@human-kit/svelte-components 1.0.0-alpha.1

package/dist/combobox/TODO.md

@@ -0,0 +1,175 @@
+# ComboBox - Code Review & TODOs
+
+Comprehensive review based on: **Accessibility**, **Scalability**, **Performance**, **Svelte 5 Runes Best Practices**.
+
+---
+
+## 🔊 Accesibilidad
+
+### Completado ✅
+
+- [x] ARIA pattern: `aria-activedescendant` para virtual focus
+- [x] `aria-expanded`, `aria-haspopup`, `aria-controls` en input
+- [x] `aria-label` en ListBox
+- [x] `role="combobox"`, `role="listbox"`, `role="option"`
+- [x] `aria-selected` en items seleccionados
+- [x] `aria-disabled` en items/placeholder deshabilitados
+- [x] Input soporta `aria-label` y `aria-labelledby` props
+- [x] ListBox tiene ID para que `aria-controls` funcione correctamente
+- [x] Button tiene `aria-controls` apuntando al listbox
+- [x] Wrapper group soporta `aria-label` y `aria-labelledby`
+- [x] Input soporta `aria-describedby` para instrucciones de uso
+
+### Pendiente
+
+- [ ] **Live regions para conteo de resultados**
+  - Agregar `<div aria-live="polite">` que anuncie "{N} resultados disponibles" al filtrar
+  - Importante para screen readers que no ven el cambio visual
+
+- [ ] **Anuncio de selección**
+  - Anunciar "Item seleccionado: {label}" cuando se selecciona
+  - Usar `aria-live="assertive"` para cambios importantes
+
+- [ ] **Soporte para grupos (sections)**
+  - Implementar `role="group"` con `aria-labelledby` para secciones
+  - Agregar `ComboBox.Section` component
+
+---
+
+## 📈 Escalabilidad
+
+### Completado ✅
+
+- [x] Hook `useVirtualFocus` reutilizable
+- [x] Controlled/uncontrolled mode
+- [x] Filtrado automático en items
+- [x] `emptyPlaceholder` reactivo
+
+### Pendiente
+
+- [ ] **`filterFn` prop customizable**
+  - Actualmente filtrado es case-insensitive includes
+  - Permitir: fuzzy search, startsWith, exact match, async search
+
+- [ ] **`allowCreate` prop**
+  - Permitir crear nuevos items cuando no hay match
+  - Callback `onCreate?: (value: string) => void`
+
+- [x] **Multiple selection UI**
+  - Chips/tags para items seleccionados ✅ `ComboBox.Tags`, `ComboBox.Tag`, `ComboBox.TagRemove`
+  - Clear all button (disponible via `clearSelection()` en context)
+  - Contador de seleccionados (disponible via `selectedValue.size`)
+  - Navegación de tags con teclado (ArrowLeft/Right, Delete/Backspace)
+  - `ComboBox.ItemIndicator` para mostrar checks en items seleccionados
+
+- [ ] **Form integration**
+  - `name` prop para `<form>` nativo
+  - Hidden input con valor serializado
+  - Validación con `required`, `aria-invalid`
+
+- [ ] **Async data support**
+  - Props: `isLoading`, `loadingPlaceholder`
+  - Callback: `onLoadMore` para infinite scroll
+  - Debounce integrado para búsqueda async
+
+- [ ] **Virtualization**
+  - Para listas grandes (>100 items)
+  - Integrar con `@tanstack/virtual` o similar
+
+---
+
+## ⚡ Performance
+
+### Completado ✅
+
+- [x] Cache de DOM queries con invalidación (`cachedItemOrder`)
+- [x] `untrack()` para evitar loops infinitos en effects
+- [x] Subscription pattern para `itemCount` reactivo
+- [x] Scoped queries via `containerRef`
+
+### Pendiente
+
+- [ ] **Memoización de `isVisible` en ListBoxItem**
+  - Actualmente se recalcula en cada render
+  - Considerar memoizar con `$derived` más granular
+
+- [ ] **Batch registration**
+  - `registerItem` se llama por cada item individualmente
+  - Para listas grandes, batch notifications
+
+- [ ] **Lazy itemLabels**
+  - El Map `itemLabels` crece con cada item
+  - Limpiar en unmount está implementado, pero considerar WeakMap
+
+- [ ] **Effect cleanup optimizations**
+  - Revisar effects que podrían consolidarse
+  - `combobox-listboxitem.svelte` tiene 2 effects que podrían ser 1
+
+---
+
+## 🔧 Svelte 5 Runes Best Practices
+
+### Completado ✅
+
+- [x] `$state` para estado reactivo
+- [x] `$derived` para valores computados
+- [x] `$effect` con cleanup functions
+- [x] `$bindable` para two-way binding
+- [x] `$props()` para destructuring
+- [x] `untrack()` para evitar re-runs innecesarios
+- [x] `$derived(expression)` en vez de `$derived(() => ...)` - Simplificado en `combobox-listboxitem.svelte`
+- [x] Effects consolidados - Usando 1 `$effect` + `onDestroy` en vez de 2 effects
+
+### Revisado - No requiere cambios
+
+- [x] **`$effect.pre`**: Revisado - no hay race conditions que lo requieran
+- [x] **Context typing**: El type único es apropiado - tree-shaking no aplica a context objects
+
+---
+
+## 🧪 Testing
+
+### Completado ✅
+
+- [x] 291 tests unitarios pasando
+- [x] Keyboard navigation tests
+- [x] Selection tests
+- [x] Filtering tests
+- [x] Empty placeholder tests
+- [x] ARIA accessibility tests (6 tests)
+- [x] Edge cases: rapid typing, whitespace, backspace
+- [x] Disabled/ReadOnly state tests
+- [x] Trigger modes (focus, input, manual)
+- [x] Selection behavior (Enter, click, Escape restoration)
+- [x] Multi-select tests (12 tests)
+- [x] Tags component tests (4 tests)
+- [x] Tag component tests (13 tests) - incluye navegación por teclado
+- [x] TagRemove component tests (6 tests)
+- [x] ItemIndicator component tests (5 tests)
+
+### Pendiente
+
+- [ ] **Tests con muchos items (100+)** - performance tests
+- [ ] **Visual regression tests** - screenshots de estados
+
+---
+
+## 📝 Documentación
+
+- [ ] **JSDoc completo**
+  - Documentar todas las props públicas
+  - Ejemplos de uso en comments
+
+- [ ] **Storybook/Demo page**
+  - Ejemplos interactivos de todos los casos de uso
+  - Estados: loading, error, disabled, readonly
+
+---
+
+## 🎯 Próximos Pasos Priorizados
+
+1. **Live regions** (accessibility - alto impacto)
+2. **Form integration** (usabilidad - casos comunes)
+3. **`filterFn` customizable** (escalabilidad)
+4. **Consolidar effects** (performance/best practices)
+5. **Async data support** (escalabilidad)

