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

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

@@ -6,7 +6,7 @@
 
 <ComboBox.Root bind:value={selected}>
 	<ComboBox.Input placeholder="Search countries..." />
-	<ComboBox.Button />
+	<ComboBox.Trigger />
 
 	<ComboBox.Popover>
 		<ComboBox.List emptyPlaceholder="No countries found">

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

@@ -11,7 +11,6 @@
 	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:
@@ -33,7 +32,7 @@
 		| 'isParentDisabled'
 	>;
 
-	let { id, class: className, ...props }: ComboBoxListBoxItemProps = $props();
+	let { id, ...props }: ComboBoxListBoxItemProps = $props();
 
 	const ctx = useComboBoxContext();
 
@@ -67,6 +66,7 @@
 
 	// Virtual focus from ComboBox context
 	const isFocused = $derived(ctx.focusedItemId === id);
+	const isFocusVisible = $derived(isFocused && ctx.isFocusVisible);
 
 	// Generate unique ID using instanceId
 	const uniqueId = $derived(`combobox-item-${ctx.instanceId}-${id}`);
@@ -121,16 +121,10 @@
 		customId={uniqueId}
 		disableFocusHandling={true}
 		isFocusedOverride={isFocused}
+		isFocusVisibleOverride={isFocusVisible}
 		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-indicator/README.md

@@ -0,0 +1,15 @@
+# ComboBox Item Indicator
+
+## API reference
+
+### ComboBox.ItemIndicator
+
+Name: `ComboBox.ItemIndicator`  
+Description: Visual selection indicator rendered inside `ComboBox.Item`.
+
+| Prop           | Type                              | Default      | Description                                          |
+| -------------- | --------------------------------- | ------------ | ---------------------------------------------------- |
+| `children`     | `Snippet`                         | `check icon` | Custom indicator content.                            |
+| `forceMount`   | `boolean`                         | `false`      | Forces rendering even when the item is not selected. |
+| `class`        | `string`                          | `undefined`  | CSS class names for the indicator wrapper.           |
+| `...restProps` | `HTMLAttributes<HTMLSpanElement>` | `-`          | Additional attributes passed to the wrapper span.    |

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

@@ -1,13 +1,12 @@
 <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 type { HTMLAttributes } from 'svelte/elements';
 	import {
 		COMBOBOX_ITEM_CONTEXT_KEY,
 		type ComboBoxItemContext
 	} from '../item/combobox-listboxitem.svelte';
+	import { useComboBoxContext } from '../root/context';
 
 	/**
 	 * ComboBox.ItemIndicator - Visual indicator shown when an item is selected.
@@ -22,12 +21,7 @@
 		class?: string;
 	} & Omit<HTMLAttributes<HTMLSpanElement>, 'class' | 'children'>;
 
-	let {
-		children,
-		forceMount = false,
-		class: className,
-		...restProps
-	}: ComboBoxItemIndicatorProps = $props();
+	let { children, forceMount = false, ...restProps }: ComboBoxItemIndicatorProps = $props();
 
 	const comboboxCtx = useComboBoxContext();
 	const itemCtx = getContext<ComboBoxItemContext>(COMBOBOX_ITEM_CONTEXT_KEY);
@@ -37,12 +31,7 @@
 </script>
 
 {#if shouldRender}
-	<span
-		aria-hidden="true"
-		data-state={isSelected ? 'checked' : 'unchecked'}
-		class={cn('inline-flex items-center justify-center', className)}
-		{...restProps}
-	>
+	<span aria-hidden="true" data-state={isSelected ? 'checked' : 'unchecked'} {...restProps}>
 		{#if children}
 			{@render children()}
 		{:else}

package/dist/combobox/list/README.md

@@ -0,0 +1,27 @@
+# ComboBox List
+
+## API reference
+
+### ComboBox.List
+
+Name: `ComboBox.List`  
+Description: Listbox bridge for combobox options. It delegates selection state and mode to `ComboBox.Root`.
+
+| Prop              | Type                                                | Default     | Description                                                                     |
+| ----------------- | --------------------------------------------------- | ----------- | ------------------------------------------------------------------------------- |
+| `aria-label`      | `string`                                            | `'Options'` | Accessible label for the internal listbox.                                      |
+| `items`           | `Iterable<T>`                                       | `ctx.items` | Dynamic data source. If omitted, uses items from root context.                  |
+| `children`        | `Snippet<[T]> \| Snippet`                           | `undefined` | Dynamic item renderer or static list content.                                   |
+| `...listBoxProps` | `Omit<ComponentProps<ListBoxRoot>, internal props>` | `-`         | Additional listbox props such as `class`, `emptyPlaceholder`, or `disabledIds`. |
+
+### Internally controlled props
+
+Name: Controlled by `ComboBox.Root`  
+Description: The following values are set by `ComboBox.List` and should not be overridden directly.
+
+| Prop            | Type                     | Default                          | Description                                           |
+| --------------- | ------------------------ | -------------------------------- | ----------------------------------------------------- |
+| `selectionMode` | `'single' \| 'multiple'` | `ctx.selectionMode`              | Selection mode inherited from root.                   |
+| `value`         | `Set<string \| number>`  | `ctx.selectedValue`              | Current combobox selection state.                     |
+| `onChange`      | `(selection) => void`    | `internal handler`               | Delegates selected item handling to combobox context. |
+| `id`            | `string`                 | `combobox-listbox-${instanceId}` | Auto-generated listbox id for ARIA wiring.            |

package/dist/combobox/list/combobox-listbox.svelte.d.ts

@@ -17,7 +17,7 @@ declare function $$render<T extends object = object>(): {
     } & {
         context?: ListBoxContext;
         element?: HTMLElement;
-    }, "selectionMode" | "selectionBehavior" | "id" | "value" | "defaultValue" | "onChange" | "items" | "children" | "context" | "element"> & {
+    }, "children" | "value" | "id" | "element" | "selectionMode" | "selectionBehavior" | "defaultValue" | "onChange" | "items" | "context"> & {
         /** Optional items for dynamic rendering - overrides items from ComboBox context */
         items?: Iterable<T>;
         /** Content of the listbox. Receives item in dynamic mode. */

