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

package/dist/combobox/TODO.md

@@ -1,175 +1,28 @@
-# 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)
+# Combobox TODO
+
+## Goal
+
+Track Combobox work with a single mandatory TODO format.
+
+## Backlog
+
+- [x] [M][P0][Area: Architecture][Owner: Unassigned][Target: Done] Build base component parts (`root`, `input`, `list`, `item`).
+- [x] [M][P0][Area: State][Owner: Unassigned][Target: Done] Implement open/close state management on root.
+- [x] [M][P0][Area: Filtering][Owner: Unassigned][Target: Done] Support filtering items by input value.
+- [x] [M][P0][Area: Selection][Owner: Unassigned][Target: Done] Implement item selection and emit `onSelectionChange`.
+- [x] [M][P0][Area: Accessibility][Owner: Unassigned][Target: Done] Add keyboard navigation and ARIA combobox/listbox semantics.
+- [x] [M][P0][Area: Interaction][Owner: Unassigned][Target: Done] Handle outside click and blur to close list.
+- [x] [M][P0][Area: States][Owner: Unassigned][Target: Done] Support disabled state for root and items.
+- [x] [M][P0][Area: Testing][Owner: Unassigned][Target: Done] Add baseline browser tests for open/filter/select behavior.
+- [x] [S][P1][Area: API][Owner: Unassigned][Target: Done] Support controlled/uncontrolled selected value.
+- [x] [M][P0][Area: Selection][Owner: Unassigned][Target: Done] Implement `supportsMultiple` mode with chips and remove action.
+- [x] [M][P0][Area: Data Model][Owner: Unassigned][Target: Done] Support rich object values and hidden input synchronization.
+- [x] [M][P0][Area: UX][Owner: Unassigned][Target: Done] Support loading, empty, and custom-value flows.
+- [x] [M][P0][Area: Focus][Owner: Unassigned][Target: Done] Align focus-visible behavior with shared input modality primitive.
+- [ ] [S][P1][Area: Data Source][Owner: Unassigned][Target: TBD] Add async item provider API (debounced remote filtering).
+- [ ] [S][P1][Area: Data Model][Owner: Unassigned][Target: TBD] Add grouped items with section headers.
+- [ ] [S][P1][Area: Performance][Owner: Unassigned][Target: TBD] Add optional virtualization for large datasets.
+- [ ] [S][P1][Area: Interaction][Owner: Unassigned][Target: TBD] Add option to commit free-text value on blur.
+- [ ] [S][P1][Area: API][Owner: Unassigned][Target: TBD] Add imperative focus/open API for advanced integrations.
+- [ ] [C][P2][Area: UX][Owner: Unassigned][Target: TBD] Add built-in highlighting helper for matched text.
+- [ ] [C][P2][Area: Performance][Owner: Unassigned][Target: TBD] Add benchmark tests for filtering and keyboard navigation.

package/dist/combobox/button/README.md

@@ -0,0 +1,20 @@
+# ComboBox Button
+
+## API reference
+
+### ComboBox.Button
+
+Name: `ComboBox.Button`  
+Description: Compatibility alias for `ComboBox.Trigger`.
+
+| Prop           | Type                   | Default     | Description                                                     |
+| -------------- | ---------------------- | ----------- | --------------------------------------------------------------- |
+| `class`        | `string`               | `undefined` | CSS class names for the trigger element.                        |
+| `children`     | `Snippet`              | `undefined` | Custom trigger content. If omitted, a chevron icon is rendered. |
+| `tabindex`     | `number`               | `-1`        | Tab index applied to the trigger button.                        |
+| `...restProps` | `HTMLButtonAttributes` | `-`         | Additional native button attributes.                            |
+
+## Notes
+
+- Prefer `ComboBox.Trigger` in new code.
+- `ComboBox.Button` forwards all props and behavior to `ComboBox.Trigger`.

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