package/dist/combobox/button/combobox-button.svelte

@@ -0,0 +1,57 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLButtonAttributes } from 'svelte/elements';
+	import { useComboBoxContext } from '../root/context';
+
+	type ComboBoxButtonProps = HTMLButtonAttributes & {
+		class?: string;
+		children?: Snippet;
+	};
+
+	let { class: className, children, tabindex = -1, ...restProps }: ComboBoxButtonProps = $props();
+
+	const ctx = useComboBoxContext();
+
+	// Use onmousedown with preventDefault to prevent blur from firing
+	// before the toggle. This prevents the race condition where:
+	// 1. Click button -> blur fires -> popover closes
+	// 2. Then onclick fires -> popover opens again
+	function handleMouseDown(e: MouseEvent) {
+		e.preventDefault();
+		if (!ctx.isDisabled && !ctx.isReadOnly) {
+			ctx.toggle();
+		}
+	}
+</script>
+
+<button
+	type="button"
+	{tabindex}
+	aria-label={ctx.isOpen ? 'Close menu' : 'Open menu'}
+	aria-expanded={ctx.isOpen}
+	aria-controls={`combobox-listbox-${ctx.instanceId}`}
+	disabled={ctx.isDisabled}
+	data-pressed={ctx.isOpen}
+	onmousedown={handleMouseDown}
+	class={className}
+	{...restProps}
+>
+	{#if children}
+		{@render children()}
+	{:else}
+		<svg
+			xmlns="http://www.w3.org/2000/svg"
+			width="16"
+			height="16"
+			viewBox="0 0 24 24"
+			fill="none"
+			stroke="currentColor"
+			stroke-width="2"
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			class="transition-transform {ctx.isOpen ? 'rotate-180' : ''}"
+		>
+			<path d="m6 9 6 6 6-6" />
+		</svg>
+	{/if}
+</button>

package/dist/combobox/button/combobox-button.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Snippet } from 'svelte';
+import type { HTMLButtonAttributes } from 'svelte/elements';
+type ComboBoxButtonProps = HTMLButtonAttributes & {
+    class?: string;
+    children?: Snippet;
+};
+declare const ComboboxButton: import("svelte").Component<ComboBoxButtonProps, {}, "">;
+type ComboboxButton = ReturnType<typeof ComboboxButton>;
+export default ComboboxButton;