package/dist/combobox/popover/README.md

@@ -0,0 +1,27 @@
+# ComboBox Popover
+
+## API reference
+
+### ComboBox.Popover
+
+Name: `ComboBox.Popover`  
+Description: Floating container for combobox options. Internally composes `Popover.Root` and `Popover.Content` in non-modal mode.
+
+| Prop                           | Type                               | Default          | Description                                                                |
+| ------------------------------ | ---------------------------------- | ---------------- | -------------------------------------------------------------------------- |
+| `offset`                       | `number`                           | `8`              | Main-axis offset from the combobox trigger.                                |
+| `placement`                    | `ExtendedPlacement`                | `'bottom-start'` | Preferred floating placement.                                              |
+| `shouldFlip`                   | `boolean`                          | `true`           | Enables automatic fallback placement when space is limited.                |
+| `boundaryElement`              | `Element \| null`                  | `null`           | Optional boundary element for positioning constraints.                     |
+| `class`                        | `string`                           | `''`             | CSS class names for the floating panel.                                    |
+| `children`                     | `Snippet`                          | `undefined`      | Popover content, typically `ComboBox.List`.                                |
+| `isNonModal`                   | `boolean`                          | `true`           | Controls whether the popover behaves as a non-modal overlay.               |
+| `shouldCloseOnInteractOutside` | `boolean`                          | `true`           | Closes when interacting outside the panel.                                 |
+| `shouldCloseOnEscape`          | `boolean`                          | `true`           | Closes on Escape key press.                                                |
+| `shouldCloseOnBlur`            | `boolean`                          | `true`           | Closes on focus leaving trigger/content in the combobox interaction model. |
+| `initialFocus`                 | `FocusTrapOptions['initialFocus']` | `undefined`      | Initial focus target when modal focus trapping is enabled.                 |
+
+## Notes
+
+- `ComboBox.Popover` forwards all `Popover.Content` configuration props except the controlled open-state wiring (`open`, `triggerRef`, and `onOpenChange`).
+- The default placement is `bottom-start` to match the combobox input.

package/dist/combobox/popover/combobox-popover-props-test.svelte