@@ -0,0 +1,27 @@
+<script lang="ts">
+	import ComboBox from '../index.js';
+
+	type Props = {
+		isPending?: boolean;
+	};
+
+	let { isPending = false }: Props = $props();
+
+	const countries = [
+		{ id: 'ar', name: 'Argentina' },
+		{ id: 'br', name: 'Brazil' }
+	];
+</script>
+
+<ComboBox.Root {isPending}>
+	<ComboBox.Input placeholder="Search countries..." />
+	<ComboBox.Button />
+
+	<ComboBox.Popover>
+		<ComboBox.List emptyPlaceholder="No countries found">
+			{#each countries as country (country.id)}
+				<ComboBox.Item id={country.id} textValue={country.name}>{country.name}</ComboBox.Item>
+			{/each}
+		</ComboBox.List>
+	</ComboBox.Popover>
+</ComboBox.Root>

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

@@ -0,0 +1,6 @@
+type Props = {
+    isPending?: boolean;
+};
+declare const ComboboxButtonTest: import("svelte").Component<Props, {}, "">;
+type ComboboxButtonTest = ReturnType<typeof ComboboxButtonTest>;
+export default ComboboxButtonTest;

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

@@ -1,6 +1,7 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
 	import type { HTMLButtonAttributes } from 'svelte/elements';
+	import { ButtonRoot } from '../../button/index.js';
 	import { useComboBoxContext } from '../root/context';
 
 	type ComboBoxButtonProps = HTMLButtonAttributes & {
@@ -11,27 +12,25 @@
 	let { class: className, children, tabindex = -1, ...restProps }: ComboBoxButtonProps = $props();
 
 	const ctx = useComboBoxContext();
+	const isButtonDisabled = $derived(ctx.isDisabled || ctx.isReadOnly || ctx.isPending);
 
-	// 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) {
+	function handleMouseDown(event: MouseEvent) {
+		event.preventDefault();
+		if (!isButtonDisabled) {
 			ctx.toggle();
 		}
 	}
 </script>
 
-<button
+<ButtonRoot
 	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}
+	isDisabled={ctx.isDisabled || ctx.isReadOnly}
+	isPending={ctx.isPending}
+	pressed={ctx.isOpen}
 	onmousedown={handleMouseDown}
 	class={className}
 	{...restProps}
@@ -54,4 +53,4 @@
 			<path d="m6 9 6 6 6-6" />
 		</svg>
 	{/if}
-</button>
+</ButtonRoot>

package/dist/combobox/clear/README.md

@@ -0,0 +1,21 @@
+# ComboBox Clear
+
+## API reference
+
+### ComboBox.Clear
+
+Name: `ComboBox.Clear`  
+Description: Optional clear button that resets the input value and clears the current selection without stealing focus from the input.
+
+| Prop           | Type                   | Default     | Description                                                |
+| -------------- | ---------------------- | ----------- | ---------------------------------------------------------- |
+| `class`        | `string`               | `undefined` | CSS class names for the clear element.                     |
+| `children`     | `Snippet`              | `undefined` | Custom clear content. If omitted, an “x” icon is rendered. |
+| `tabindex`     | `number`               | `-1`        | Tab index applied to the clear button.                     |
+| `...restProps` | `HTMLButtonAttributes` | `-`         | Additional native button attributes.                       |
+
+## Notes
+
+- `ComboBox.Clear` clears both the visible input text and the selected value(s).
+- The clear button is disabled when there is nothing to clear, or when the combobox is disabled, read-only, or pending.
+- Clicking the clear button keeps focus on the combobox input.

package/dist/combobox/clear/combobox-clear-test.svelte

@@ -0,0 +1,34 @@
+<script lang="ts">
+	import ComboBox from '../index.js';
+
+	let value = $state<string | number | undefined>('ar');
+	let inputValue = $state('Argentina');
+	let isPending = $state(false);
+
+	const countries = [
+		{ id: 'ar', name: 'Argentina' },
+		{ id: 'br', name: 'Brazil' },
+		{ id: 'ca', name: 'Canada' }
+	];
+</script>
+
+<ComboBox.Root bind:value bind:inputValue {isPending}>
+	<div class="flex gap-1">
+		<ComboBox.Input placeholder="Search countries..." />
+		<ComboBox.Clear />
+		<ComboBox.Trigger />
+	</div>
+
+	<ComboBox.Popover>
+		<ComboBox.List emptyPlaceholder="No countries found">
+			{#each countries as country (country.id)}
+				<ComboBox.Item id={country.id} textValue={country.name}>{country.name}</ComboBox.Item>
+			{/each}
+		</ComboBox.List>
+	</ComboBox.Popover>
+</ComboBox.Root>
+
+<button type="button" data-set-pending onclick={() => (isPending = true)}>Set pending</button>
+<button type="button" data-clear-pending onclick={() => (isPending = false)}>Clear pending</button>
+<output data-selected-value>{value === undefined ? 'undefined' : String(value)}</output>
+<output data-input-value>{inputValue}</output>

package/dist/combobox/clear/combobox-clear-test.svelte.d.ts

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

package/dist/combobox/clear/combobox-clear.svelte

@@ -0,0 +1,61 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLButtonAttributes } from 'svelte/elements';
+	import { ButtonRoot } from '../../button/index.js';
+	import { useComboBoxContext } from '../root/context';
+
+	type ComboBoxClearProps = HTMLButtonAttributes & {
+		class?: string;
+		children?: Snippet;
+	};
+
+	let { class: className, children, tabindex = -1, ...restProps }: ComboBoxClearProps = $props();
+
+	const ctx = useComboBoxContext();
+	const hasContent = $derived(ctx.displayValue.trim().length > 0 || ctx.selectedValue.size > 0);
+	const isClearDisabled = $derived(
+		ctx.isDisabled || ctx.isReadOnly || ctx.isPending || !hasContent
+	);
+	const ariaLabel = $derived(ctx.selectedValue.size > 0 ? 'Clear selection' : 'Clear input');
+
+	function handleMouseDown(event: MouseEvent) {
+		event.preventDefault();
+	}
+
+	function handleClick() {
+		if (isClearDisabled) return;
+		ctx.clearSelection();
+		ctx.inputRef?.focus();
+	}
+</script>
+
+<ButtonRoot
+	type="button"
+	{tabindex}
+	aria-label={ariaLabel}
+	isDisabled={ctx.isDisabled || ctx.isReadOnly || !hasContent}
+	isPending={ctx.isPending}
+	onmousedown={handleMouseDown}
+	onclick={handleClick}
+	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"
+		>
+			<path d="M18 6 6 18" />
+			<path d="m6 6 12 12" />
+		</svg>
+	{/if}
+</ButtonRoot>

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

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

package/dist/combobox/index.d.ts

@@ -1,7 +1,9 @@
-export * as ComboBox from './index.parts.ts';
+export * as ComboBox from './index.parts.js';
 export { default as ComboBoxRoot } from './root/combobox.svelte';
 export { default as ComboBoxInput } from './input/combobox-input.svelte';
+export { default as ComboBoxTrigger } from './trigger/combobox-trigger.svelte';
 export { default as ComboBoxButton } from './button/combobox-button.svelte';
+export { default as ComboBoxClear } from './clear/combobox-clear.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';
@@ -9,6 +11,6 @@ export { default as ComboBoxItemIndicator } from './item-indicator/combobox-item
 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 { getComboBoxContext, setComboBoxContext, useComboBoxContext, type ComboBoxContext } from './root/context.js';
+import * as ComboBoxParts from './index.parts.js';
 export default ComboBoxParts;

package/dist/combobox/index.js

@@ -1,9 +1,11 @@
 // Namespace export for component composition: <ComboBox.Root>, <ComboBox.Input>, etc.
-export * as ComboBox from './index.parts.ts';
+export * as ComboBox from './index.parts.js';
 // 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 ComboBoxTrigger } from './trigger/combobox-trigger.svelte';
 export { default as ComboBoxButton } from './button/combobox-button.svelte';
+export { default as ComboBoxClear } from './clear/combobox-clear.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';
@@ -12,7 +14,7 @@ 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';
+export { getComboBoxContext, setComboBoxContext, useComboBoxContext } from './root/context.js';
 // Default export as namespace object
-import * as ComboBoxParts from './index.parts.ts';
+import * as ComboBoxParts from './index.parts.js';
 export default ComboBoxParts;

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

@@ -1,6 +1,8 @@
 export { default as Root } from './root/combobox.svelte';
 export { default as Input } from './input/combobox-input.svelte';
+export { default as Trigger } from './trigger/combobox-trigger.svelte';
 export { default as Button } from './button/combobox-button.svelte';
+export { default as Clear } from './clear/combobox-clear.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';

package/dist/combobox/index.parts.js

@@ -1,7 +1,9 @@
 // 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 Trigger } from './trigger/combobox-trigger.svelte';
 export { default as Button } from './button/combobox-button.svelte';
+export { default as Clear } from './clear/combobox-clear.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';

package/dist/combobox/input/README.md

@@ -0,0 +1,16 @@
+# ComboBox Input
+
+## API reference
+
+### ComboBox.Input
+
+Name: `ComboBox.Input`  
+Description: Text input with `role="combobox"` that syncs typed value, active descendant, and keyboard handling with `ComboBox.Root`.
+
+| Prop               | Type                  | Default     | Description                                     |
+| ------------------ | --------------------- | ----------- | ----------------------------------------------- |
+| `aria-label`       | `string`              | `undefined` | Accessible label applied directly to the input. |
+| `aria-labelledby`  | `string`              | `undefined` | Element id that labels the input.               |
+| `aria-describedby` | `string`              | `undefined` | Element id that describes the input behavior.   |
+| `class`            | `string`              | `undefined` | CSS class names for the input element.          |
+| `...restProps`     | `HTMLInputAttributes` | `-`         | Additional native input attributes.             |

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

@@ -1,6 +1,11 @@
 <script lang="ts">
 	import type { HTMLInputAttributes } from 'svelte/elements';
+	import { Input } from '../../input';
 	import { useComboBoxContext } from '../root/context';
+	import {
+		shouldShowFocusVisible,
+		trackInteractionModality
+	} from '../../primitives/input-modality';
 	import { cn } from '../../utils/cn';
 
 	type ComboBoxInputProps = HTMLInputAttributes & {
@@ -13,11 +18,26 @@
 		class?: string;
 	};
 
+	function composeEventHandlers<TEvent extends Event>(
+		internalHandler: ((event: TEvent) => void) | undefined,
+		externalHandler: ((event: TEvent) => void) | undefined
+	): (event: TEvent) => void {
+		return (event: TEvent) => {
+			internalHandler?.(event);
+			externalHandler?.(event);
+		};
+	}
+
 	let {
 		'aria-label': ariaLabel,
 		'aria-labelledby': ariaLabelledby,
 		'aria-describedby': ariaDescribedby,
 		class: className,
+		oninput: onInputExternal,
+		onfocus: onFocusExternal,
+		onmousedown: onMouseDownExternal,
+		onblur: onBlurExternal,
+		onkeydown: onKeyDownExternal,
 		...restProps
 	}: ComboBoxInputProps = $props();
 
@@ -42,6 +62,8 @@
 	}
 
 	function handleFocus() {
+		ctx.setFocusVisible(shouldShowFocusVisible(inputRef));
+
 		// 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.
@@ -54,7 +76,9 @@
 		}
 	}
 
