From f06867ad75777c2f7c1df5ea5e068000088968bb Mon Sep 17 00:00:00 2001
From: Elijah Duffy <elijah@thatoneguy.ca>
Date: Mon, 9 Mar 2026 16:37:02 -0700
Subject: [PATCH] combobox: rough option snippets implementation

---
 src/lib/Combobox.svelte | 110 ++++++++++++++++++++++++++++++++++------
 src/routes/+page.svelte |  24 ++++++++-
 2 files changed, 118 insertions(+), 16 deletions(-)

diff --git a/src/lib/Combobox.svelte b/src/lib/Combobox.svelte
index 9d1c1d5..86a0a46 100644
--- a/src/lib/Combobox.svelte
+++ b/src/lib/Combobox.svelte
@@ -1,12 +1,49 @@
 <script lang="ts" module>
 	export type ComboboxOption = {
+		/** Value of the option */
 		value: string;
+		/**
+		 * Label of the option displayed in the picker and, if the option is
+		 * selected, in the main input field (unless preview overrides it during
+		 * combobox open state).
+		 */
 		label?: string;
-		infotext?: string;
-		preview?: string;
-		disabled?: boolean;
-		icon?: Snippet<[item: ComboboxOption]>;
+		/**
+		 * An optional custom render function for the option, receives the
+		 * option as an argument and is used in the picker instead of the
+		 * label if provided. Note that label should still be provided even
+		 * if render is used, as it's used for search and accessibility.
+		 */
 		render?: Snippet<[item: ComboboxOption]>;
+		/**
+		 * Additional information text for the option, displayed beside the
+		 * label in the picker and, if the option is selected, in the main
+		 * input field.
+		 */
+		infotext?: string;
+		/**
+		 * Snippet override for infotext, receives the option as an argument.
+		 * Note that infotext should still be provided even if infotextRender
+		 * is used, as it's used for search and accessibility.
+		 */
+		infotextRender?: Snippet<[item: ComboboxOption]>;
+		/**
+		 * Preview text for the option, displayed in the picker and, if the
+		 * option is selected and the combobox is open, in the main input field.
+		 */
+		preview?: string;
+		/**
+		 * Snippet override for the preview text, receives the option as an
+		 * argument. Note that preview should still be provided even if
+		 * previewRender is used, as it's used for search and accessibility.
+		 */
+		previewRender?: Snippet<[item: ComboboxOption]>;
+		/** Whether the option is disabled */
+		disabled?: boolean;
+		/** An optional icon for the option, displayed in the picker and,
+		 * if the option is selected, in the closed combobox.
+		 */
+		icon?: Snippet<[item: ComboboxOption]> | IconDef;
 	};
 
 	const getLabel = (item: ComboboxOption | undefined): string => item?.label ?? item?.value ?? '';
@@ -54,6 +91,11 @@
 		/** allows the user to select an option without selecting a value (events are still triggered) */
 		stateless?: boolean;
 		notFoundMessage?: string;
+		/**
+		 * Configures which option fields are included in the search
+		 * (default: 'label' and 'value').
+		 */
+		searchKeys?: ('label' | 'value' | 'preview' | 'infotext')[];
 		class?: ClassValue | null | undefined;
 		use?: () => void;
 		onvalidate?: (e: InputValidatorEvent) => void;
@@ -83,6 +125,7 @@
 		compact = false,
 		stateless = false,
 		notFoundMessage = 'No results found',
+		searchKeys = ['label', 'value'],
 		class: classValue,
 		use,
 		onvalidate,
@@ -106,6 +149,12 @@
 	let searchContainer = $state<HTMLDivElement | null>(null);
 	let pickerContainer = $state<HTMLDivElement | null>(null);
 