package/dist/combobox/index.d.ts

@@ -0,0 +1,14 @@
+export * as ComboBox from './index.parts.ts';
+export { default as ComboBoxRoot } from './root/combobox.svelte';
+export { default as ComboBoxInput } from './input/combobox-input.svelte';
+export { default as ComboBoxButton } from './button/combobox-button.svelte';
+export { default as ComboBoxPopover } from './popover/combobox-popover.svelte';
+export { default as ComboBoxList } from './list/combobox-listbox.svelte';
+export { default as ComboBoxItem } from './item/combobox-listboxitem.svelte';
+export { default as ComboBoxItemIndicator } from './item-indicator/combobox-item-indicator.svelte';
+export { default as ComboBoxTags } from './tags/combobox-tags.svelte';
+export { default as ComboBoxTag } from './tag/combobox-tag.svelte';
+export { default as ComboBoxTagRemove } from './tag-remove/combobox-tag-remove.svelte';
+export { getComboBoxContext, setComboBoxContext, useComboBoxContext, type ComboBoxContext } from './root/context.ts';
+import * as ComboBoxParts from './index.parts.ts';
+export default ComboBoxParts;

package/dist/combobox/index.js

@@ -0,0 +1,18 @@
+// Namespace export for component composition: <ComboBox.Root>, <ComboBox.Input>, etc.
+export * as ComboBox from './index.parts.ts';
+// Direct named exports for individual imports
+export { default as ComboBoxRoot } from './root/combobox.svelte';
+export { default as ComboBoxInput } from './input/combobox-input.svelte';
+export { default as ComboBoxButton } from './button/combobox-button.svelte';
+export { default as ComboBoxPopover } from './popover/combobox-popover.svelte';
+export { default as ComboBoxList } from './list/combobox-listbox.svelte';
+export { default as ComboBoxItem } from './item/combobox-listboxitem.svelte';
+export { default as ComboBoxItemIndicator } from './item-indicator/combobox-item-indicator.svelte';
+export { default as ComboBoxTags } from './tags/combobox-tags.svelte';
+export { default as ComboBoxTag } from './tag/combobox-tag.svelte';
+export { default as ComboBoxTagRemove } from './tag-remove/combobox-tag-remove.svelte';
+// Context and types
+export { getComboBoxContext, setComboBoxContext, useComboBoxContext } from './root/context.ts';
+// Default export as namespace object
+import * as ComboBoxParts from './index.parts.ts';
+export default ComboBoxParts;

package/dist/combobox/index.parts.d.ts

@@ -0,0 +1,10 @@
+export { default as Root } from './root/combobox.svelte';
+export { default as Input } from './input/combobox-input.svelte';
+export { default as Button } from './button/combobox-button.svelte';
+export { default as Popover } from './popover/combobox-popover.svelte';
+export { default as List } from './list/combobox-listbox.svelte';
+export { default as Item } from './item/combobox-listboxitem.svelte';
+export { default as ItemIndicator } from './item-indicator/combobox-item-indicator.svelte';
+export { default as Tags } from './tags/combobox-tags.svelte';
+export { default as Tag } from './tag/combobox-tag.svelte';
+export { default as TagRemove } from './tag-remove/combobox-tag-remove.svelte';