-	function handleMouseDown() {
+	function handleMouseDown(event: MouseEvent) {
+		trackInteractionModality(event, inputRef);
+		ctx.setFocusVisible(false);
 		ctx.setFocusedTagId(null);
 		// Open on press if trigger is 'press'
 		if (ctx.trigger === 'press' && !ctx.isOpen && !ctx.isDisabled && !ctx.isReadOnly) {
@@ -62,14 +86,21 @@
 		}
 	}
 
-	function handleBlur() {
+	function handleKeyDown(event: KeyboardEvent) {
+		trackInteractionModality(event, inputRef);
+		ctx.setFocusVisible(shouldShowFocusVisible(inputRef));
+		ctx.handleKeydown(event);
+	}
+
+	function handleBlur(event: FocusEvent) {
+		ctx.setFocusVisible(false);
 		// Restore selection label or deselect if empty
-		ctx.handleInputBlur();
+		ctx.handleInputBlur(event);
 	}
 </script>
 
-<input
-	bind:this={inputRef}
+<Input
+	bind:element={inputRef}
 	type="text"
 	role="combobox"
 	aria-autocomplete="list"
@@ -83,13 +114,13 @@
 	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}
+	isDisabled={ctx.isDisabled}
+	isReadOnly={ctx.isReadOnly}
+	oninput={composeEventHandlers(handleInput, onInputExternal ?? undefined)}
+	onfocus={composeEventHandlers(handleFocus, onFocusExternal ?? undefined)}
+	onmousedown={composeEventHandlers(handleMouseDown, onMouseDownExternal ?? undefined)}
+	onblur={composeEventHandlers(handleBlur, onBlurExternal ?? undefined)}
+	onkeydown={composeEventHandlers(handleKeyDown, onKeyDownExternal ?? undefined)}
 	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

package/dist/combobox/item/README.md

@@ -0,0 +1,27 @@
+# ComboBox Item
+
+## API reference
+
+### ComboBox.Item
+
+Name: `ComboBox.Item`  
+Description: Selectable option item with combobox-specific filtering, virtual focus, and registration logic.
+
+| Prop           | Type                             | Default        | Description                                                    |
+| -------------- | -------------------------------- | -------------- | -------------------------------------------------------------- |
+| `id`           | `string \| number`               | `required`     | Unique item id used for selection and ARIA relationships.      |
+| `textValue`    | `string`                         | `content text` | Text used for filtering and fallback label resolution.         |
+| `disabled`     | `boolean`                        | `false`        | Marks the item as disabled and non-selectable.                 |
+| `class`        | `string`                         | `undefined`    | CSS class names for the item.                                  |
+| `children`     | `Snippet`                        | `undefined`    | Rendered item content.                                         |
+| `...restProps` | `HTMLAttributes<HTMLDivElement>` | `-`            | Additional attributes passed to the underlying option element. |
+
+### Item context utility
+
+Name: `COMBOBOX_ITEM_CONTEXT_KEY` / `ComboBoxItemContext`  
+Description: Internal context consumed by `ComboBox.ItemIndicator` to read the parent item id.
+
+| Prop                        | Type               | Default                       | Description                               |
+| --------------------------- | ------------------ | ----------------------------- | ----------------------------------------- |
+| `COMBOBOX_ITEM_CONTEXT_KEY` | `symbol`           | `Symbol.for('combobox-item')` | Context key shared by item and indicator. |
+| `id`                        | `string \| number` | `required`                    | Current item id exposed through context.  |