+	// TODO: finish adding support for dynamic search fields
+	// TODO: finish documenting props
+	// TODO: properly support paginated options???
+	// TODO: there's something weird with dropdown placement on narrow screens
+	// TODO: match width to input isn't working properly for vconf selectors
+
 	/** stores options filtered according to search value */
 	const filteredItems = $derived.by(() => {
 		const arr = matchSorter(options, searchValue, { keys: [(item) => getLabel(item)] });
@@ -365,6 +414,7 @@
 <!-- Combobox picker -->
 <Portal target="body">
 	{#if open}
+		<!-- Picker container -->
 		<div
 			class={[
 				'picker absolute top-0 left-0 z-50 overflow-y-auto px-2 py-3',
@@ -397,6 +447,7 @@
 			tabindex="0"
 		>
 			{#each filteredItems as item, i (item.value)}
+				<!-- Option container -->
 				<div
 					data-id={item.value}
 					aria-selected={value?.value === item.value}
@@ -421,24 +472,24 @@
 					onkeydown={() => {}}
 					tabindex="-1"
 				>
+					<!-- Option icon -->
 					{#if item.icon}
-						{@render item.icon(item)}
+						{@render optionIconOrIconDef(item)}
 					{/if}
 
+					<!-- Option label / `render` snippet -->
 					<div class={['mr-8', item.icon && 'ml-2']}>
-						{#if item.render}
-							{@render item.render(item)}
-						{:else}
-							{getLabel(item)}
-						{/if}
+						{@render snippetOrString(item, item.render || getLabel(item))}
 					</div>
 
-					{#if item?.infotext}
+					<!-- Option infotext / `infotextRender` snippet (always right-aligned) -->
+					{#if item.infotext || item.infotextRender}
 						<div class="text-sui-text/80 dark:text-sui-background/80 ml-auto text-sm">
-							{item.infotext}
+							{@render snippetOrString(item, item.infotextRender || item.infotext)}
 						</div>
 					{/if}
 
+					<!-- Option checkmark, visible if selected -->
 					{#if value?.value === item.value}
 						<div class={[item?.infotext ? 'ml-2' : 'ml-auto']}>
 							<Check />
@@ -446,6 +497,7 @@
 					{/if}
 				</div>
 			{:else}
+				<!-- Display loading state or not found if no options available -->
 				<span class="block px-5 py-2 text-sm">
 					{#if loading}
 						Loading...
@@ -458,6 +510,7 @@
 	{/if}
 </Portal>
 
+<!-- Combobox persistant container -->
 <div class={classValue}>
 	<!-- Combobox Label -->
 	{#if label}
@@ -493,6 +546,7 @@
 <!-- Search input box -->
 {#snippet searchInputBox(caret: boolean = true)}
 	<div class="relative">
+		<!-- Persistant OR selected option icon, if visible -->
 		{#if iconVisible}
 			<div
 				class={[
@@ -505,9 +559,9 @@
 				{#if loading}
 					<Spinner class="stroke-sui-accent! -mt-0.5" size="1em" />
 				{:else if useHighlighted && highlighted?.icon}
-					{@render highlighted.icon(highlighted)}
+					{@render optionIconOrIconDef(highlighted)}
 				{:else if value?.icon}
-					{@render value.icon(value)}
+					{@render optionIconOrIconDef(value)}
 				{:else if icon}
 					<icon.component {...icon.props} />
 				{:else}
@@ -516,6 +570,7 @@
 			</div>
 		{/if}
 
+		<!-- Combobox input box -->
 		<StyledRawInput
 			style={iconWidth && iconVisible ? `padding-left: ${iconWidth + 14 + 10}px` : undefined}
 			class={[caret && 'pr-9', !valid && 'border-red-500!']}
@@ -578,7 +633,8 @@
 			}}
 		/>
 
-		{#if (value && value.infotext) || (highlighted && useHighlighted && highlighted.infotext)}
+		<!-- Right-aligned infotext (overlay) -->
+		{#if (value && (value.infotext || value.infotextRender)) || (highlighted && useHighlighted && (highlighted.infotext || highlighted.infotextRender))}
 			<div
 				class={[
 					'pointer-events-none absolute top-1/2 -translate-y-1/2 transform text-sm select-none',
@@ -587,6 +643,11 @@
 				]}
 			>
 				{useHighlighted && highlighted?.infotext ? highlighted.infotext : value?.infotext}
+				{#if useHighlighted && (highlighted?.infotext || highlighted?.infotextRender)}
+					{@render snippetOrString(highlighted!, highlighted.infotextRender)}
+				{:else if value?.infotext}
+					{@render snippetOrString(value, value.infotextRender)}
+				{/if}
 			</div>
 		{/if}
 
@@ -602,6 +663,25 @@
 	</div>
 {/snippet}
 
+{#snippet optionIconOrIconDef(opt: ComboboxOption | undefined)}
+	{#if typeof opt?.icon === 'function'}
+		{@render opt.icon(opt)}
+	{:else if opt?.icon}
+		<opt.icon.component {...opt.icon.props} />
+	{/if}
+{/snippet}
+
+{#snippet snippetOrString(
+	opt: ComboboxOption,
+	value: string | Snippet<[item: ComboboxOption]> | undefined
+)}
+	{#if typeof value === 'function'}
+		{@render value(opt)}
+	{:else}
+		{value}
+	{/if}
+{/snippet}
+
 <style lang="postcss">
 	@reference "./styles/reference.css";
 
diff --git a/src/routes/+page.svelte b/src/routes/+page.svelte
index a7fd585..3a3810e 100644
--- a/src/routes/+page.svelte
+++ b/src/routes/+page.svelte
@@ -164,6 +164,16 @@
 	</div>
 </div>
 
+{#snippet comboRender(item: ComboboxOption)}
+	Opt 1
+{/snippet}
+{#snippet comboInfotext(item: ComboboxOption)}
+	User
+{/snippet}
+{#snippet comboPreview(item: ComboboxOption)}
+	Preview {item.label}
+{/snippet}
+
 <div class="component">
 	<p class="title">Combobox</p>
 
@@ -172,7 +182,19 @@
 			name="example-combobox"
 			label="Select an option"
 			placeholder="Choose..."
-			options={comboboxOptions}
+			options={[
+				{
+					value: 'option1',
+					label: 'Option 1',
+					preview: 'Prvw',
+					infotext: 'Info',
+					render: comboRender,
+					infotextRender: comboInfotext,
+					previewRender: comboPreview
+				},
+				{ value: 'option2', label: 'Option 2' },
+				{ value: 'option3', label: 'Option 3', disabled: true }
+			]}
 			onchange={(e) => console.log('Selected:', e.value)}
 			onvalidate={(e) => console.log('Validation:', e.detail)}
 		/>