package/dist/combobox/index.parts.js

@@ -0,0 +1,11 @@
+// Short alias exports for namespace usage: ComboBox.Root, ComboBox.Input, etc.
+export { default as Root } from './root/combobox.svelte';
+export { default as Input } from './input/combobox-input.svelte';
+export { default as Button } from './button/combobox-button.svelte';
+export { default as Popover } from './popover/combobox-popover.svelte';
+export { default as List } from './list/combobox-listbox.svelte';
+export { default as Item } from './item/combobox-listboxitem.svelte';
+export { default as ItemIndicator } from './item-indicator/combobox-item-indicator.svelte';
+export { default as Tags } from './tags/combobox-tags.svelte';
+export { default as Tag } from './tag/combobox-tag.svelte';
+export { default as TagRemove } from './tag-remove/combobox-tag-remove.svelte';

package/dist/combobox/input/combobox-input.svelte

@@ -0,0 +1,98 @@
+<script lang="ts">
+	import type { HTMLInputAttributes } from 'svelte/elements';
+	import { useComboBoxContext } from '../root/context';
+	import { cn } from '../../utils/cn';
+
+	type ComboBoxInputProps = HTMLInputAttributes & {
+		/** Accessible label for the input */
+		'aria-label'?: string;
+		/** ID of element that labels this input */
+		'aria-labelledby'?: string;
+		/** ID of element that describes this input (e.g., usage instructions) */
+		'aria-describedby'?: string;
+		class?: string;
+	};
+
+	let {
+		'aria-label': ariaLabel,
+		'aria-labelledby': ariaLabelledby,
+		'aria-describedby': ariaDescribedby,
+		class: className,
+		...restProps
+	}: ComboBoxInputProps = $props();
+
+	let inputRef: HTMLInputElement | null = $state(null);
+	const ctx = useComboBoxContext();
+
+	$effect(() => {
+		if (inputRef) {
+			ctx.setInputRef(inputRef);
+			ctx.setTriggerRef(inputRef);
+		}
+	});
+
+	function handleInput(event: Event) {
+		ctx.setFocusedTagId(null);
+		const target = event.target as HTMLInputElement;
+		ctx.setInputValue(target.value);
+		// Open on input for all trigger modes when user types
+		if (!ctx.isOpen && target.value.length > 0) {
+			ctx.open();
+		}
+	}
+
+	function handleFocus() {
+		// Open on focus if trigger is 'focus'
+		// Use a small delay to avoid opening immediately on programmatic focus
+		// (e.g., from a focus trap). This gives time for refs to be set up.
+		if (ctx.trigger === 'focus' && !ctx.isOpen) {
+			requestAnimationFrame(() => {
+				if (ctx.trigger === 'focus' && !ctx.isOpen) {
+					ctx.open();
+				}
+			});
+		}
+	}
+
+	function handleMouseDown() {
+		ctx.setFocusedTagId(null);
+		// Open on press if trigger is 'press'
+		if (ctx.trigger === 'press' && !ctx.isOpen && !ctx.isDisabled && !ctx.isReadOnly) {
+			ctx.open();
+		}
+	}
+
+	function handleBlur() {
+		// Restore selection label or deselect if empty
+		ctx.handleInputBlur();
+	}
+</script>
+
+<input
+	bind:this={inputRef}
+	type="text"
+	role="combobox"
+	aria-autocomplete="list"
+	aria-expanded={ctx.isOpen}
+	aria-haspopup="listbox"
+	aria-controls={`combobox-listbox-${ctx.instanceId}`}
+	aria-activedescendant={ctx.focusedItemId !== null
+		? `combobox-item-${ctx.instanceId}-${ctx.focusedItemId}`
+		: undefined}
+	aria-label={ariaLabel}
+	aria-labelledby={ariaLabelledby}
+	aria-describedby={ariaDescribedby}
+	value={ctx.displayValue}
+	disabled={ctx.isDisabled}
+	readonly={ctx.isReadOnly}
+	oninput={handleInput}
+	onfocus={handleFocus}
+	onmousedown={handleMouseDown}
+	onblur={handleBlur}
+	onkeydown={ctx.handleKeydown}
+	class={cn(
+		'bg-depth-2 sunken placeholder:text-muted-foreground hover:bg-depth-1 focus:ring-border h-8 w-full rounded-xs border px-2 text-sm shadow-xs transition-all ease-out outline-none focus:ring focus:ring-offset-1 disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50',
+		className
+	)}
+	{...restProps}
+/>