@@ -0,0 +1,38 @@
+<script lang="ts">
+	import type { ComponentProps } from 'svelte';
+	import ComboBox from '../index';
+	import type { PopoverContent } from '../../popover';
+
+	type Props = {
+		offset?: number;
+		placement?: ComponentProps<typeof PopoverContent>['placement'];
+		shouldFlip?: boolean;
+		shouldCloseOnEscape?: boolean;
+	};
+
+	let {
+		offset = 8,
+		placement = 'bottom-start',
+		shouldFlip = true,
+		shouldCloseOnEscape = true
+	}: Props = $props();
+
+	const countries = [
+		{ id: 'ar', name: 'Argentina' },
+		{ id: 'br', name: 'Brazil' },
+		{ id: 'ca', name: 'Canada' }
+	];
+</script>
+
+<ComboBox.Root trigger="press">
+	<ComboBox.Input placeholder="Search countries..." />
+	<ComboBox.Trigger />
+
+	<ComboBox.Popover {offset} {placement} {shouldFlip} {shouldCloseOnEscape}>
+		<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/popover/combobox-popover-props-test.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { ComponentProps } from 'svelte';
+import type { PopoverContent } from '../../popover';
+type Props = {
+    offset?: number;
+    placement?: ComponentProps<typeof PopoverContent>['placement'];
+    shouldFlip?: boolean;
+    shouldCloseOnEscape?: boolean;
+};
+declare const ComboboxPopoverPropsTest: import("svelte").Component<Props, {}, "">;
+type ComboboxPopoverPropsTest = ReturnType<typeof ComboboxPopoverPropsTest>;
+export default ComboboxPopoverPropsTest;

package/dist/combobox/popover/combobox-popover.svelte

@@ -1,66 +1,209 @@
 <script lang="ts">
-	import type { Snippet } from 'svelte';
+	import type { ComponentProps, Snippet } from 'svelte';
 	import { useComboBoxContext } from '../root/context';
 	import { Popover } from '../../popover';
+	import { focusWithModality, type InputModality } from '../../primitives/input-modality';
+	import type { PopoverOpenChangeDetails } from '../../popover/root/context';
 
 	/**
 	 * ComboBox.Popover - Just the floating container wrapper.
 	 * Should contain ComboBox.ListBox as a child.
 	 */