package/dist/combobox/input/combobox-input.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { HTMLInputAttributes } from 'svelte/elements';
+type ComboBoxInputProps = HTMLInputAttributes & {
+    /** Accessible label for the input */
+    'aria-label'?: string;
+    /** ID of element that labels this input */
+    'aria-labelledby'?: string;
+    /** ID of element that describes this input (e.g., usage instructions) */
+    'aria-describedby'?: string;
+    class?: string;
+};
+declare const ComboboxInput: import("svelte").Component<ComboBoxInputProps, {}, "">;
+type ComboboxInput = ReturnType<typeof ComboboxInput>;
+export default ComboboxInput;

package/dist/combobox/item/combobox-item-implicit-text-test.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+	import { ComboBox } from '../index';
+
+	let selected = $state<string | number | undefined>();
+</script>
+
+<ComboBox.Root bind:value={selected}>
+	<ComboBox.Input placeholder="Search countries..." />
+	<ComboBox.Button />
+
+	<ComboBox.Popover>
+		<ComboBox.List emptyPlaceholder="No countries found">
+			<!-- Intentionally omit textValue to validate implicit text extraction -->
+			<ComboBox.Item id="ar">Argentina</ComboBox.Item>
+			<ComboBox.Item id="br">Brazil</ComboBox.Item>
+			<ComboBox.Item id="ca">Canada</ComboBox.Item>
+		</ComboBox.List>
+	</ComboBox.Popover>
+</ComboBox.Root>
+
+<div data-testid="selected">{selected ?? ''}</div>

package/dist/combobox/item/combobox-item-implicit-text-test.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const ComboboxItemImplicitTextTest: import("svelte").Component<Record<string, never>, {}, "">;
+type ComboboxItemImplicitTextTest = ReturnType<typeof ComboboxItemImplicitTextTest>;
+export default ComboboxItemImplicitTextTest;

package/dist/combobox/item/combobox-listboxitem.svelte

@@ -0,0 +1,136 @@
+<script lang="ts" module>
+	export const COMBOBOX_ITEM_CONTEXT_KEY = Symbol.for('combobox-item');
+
+	export type ComboBoxItemContext = {
+		id: string | number;
+	};
+</script>
+
+<script lang="ts">
+	import type { ComponentProps } from 'svelte';
+	import { untrack, onDestroy, setContext } from 'svelte';
+	import ListBoxItem from '../../listbox/item/listbox-item.svelte';
+	import { useComboBoxContext } from '../root/context';
+	import { cn } from '../../utils/cn';
+
+	/**
+	 * ComboBox.ListBoxItem wraps ListBox.Item and provides ComboBox-specific behavior:
+	 * - Virtual focus (aria-activedescendant pattern)
+	 * - Unique ID with instanceId for multiple comboboxes
+	 * - Registration with ComboBox context for navigation
+	 * - Scroll on focus for keyboard navigation
+	 * - Automatic filtering based on inputValue
+	 */
+	type ComboBoxListBoxItemProps = Omit<
+		ComponentProps<typeof ListBoxItem>,
+		// Internal override props that ComboBox.ListBoxItem controls
+		| 'customId'
+		| 'disableFocusHandling'
+		| 'isFocusedOverride'
+		| 'onItemSelect'
+		| 'onResolvedTextValue'
+		| 'scrollOnFocus'
+		| 'isParentDisabled'
+	>;
+
+	let { id, class: className, ...props }: ComboBoxListBoxItemProps = $props();
+
+	const ctx = useComboBoxContext();
+
+	// Provide item context for child components like ItemIndicator
+	setContext<ComboBoxItemContext>(COMBOBOX_ITEM_CONTEXT_KEY, {
+		get id() {
+			return id;
+		}
+	});
+
+	// Text value for filtering and display.
+	// If textValue prop is omitted, resolve it from rendered content on mount.
+	let resolvedTextValue = $state<string | null>(props.textValue ?? null);
+	const effectiveTextValue = $derived(resolvedTextValue ?? '');
+
+	$effect(() => {
+		if (props.textValue !== undefined) {
+			resolvedTextValue = props.textValue;
+		}
+	});
+
+	// Normalized input for filtering comparison
+	const normalizedInput = $derived(ctx.inputValue.trim().toLowerCase());
+
+	// Automatic filtering: if text is not resolved yet, keep item visible until mount resolves it.
+	const isVisible = $derived(
+		!normalizedInput ||
+			!effectiveTextValue ||
+			effectiveTextValue.toLowerCase().includes(normalizedInput)
+	);
+
+	// Virtual focus from ComboBox context
+	const isFocused = $derived(ctx.focusedItemId === id);
+
+	// Generate unique ID using instanceId
+	const uniqueId = $derived(`combobox-item-${ctx.instanceId}-${id}`);
+
+	// Track registration state to avoid re-registering
+	let isRegistered = $state(false);
+
+	// Reactive registration: register when visible, unregister when hidden
+	$effect(() => {
+		const visible = isVisible;
+		const label = effectiveTextValue || String(id);
+		const itemId = id;
+
+		untrack(() => {
+			if (visible && !isRegistered) {
+				ctx.registerItem(itemId, label);
+				isRegistered = true;
+			} else if (!visible && isRegistered) {
+				ctx.unregisterItem(itemId);
+				isRegistered = false;
+			}
+		});
+	});
+
+	function handleResolvedTextValue(label: string) {
+		if (!label) return;
+		resolvedTextValue = label;
+		// Update label map when already registered.
+		if (isRegistered) {
+			ctx.registerItem(id, label);
+		}
+	}
+
+	// Cleanup on component destroy - use onDestroy for clearer semantics
+	onDestroy(() => {
+		if (isRegistered) {
+			ctx.unregisterItem(id);
+		}
+	});
+
+	// Custom select handler that uses ComboBox context
+	function handleSelect(itemId: string | number, label: string) {
+		ctx.select(itemId, label);
+	}
+</script>
+
+{#if isVisible}
+	<ListBoxItem
+		{id}
+		{...props}
+		textValue={props.textValue}
+		customId={uniqueId}
+		disableFocusHandling={true}
+		isFocusedOverride={isFocused}
+		onItemSelect={handleSelect}
+		onResolvedTextValue={handleResolvedTextValue}
+		scrollOnFocus={true}
+		isParentDisabled={ctx.isDisabled}
+		class={cn(
+			'cursor-pointer px-3 py-2 transition-colors outline-none',
+			'data-focused:bg-accent data-hovered:bg-accent',
+			'data-selected:bg-primary/10 data-selected:font-medium',
+			'data-disabled:pointer-events-none data-disabled:opacity-50',
+			className
+		)}
+	/>
+{/if}

package/dist/combobox/item/combobox-listboxitem.svelte.d.ts

@@ -0,0 +1,18 @@
+export declare const COMBOBOX_ITEM_CONTEXT_KEY: unique symbol;
+export type ComboBoxItemContext = {
+    id: string | number;
+};
+import type { ComponentProps } from 'svelte';
+import ListBoxItem from '../../listbox/item/listbox-item.svelte';
+/**
+ * ComboBox.ListBoxItem wraps ListBox.Item and provides ComboBox-specific behavior:
+ * - Virtual focus (aria-activedescendant pattern)
+ * - Unique ID with instanceId for multiple comboboxes
+ * - Registration with ComboBox context for navigation
+ * - Scroll on focus for keyboard navigation
+ * - Automatic filtering based on inputValue
+ */
+type ComboBoxListBoxItemProps = Omit<ComponentProps<typeof ListBoxItem>, 'customId' | 'disableFocusHandling' | 'isFocusedOverride' | 'onItemSelect' | 'onResolvedTextValue' | 'scrollOnFocus' | 'isParentDisabled'>;
+declare const ComboboxListboxitem: import("svelte").Component<ComboBoxListBoxItemProps, {}, "">;
+type ComboboxListboxitem = ReturnType<typeof ComboboxListboxitem>;
+export default ComboboxListboxitem;

package/dist/combobox/item-indicator/combobox-item-indicator.svelte

@@ -0,0 +1,63 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { getContext } from 'svelte';
+	import { cn } from '../../utils/cn';
+	import { useComboBoxContext } from '../root/context';
+	import {
+		COMBOBOX_ITEM_CONTEXT_KEY,
+		type ComboBoxItemContext
+	} from '../item/combobox-listboxitem.svelte';
+
+	/**
+	 * ComboBox.ItemIndicator - Visual indicator shown when an item is selected.
+	 * Must be used inside ComboBox.Item.
+	 * Only renders when the parent item is selected.
+	 */
+	type ComboBoxItemIndicatorProps = {
+		/** Content to render when selected (defaults to checkmark icon) */
+		children?: Snippet;
+		/** Force show the indicator regardless of selection state */
+		forceMount?: boolean;
+		class?: string;
+	} & Omit<HTMLAttributes<HTMLSpanElement>, 'class' | 'children'>;
+
+	let {
+		children,
+		forceMount = false,
+		class: className,
+		...restProps
+	}: ComboBoxItemIndicatorProps = $props();
+
+	const comboboxCtx = useComboBoxContext();
+	const itemCtx = getContext<ComboBoxItemContext>(COMBOBOX_ITEM_CONTEXT_KEY);
+
+	const isSelected = $derived(comboboxCtx.selectedValue.has(itemCtx.id));
+	const shouldRender = $derived(forceMount || isSelected);
+</script>
+
+{#if shouldRender}
+	<span
+		aria-hidden="true"
+		data-state={isSelected ? 'checked' : 'unchecked'}
+		class={cn('inline-flex items-center justify-center', className)}
+		{...restProps}
+	>
+		{#if children}
+			{@render children()}
+		{:else}
+			<svg
+				xmlns="http://www.w3.org/2000/svg"
+				viewBox="0 0 16 16"
+				fill="currentColor"
+				class="h-4 w-4"
+			>
+				<path
+					fill-rule="evenodd"
+					d="M12.416 3.376a.75.75 0 0 1 .208 1.04l-5 7.5a.75.75 0 0 1-1.154.114l-3-3a.75.75 0 0 1 1.06-1.06l2.353 2.353 4.493-6.74a.75.75 0 0 1 1.04-.207Z"
+					clip-rule="evenodd"
+				/>
+			</svg>
+		{/if}
+	</span>
+{/if}

package/dist/combobox/item-indicator/combobox-item-indicator.svelte.d.ts

@@ -0,0 +1,17 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+/**
+ * ComboBox.ItemIndicator - Visual indicator shown when an item is selected.
+ * Must be used inside ComboBox.Item.
+ * Only renders when the parent item is selected.
+ */
+type ComboBoxItemIndicatorProps = {
+    /** Content to render when selected (defaults to checkmark icon) */
+    children?: Snippet;
+    /** Force show the indicator regardless of selection state */
+    forceMount?: boolean;
+    class?: string;
+} & Omit<HTMLAttributes<HTMLSpanElement>, 'class' | 'children'>;
+declare const ComboboxItemIndicator: import("svelte").Component<ComboBoxItemIndicatorProps, {}, "">;
+type ComboboxItemIndicator = ReturnType<typeof ComboboxItemIndicator>;
+export default ComboboxItemIndicator;