-	type ComboBoxPopoverProps = {
-		class?: string;
+	type ComboBoxPopoverProps = Omit<
+		ComponentProps<typeof Popover.Content>,
+		'open' | 'triggerRef' | 'onOpenChange' | 'children'
+	> & {
 		children?: Snippet;
 	};
 
-	let { class: className = '', children }: ComboBoxPopoverProps = $props();
+	let {
+		class: className = '',
+		children,
+		placement = 'bottom-start',
+		isNonModal = true,
+		shouldCloseOnEscape = true,
+		shouldCloseOnBlur = true,
+		...contentProps
+	}: ComboBoxPopoverProps = $props();
 
 	const ctx = useComboBoxContext();
+	let restoreListboxMaxHeight: (() => void) | undefined;
+
+	function resolveFocusTarget(details?: PopoverOpenChangeDetails): HTMLElement | null {
+		const rawTarget = details?.event?.target;
+		if (!(rawTarget instanceof Node)) return null;
+		if (ctx.inputRef?.contains(rawTarget)) return null;
+		return rawTarget instanceof HTMLElement ? rawTarget : rawTarget.parentElement;
+	}
+
+	function handleOpenChange(open: boolean, details?: PopoverOpenChangeDetails) {
+		if (!open) {
+			// Cancel Popover.Root's close to prevent scheduleTriggerCloseFocus from
+			// setting stale data-focused on the trigger. The combobox passes triggerRef
+			// via prop (not Popover.Trigger), so Popover.Root never registers a
+			// blur-cleanup listener and any data-focused it sets persists forever.
+			//
+			// IMPORTANT: the actual state change is deferred to a microtask so that
+			// when Popover.Root's closePopover re-reads `isOpen` after the callback,
+			// the derived value is still `true` and the guard succeeds. A synchronous
+			// ctx.onOpenChange(false) would update the upstream signal immediately,
+			// making the derived `false` and bypassing the guard despite the cancel.
+			details?.cancel();
+
+			if (details?.reason === 'outside-press') {
+				const target = resolveFocusTarget(details);
+				queueMicrotask(() => {
+					ctx.onOpenChange(false);
+
+					if (target) {
+						focusWithModality(target, 'pointer' satisfies InputModality);
+					}
+
+					// If focus is still on the input (non-focusable target), blur it
+					// so focusWithin becomes false.
+					if (document.activeElement === ctx.inputRef) {
+						ctx.inputRef?.blur();
+					}
+				});
+				return;
+			}
+
+			queueMicrotask(() => {
+				ctx.onOpenChange(false);
+			});
+			return;
+		}
 
-	function handleOpenChange(open: boolean) {
 		ctx.onOpenChange(open);
 	}
 
+	function handleMouseDown() {
+		ctx.markPopoverPointerDown();
+	}
+
+	function applyListboxViewportConstraint() {
+		const listbox = ctx.listboxRef;
+		if (!listbox) return;
+
+		const previousInlineMaxHeight = listbox.style.maxHeight;
+		const computedMaxHeight = getComputedStyle(listbox).maxHeight;
+
+		listbox.style.maxHeight =
+			computedMaxHeight && computedMaxHeight !== 'none'
+				? `min(${computedMaxHeight}, var(--available-height))`
+				: 'var(--available-height)';
+
+		restoreListboxMaxHeight = () => {
+			listbox.style.maxHeight = previousInlineMaxHeight;
+		};
+	}
+
+	function canElementScrollInDirection(element: HTMLElement, deltaY: number) {
+		const isScrollingDown = deltaY > 0;
+		const isScrollingUp = deltaY < 0;
+		const canScrollDown = element.scrollTop < element.scrollHeight - element.clientHeight;
+		const canScrollUp = element.scrollTop > 0;
+
+		return (isScrollingDown && canScrollDown) || (isScrollingUp && canScrollUp);
+	}
+
+	function isScrollableElement(element: HTMLElement) {
+		const { overflowY } = getComputedStyle(element);
+		return (
+			['auto', 'scroll', 'overlay'].includes(overflowY) &&
+			element.scrollHeight > element.clientHeight
+		);
+	}
+
+	function hasScrollableDescendantForWheel(
+		boundary: HTMLElement,
+		target: EventTarget | null,
+		deltaY: number
+	) {
+		let current =
+			target instanceof HTMLElement ? target : target instanceof Node ? target.parentElement : null;
+
+		while (current) {
+			if (isScrollableElement(current) && canElementScrollInDirection(current, deltaY)) {
+				return true;
+			}
+
+			if (current === boundary) {
+				break;
+			}
+
+			current = current.parentElement;
+		}
+
+		return false;
+	}
+
 	/**
 	 * Prevent wheel/scroll events from propagating to the page
 	 * This keeps the page from scrolling when scrolling over the popover
-	 * But allows internal scrolling when the popover has overflow
+	 * But allows internal scrolling when either the popover or a descendant owns overflow
 	 */
 	function handleWheel(event: WheelEvent) {
 		const element = event.currentTarget as HTMLElement;
 		if (!element) return;
 
-		const { scrollTop, scrollHeight, clientHeight } = element;
-		const isScrollingDown = event.deltaY > 0;
-		const isScrollingUp = event.deltaY < 0;
-
-		// Check if we can scroll in the direction of the wheel
-		const canScrollDown = scrollTop < scrollHeight - clientHeight;
-		const canScrollUp = scrollTop > 0;
-
-		// If we can scroll internally in this direction, allow it
-		if ((isScrollingDown && canScrollDown) || (isScrollingUp && canScrollUp)) {
-			// Allow internal scroll, but stop propagation to page
-			event.stopPropagation();
-		} else {
-			// Can't scroll internally, prevent both default and propagation
-			event.preventDefault();
+		if (
+			hasScrollableDescendantForWheel(element, event.target, event.deltaY) ||
+			(isScrollableElement(element) && canElementScrollInDirection(element, event.deltaY))
+		) {
 			event.stopPropagation();
+			return;
 		}
+
+		event.preventDefault();
+		event.stopPropagation();
 	}
 
+	$effect(() => {
+		restoreListboxMaxHeight?.();
+		restoreListboxMaxHeight = undefined;
+
+		if (ctx.isOpen && ctx.listboxRef) {
+			applyListboxViewportConstraint();
+		}
+
+		return () => {
+			restoreListboxMaxHeight?.();
+			restoreListboxMaxHeight = undefined;
+		};
+	});
+
 	$effect(() => {
 		if (ctx.isOpen) {
 			ctx.inputRef?.focus();
 		}
 	});
+
+	$effect(() => {
+		ctx.setShouldCloseOnEscape(shouldCloseOnEscape);
+		return () => {
+			ctx.setShouldCloseOnEscape(true);
+		};
+	});
+
+	$effect(() => {
+		ctx.setShouldCloseOnBlur(shouldCloseOnBlur);
+		return () => {
+			ctx.setShouldCloseOnBlur(true);
+		};
+	});
 </script>
 
 <Popover.Root open={ctx.isOpen} triggerRef={ctx.triggerRef} onOpenChange={handleOpenChange}>
 	<Popover.Content
-		isNonModal={true}
-		placement="bottom-start"
+		{isNonModal}
+		{placement}
+		{shouldCloseOnEscape}
+		{shouldCloseOnBlur}
 		class={className}
+		onmousedown={handleMouseDown}
 		onwheel={handleWheel}
+		{...contentProps}
 	>
 		{#if children}
 			{@render children()}

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

@@ -1,10 +1,10 @@
-import type { Snippet } from 'svelte';
+import type { ComponentProps, Snippet } from 'svelte';
+import { Popover } from '../../popover';
 /**
  * ComboBox.Popover - Just the floating container wrapper.
  * Should contain ComboBox.ListBox as a child.
  */
-type ComboBoxPopoverProps = {
-    class?: string;
+type ComboBoxPopoverProps = Omit<ComponentProps<typeof Popover.Content>, 'open' | 'triggerRef' | 'onOpenChange' | 'children'> & {
     children?: Snippet;
 };
 declare const ComboboxPopover: import("svelte").Component<ComboBoxPopoverProps, {}, "">;

package/dist/combobox/popover/combobox-scrollable-list-test.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+	import ComboBox from '../index';
+
+	const items = Array.from({ length: 12 }, (_, index) => ({
+		id: `item-${index + 1}`,
+		name: `Item ${index + 1}`
+	}));
+</script>
+
+<ComboBox.Root trigger="press">
+	<ComboBox.Input placeholder="Search items..." />
+	<ComboBox.Trigger />
+
+	<ComboBox.Popover>
+		<ComboBox.List class="combobox-test-scroll-list" emptyPlaceholder="No items found">
+			{#each items as item (item.id)}
+				<ComboBox.Item id={item.id} textValue={item.name}>
+					{item.name}
+				</ComboBox.Item>
+			{/each}
+		</ComboBox.List>
+	</ComboBox.Popover>
+</ComboBox.Root>

package/dist/combobox/popover/combobox-scrollable-list-test.svelte.d.ts

@@ -0,0 +1,18 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const ComboboxScrollableListTest: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type ComboboxScrollableListTest = InstanceType<typeof ComboboxScrollableListTest>;
+export default ComboboxScrollableListTest;

package/dist/combobox/root/README.md

@@ -0,0 +1,45 @@
+# ComboBox Root
+
+## API reference
+
+### ComboBox.Root
+
+Name: `ComboBox.Root`  
+Description: State container for combobox behavior, including open state, input value, selection logic, filtering, and keyboard interaction.
+
+| Prop                | Type                                       | Default                          | Description                                                 |
+| ------------------- | ------------------------------------------ | -------------------------------- | ----------------------------------------------------------- |
+| `id`                | `string`                                   | `$props.id()`                    | Stable id used to derive internal ARIA ids.                 |
+| `isDisabled`        | `boolean`                                  | `false`                          | Disables all user interaction.                              |
+| `isPending`         | `boolean`                                  | `false`                          | Exposes busy async state on the root via `data-pending`.    |
+| `isReadOnly`        | `boolean`                                  | `false`                          | Keeps the component interactive but prevents value changes. |
+| `value`             | `string \| number \| (string \| number)[]` | `undefined`                      | Controlled selection value. Supports `bind:value`.          |
+| `defaultValue`      | `string \| number \| (string \| number)[]` | `undefined`                      | Initial selection value in uncontrolled mode.               |
+| `inputValue`        | `string`                                   | `undefined`                      | Controlled input value. Supports `bind:inputValue`.         |
+| `defaultInputValue` | `string`                                   | `''`                             | Initial input value in uncontrolled mode.                   |
+| `selectionBehavior` | `'toggle' \| 'replace'`                    | `'toggle'`                       | Selection behavior when selecting an option.                |
+| `selectionMode`     | `'single' \| 'multiple'`                   | `'single'`                       | Single-select or multi-select mode.                         |
+| `closeOnSelect`     | `boolean`                                  | `single: true / multiple: false` | Controls whether the popover closes after selection.        |
+| `isOpen`            | `boolean`                                  | `undefined`                      | Controlled open state. Supports `bind:isOpen`.              |
+| `trigger`           | `'focus' \| 'input' \| 'press'`            | `'press'`                        | Opening strategy for the popover.                           |
+| `onInputChange`     | `(value: string) => void`                  | `undefined`                      | Called when the input value changes.                        |
+| `onOpenChange`      | `(open: boolean) => void`                  | `undefined`                      | Called when open state changes.                             |
+| `onChange`          | `(value) => void`                          | `undefined`                      | Called when selection changes.                              |
+| `items`             | `T[]`                                      | `undefined`                      | Optional item collection for dynamic rendering.             |
+| `renderItem`        | `Snippet<[T]>`                             | `undefined`                      | Optional item renderer for dynamic mode.                    |
+| `children`          | `Snippet`                                  | `undefined`                      | Composed combobox parts.                                    |
+| `class`             | `string`                                   | `''`                             | CSS class names for the root group element.                 |
+| `aria-label`        | `string`                                   | `undefined`                      | Accessible label for the combobox group.                    |
+| `aria-labelledby`   | `string`                                   | `undefined`                      | Id of an external labeling element.                         |
+
+### Context utilities
+
+Name: `context.ts` helpers  
+Description: Internal and advanced APIs for publishing and consuming combobox state.
+
+| Prop                 | Type                                 | Default | Description                                         |
+| -------------------- | ------------------------------------ | ------- | --------------------------------------------------- |
+| `setComboBoxContext` | `(ctx: ComboBoxContext) => void`     | `-`     | Registers combobox context in root.                 |
+| `getComboBoxContext` | `() => ComboBoxContext \| undefined` | `-`     | Returns context if available.                       |
+| `useComboBoxContext` | `() => ComboBoxContext`              | `-`     | Returns context and throws outside `ComboBox.Root`. |
+| `ComboBoxContext`    | `type`                               | `-`     | Full context contract for state and actions.        |

package/dist/combobox/root/combobox-multiselect-test.svelte

@@ -47,7 +47,7 @@
 			{/snippet}
 		</ComboBox.Tags>
 		<ComboBox.Input placeholder="Search fruits..." />
-		<ComboBox.Button>▼</ComboBox.Button>
+		<ComboBox.Trigger>▼</ComboBox.Trigger>
 	</div>
 
 	<ComboBox.Popover>

package/dist/combobox/root/combobox-numeric-string-id-test.svelte

@@ -6,7 +6,7 @@
 
 <ComboBox.Root bind:value={selected}>
 	<ComboBox.Input placeholder="Search codes..." />
-	<ComboBox.Button />
+	<ComboBox.Trigger />
 
 	<ComboBox.Popover>
 		<ComboBox.List emptyPlaceholder="No codes found">

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

@@ -4,11 +4,20 @@
 	type Props = {
 		id?: string;
 		isDisabled?: boolean;
+		isPending?: boolean;
 		isReadOnly?: boolean;
 		trigger?: 'focus' | 'input' | 'press';
 	};
 
-	let { id, isDisabled = false, isReadOnly = false, trigger = 'press' }: Props = $props();
+	let {
+		id,
+		isDisabled = false,
+		isPending = false,
+		isReadOnly = false,
+		trigger = 'press'
+	}: Props = $props();
+
+	let selectedValue = $state<string | number | undefined>();
 
 	const countries = [
 		{ id: 'ar', name: 'Argentina' },
@@ -24,9 +33,9 @@
 	];
 </script>
 
-<ComboBox.Root {id} {isDisabled} {isReadOnly} {trigger}>
+<ComboBox.Root {id} {isDisabled} {isPending} {isReadOnly} {trigger} bind:value={selectedValue}>
 	<ComboBox.Input placeholder="Search countries..." />
-	<ComboBox.Button />
+	<ComboBox.Trigger />
 
 	<ComboBox.Popover>
 		<ComboBox.List emptyPlaceholder="No countries found">
@@ -39,5 +48,9 @@
 	</ComboBox.Popover>
 </ComboBox.Root>
 
+<output data-selected-value
+	>{selectedValue === undefined ? 'undefined' : String(selectedValue)}</output
+>
+
 <!-- Button outside the combobox for testing blur behavior -->
 <button type="button" data-testid="outside-button">Outside</button>

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

@@ -1,6 +1,7 @@
 type Props = {
     id?: string;
     isDisabled?: boolean;
+    isPending?: boolean;
     isReadOnly?: boolean;
     trigger?: 'focus' | 'input' | 'press';
 };