entasis 0.10.2 → 0.12.0

package/dist/components/Form/Combobox/Combobox.svelte

@@ -1,19 +1,21 @@
 <script lang="ts">
 	import { useI18n } from '../../../i18n/context.svelte.js';
 	import Field from '../Field/Field.svelte';
+	import FieldHiddenInputs from '../Field/FieldHiddenInputs.svelte';
 	import { createFieldState } from '../Field/field.state.svelte.js';
 	import type { ComboboxProps, ComboboxOption } from './combobox.props.js';
 	import Popover from '../../Popover/Popover.svelte';
-	import ScrollArea from '../../ScrollArea/ScrollArea.svelte';
-	import MenuOption from '../../MenuOption/MenuOption.svelte';
+	import { popupOpenClaim } from '../../Popover/popover.claims.js';
 	import { xIcon } from '../../Icons/x.js';
 	import { magnifyingGlassIcon } from '../../Icons/magnifyingGlass.js';
-	import { useDebounce } from '../../../utils/useDebounce.svelte.js';
-	import type { PopoverState } from '../../Popover/popover.state.svelte.js';
+	import type { PopoverApi } from '../../Popover/popover.api.js';
 	import { useComboboxTheme } from './combobox.theme.js';
-	import { useKeyDown } from '../../../utils/useKeyDown.svelte.js';
-	import { useListNavigation } from '../../../utils/useListNavigation.svelte.js';
-	import { onMount, untrack } from 'svelte';
+	import { createBindableValue } from '../../../utils/state.svelte.js';
+	import { flattenItems } from './combobox.items.js';
+	import { ComboboxController } from './combobox.state.svelte.js';
+	import ComboboxPopup from './ComboboxPopup.svelte';
+	import { untrack } from 'svelte';
+	import { presence } from '../../../utils/stateAttributes.js';
 	import FieldActionButton from '../Field/FieldActionButton.svelte';
 
 	let {
@@ -23,18 +25,33 @@
 		errors = $bindable([]),
 		loading = $bindable(false),
 		focused = $bindable(false),
+		open = $bindable(),
+		defaultOpen = false,
+		onOpenChange,
+		onAfterOpen,
+		onAfterClose,
 		required = false,
 		size = 'normal',
 		density = 'normal',
 		placeholder = '',
 		items,
+		openOnFocus,
 		showAllOnFocus = false,
+		filter,
+		limit,
+		autoHighlight = 'always',
+		loop,
+		onHighlightChange,
+		separators = true,
+		item,
 		getValueOption,
 		loadingText,
 		noOptionsText,
 		i18n,
 		theme,
 		disabled,
+		readOnly,
+		messages,
 		name,
 		onValidate,
 		onValueChange,
@@ -48,8 +65,14 @@
 
 	const id = $props.id();
 	const t = $derived(useI18n(i18n));
-	const listboxId = `${id}-listbox`;
-	const optionId = (value: string) => `${id}-option-${value.replace(/[^a-zA-Z0-9_-]/g, '_')}`;
+	const openState = createBindableValue(
+		() => open,
+		(next) => {
+			open = next;
+		},
+		() => defaultOpen
+	);
+	// Options resolved from an async source, for the label of the selected value.
 	let currentOption = $state<ComboboxOption | null>(null);
 
 	const field = createFieldState({
@@ -81,6 +104,12 @@
 		set disabled(v: boolean | undefined) {
 			disabled = v;
 		},
+		get readOnly() {
+			return readOnly;
+		},
+		get messages() {
+			return messages;
+		},
 		get required() {
 			return required;
 		},
@@ -99,145 +128,88 @@
 		type: 'combobox'
 	});
 
-	const selectedOption = $derived(
-		typeof items === 'function'
-			? currentOption
-			: (items.find((option) => option.value === field.value) ?? null)
-	);
-
-	// Load options state
-
-	// Keyboard navigation state
-
-	const getOptions = async (searchValue?: string | null, showAllOnFocus?: boolean) => {
-		const isOptionsAsync = typeof items === 'function';
-		if (!searchValue) {
-			if (!showAllOnFocus || isOptionsAsync) {
-				return { options: [] as ComboboxOption[], error: null };
-			} else {
-				return { options: items, error: null };
+	const controller = new ComboboxController({
+		id,
+		field,
+		items: () => items,
+		filter: () => filter,
+		limit: () => limit,
+		messages: () => t,
+		loadingText: () => loadingText,
+		noOptionsText: () => noOptionsText,
+		query: {
+			get: () => searchValue,
+			set: (next) => {
+				searchValue = next;
 			}
-		} else {
-			if (isOptionsAsync) {
-				loading = true;
-				try {
-					const results = await items(searchValue);
-					return { options: results, error: null };
-				} catch (error) {
-					return {
-						options: [] as ComboboxOption[],
-						error: error instanceof Error ? error.message : t.failedToLoadOptions
-					};
-				} finally {
-					loading = false;
-				}
-			} else {
-				const result = items.filter((option) =>
-					option.label.toLowerCase().includes(searchValue.toLowerCase())
-				);
-
-				return { options: result, error: null };
+		},
+		loading: {
+			get: () => loading,
+			set: (next) => {
+				loading = next;
+			}
+		},
+		open: {
+			get: () => openState.value,
+			set: (next) => {
+				openState.value = next;
 			}
+		},
+		onOpenChange: () => onOpenChange,
+		openOnFocus: () => openOnFocus ?? showAllOnFocus,
+		autoHighlight: () => autoHighlight,
+		loop: () => loop,
+		anchor: () => field.value ?? undefined,
+		onHighlightChange: () => onHighlightChange,
+		onSelect: (option, event) => {
+			currentOption = option;
+			field.setValue(option.value);
+			controller.close({ reason: 'item-press', event });
+			searchValue = '';
 		}
-	};
-	let optionsAsync = $state<{ options: ComboboxOption[]; error: string | null }>({
-		options: [],
-		error: null
 	});
 
-	const debouncedSearch = useDebounce((searchValue?: string | null, showAllOnFocus?: boolean) => {
-		getOptions(searchValue, showAllOnFocus).then((result) => {
-			optionsAsync = result;
-		});
-	}, 100);
+	// A static list knows its options; an async source reports the selected one through
+	// `getValueOption`, or from the results it has loaded.
+	const selectedOption = $derived(
+		typeof items === 'function'
+			? currentOption
+			: (flattenItems(items).find((option) => option.value === field.value) ?? null)
+	);
 
+	// The label follows the value, also when the parent changes it from outside.
+	let resolution = 0;
 	$effect(() => {
-		void searchValue;
-		void showAllOnFocus;
+		const current = field.value;
+		if (typeof items !== 'function') return;
 		untrack(() => {
-			debouncedSearch(searchValue, showAllOnFocus);
+			if (current == null) {
+				currentOption = null;
+				return;
+			}
+			if (currentOption?.value === current) return;
+			const loaded = controller.fetchedOptions.find((option) => option.value === current);
+			if (loaded) {
+				currentOption = loaded;
+				return;
+			}
+			const request = ++resolution;
+			currentOption = null;
+			void Promise.resolve(getValueOption?.(current)).then((option) => {
+				if (request === resolution && field.value === current) currentOption = option ?? null;
+			});
 		});
 	});
 
-	const isOpen = $derived.by(() => {
-		// Should show if
-		// has error or  has options or has no options and a search value
-		// is focused
-		return !!(
-			field.focused &&
-			(optionsAsync.error ||
-				optionsAsync.options.length > 0 ||
-				(optionsAsync.options.length === 0 && searchValue))
-		);
-	});
-
-	// Handle option selection
-	const handleSelectOption = (option: ComboboxOption) => {
-		currentOption = option;
-		field.value = option.value;
-		searchValue = '';
-		field.node?.blur();
-	};
-
-	// Handle clear
 	const handleClear = () => {
 		currentOption = null;
-		field.value = null;
+		field.setValue(null);
 		searchValue = '';
-		field.node?.blur();
+		field.node?.focus();
 	};
 
-	// Keyboard navigation: value-driven virtual focus. Re-anchors the highlight to the first
-	// option whenever the (async) option set changes.
-	const nav = useListNavigation({
-		values: () => optionsAsync.options.map((option) => option.value),
-		optionId,
-		onSelect: (value) => {
-			const option = optionsAsync.options.find((opt) => opt.value === value);
-			if (option) handleSelectOption(option);
-		}
-	});
-
-	useKeyDown({
-		isActive: () => field.focused,
-		keys: ['Escape'],
-		callback: () => {
-			field.node?.blur();
-		},
-		onWindow: () => true
-	});
-	const keyDownHook = useKeyDown({
-		isActive: () => isOpen || field.focused,
-		keys: ['ArrowDown', 'ArrowUp', 'Enter', 'Escape', 'Home', 'End'],
-		callback: (event: KeyboardEvent) => {
-			if (!isOpen || optionsAsync.options.length === 0) {
-				if (event.key === 'ArrowDown' || event.key === 'Enter') {
-					if (searchValue) {
-						field.focused = true;
-					}
-				}
-				return;
-			}
-
-			if (event.key === 'Escape') {
-				field.focused = false;
-				return;
-			}
-			nav.onKeydown(event);
-		},
-		onWindow: () => false // Only attach to input element, not window
-	});
-
-	onMount(async () => {
-		if (field.value) {
-			if (typeof items === 'function') {
-				currentOption = (await getValueOption?.(field.value)) || null;
-			}
-		}
-	});
-
 	// Determine if we should show clear button
-	const showClear = $derived(searchValue || field.value);
+	const showClear = $derived((searchValue || field.value) && !field.readOnly && !field.disabled);
 
 	// Default prefix: magnifying glass icon (unless prefix is false or custom snippet provided)
 	const effectivePrefix = $derived(
@@ -247,52 +219,29 @@
 	const classes = $derived(useComboboxTheme(theme));
 </script>
 
-<Popover closeOnClickOutside={false} fitTrigger position="bottom" size="small" open={isOpen}>
-	<div
-		id={listboxId}
-		role="listbox"
-		aria-label={t.options}
-		class="flex max-h-[200px] flex-col gap-1"
-	>
-		{#if loading}
-			<div class={classes.loading({ size })} role="status" aria-live="polite">
-				{loadingText ?? t.loadingEllipsis}
-			</div>
-		{:else if optionsAsync.error}
-			<div class={classes.error({ size })} role="alert" aria-live="assertive">
-				{optionsAsync.error}
-			</div>
-		{:else if optionsAsync.options.length === 0 && searchValue}
-			<div class={classes.noOptions({ size })} role="status">{noOptionsText ?? t.noOptions}</div>
-		{:else if optionsAsync.options.length === 0 && !searchValue && showAllOnFocus}
-			<div class={classes.noOptions({ size })} role="status">{noOptionsText ?? t.noOptions}</div>
-		{:else if optionsAsync.options.length > 0}
-			<ScrollArea scrollOnEdges type="auto" class="flex max-h-[200px] flex-col gap-1">
-				{#each optionsAsync.options as option (option.value)}
-					<MenuOption
-						as="button"
-						role="option"
-						{size}
-						{density}
-						title={option.label}
-						description={option.description}
-						highlighted={nav.highlighted === option.value}
-						selected={field.value === option.value}
-						onclick={() => handleSelectOption(option)}
-						attrs={{
-							id: optionId(option.value),
-							onpointermove: () => nav.setHighlighted(option.value),
-							onmousedown: (e: MouseEvent) => {
-								e.stopPropagation();
-								e.preventDefault();
-							}
-						}}
-					/>
-				{/each}
-			</ScrollArea>
-		{/if}
-	</div>
-	{#snippet trigger(popover: PopoverState)}
+<Popover
+	haspopup="listbox"
+	closeOnClickOutside={false}
+	closeOnEscape={false}
+	focusOnClose={false}
+	fitTrigger
+	position="bottom"
+	size="small"
+	open={controller.visible}
+	onAfterOpen={() => onAfterOpen?.()}
+	onAfterClose={() => onAfterClose?.()}
+>
+	<ComboboxPopup
+		{controller}
+		{classes}
+		{size}
+		{density}
+		{separators}
+		{item}
+		{i18n}
+		isSelected={(option) => field.value === option.value}
+	/>
+	{#snippet trigger(popover: PopoverApi)}
 		<Field
 			{density}
 			{field}
@@ -312,30 +261,41 @@
 				}
 			}}
 			{...rest}
-			{@attach popover.reference}
+			anchor={popover.reference}
 		>
 			<input
 				data-1p-ignore
 				type="text"
 				{id}
-				name={field.name}
 				bind:value={searchValue}
 				placeholder={selectedOption ? selectedOption.label : placeholder}
 				bind:this={field.node}
 				bind:focused={field.focused}
-				{disabled}
+				disabled={field.disabled}
 				role="combobox"
-				aria-expanded={isOpen}
-				aria-controls={isOpen ? listboxId : undefined}
+				aria-expanded={controller.expanded}
+				aria-controls={controller.expanded ? controller.listboxId : undefined}
 				aria-autocomplete="list"
-				aria-activedescendant={isOpen ? nav.activeDescendant : undefined}
+				aria-activedescendant={controller.activeDescendant}
 				aria-haspopup="listbox"
-				aria-invalid={!!optionsAsync.error}
+				aria-invalid={controller.error !== null}
+				data-disabled={presence(field.disabled)}
+				{@attach popupOpenClaim(controller.visible)}
 				autocomplete="off"
 				class={classes.input({ size, hasValue: field.value !== null, disabled: field.disabled })}
 				class:placeholder:text-neutral={selectedOption && !searchValue}
-				{@attach keyDownHook.reference}
+				oninput={(event) => controller.onInput(event)}
+				onkeydown={(event) => controller.onKeydown(event)}
+				onfocus={(event) => controller.onFocus(event)}
+				onpointerdown={() => controller.onPointerDown()}
+				onclick={(event) => controller.onClick(event)}
 			/>
+			<!-- The search box holds a draft, not the value: the value is what a native form submits. -->
+			<FieldHiddenInputs {field} value={field.value} />
+			<!-- Persistent, so it exists before the first announcement: result counts and status. -->
+			<span class="sr-only" {...controller.announcer.regionAttrs}>
+				{controller.announcer.message}
+			</span>
 			{#if showClear && !suffix}
 				<FieldActionButton
 					{size}

package/dist/components/Form/Combobox/Combobox.svelte.d.ts

@@ -1,4 +1,4 @@
 import type { ComboboxProps } from './combobox.props.js';
-declare const Combobox: import("svelte").Component<ComboboxProps, {}, "value" | "loading" | "errors" | "focused" | "searchValue">;
+declare const Combobox: import("svelte").Component<ComboboxProps, {}, "value" | "loading" | "errors" | "focused" | "open" | "searchValue">;
 type Combobox = ReturnType<typeof Combobox>;
 export default Combobox;

package/dist/components/Form/Combobox/ComboboxPopup.svelte

@@ -0,0 +1,128 @@
+<script lang="ts">
+	// The list Combobox and TagsInput open under their input: a listbox of options and groups,
+	// with the loading, error and "no options" message beside it (a listbox may only own options
+	// and groups). Live announcements come from the controller's persistent region, not from here.
+	import type { Snippet } from 'svelte';
+	import type { Density, Sizes } from '../../../types/theme.js';
+	import { useI18n } from '../../../i18n/context.svelte.js';
+	import MenuOption from '../../MenuOption/MenuOption.svelte';
+	import ScrollArea from '../../ScrollArea/ScrollArea.svelte';
+	import { toRenderGroups } from './combobox.items.js';
+	import type { ComboboxController } from './combobox.state.svelte.js';
+	import type { ComboboxOption } from './combobox.props.js';
+
+	type PartClass = (props: { size: Sizes }) => string;
+
+	let {
+		controller,
+		classes,
+		size,
+		density,
+		separators = true,
+		item,
+		isSelected,
+		i18n
+	}: {
+		controller: ComboboxController;
+		classes: {
+			loading: PartClass;
+			error: PartClass;
+			noOptions: PartClass;
+			group: PartClass;
+			groupLabel: PartClass;
+			separator: PartClass;
+		};
+		size: Sizes;
+		density: Density;
+		separators?: boolean;
+		item?: Snippet<[ComboboxOption]>;
+		isSelected?: (option: ComboboxOption) => boolean;
+		i18n?: Parameters<typeof useI18n>[0];
+	} = $props();
+
+	const t = $derived(useI18n(i18n));
+	const view = $derived(controller.view);
+	const status = $derived(controller.status);
+	const groups = $derived(toRenderGroups(view.items));
+	// The controller is created once per field; its navigation object is stable.
+	// svelte-ignore state_referenced_locally
+	const nav = controller.nav;
+	const listClass =
+		'flex max-h-[min(200px,calc(var(--available-height,100dvh)_-_2*var(--space-xs)))] flex-col gap-1';
+</script>
+
+{#snippet row(option: ComboboxOption)}
+	{#snippet customRow()}
+		{@render item?.(option)}
+	{/snippet}
+	<MenuOption
+		as="button"
+		role="option"
+		{size}
+		{density}
+		title={item ? undefined : option.label}
+		description={item ? undefined : option.description}
+		children={item ? customRow : undefined}
+		highlighted={nav.highlighted === option.value}
+		selected={isSelected?.(option) ?? false}
+		disabled={!!option.disabled}
+		onclick={(event) => controller.selectOption(option, event)}
+		attrs={{
+			id: nav.optionId(option.value),
+			tabindex: -1,
+			onpointermove: (event: PointerEvent) => {
+				if (!option.disabled) nav.pointerHighlight(option.value, event);
+			}
+		}}
+	/>
+{/snippet}
+
+<!-- A press anywhere in the list (padding, group labels, the scrollbar) must not move focus off
+     the input, or the field would lose it and the list would close before the click lands. -->
+<div role="presentation" class="flex flex-col" onmousedown={controller.preventBlur}>
+	{#if status}
+		<div class={classes[status.kind === 'empty' ? 'noOptions' : status.kind]({ size })}>
+			{status.text}
+		</div>
+	{/if}
+	{#if view.hasOptions}
+		<!-- The scrolling viewport is the listbox, so options and groups are its only children. It is
+		     focusable from script only (tabindex -1): DOM focus stays on the input, and the input's
+		     active descendant scrolls the highlighted option into view. -->
+		<ScrollArea
+			bind:viewportRef={controller.viewport}
+			viewportAttrs={{
+				id: controller.listboxId,
+				role: 'listbox',
+				'aria-label': t.options,
+				'aria-busy': view.loading || undefined,
+				tabindex: -1
+			}}
+			scrollOnEdges
+			type="auto"
+			class={listClass}
+		>
+			{#each groups as group, groupIndex (groupIndex)}
+				{#if separators && groupIndex > 0}
+					<!-- Decorative divider between groups: the groups already convey the structure. -->
+					<div role="presentation" class={classes.separator({ size })}></div>
+				{/if}
+				{#if group.label}
+					<div role="group" aria-label={group.label} class={classes.group({ size })}>
+						<div aria-hidden="true" class={classes.groupLabel({ size })}>{group.label}</div>
+						{#each group.items as option (option.value)}
+							{@render row(option)}
+						{/each}
+					</div>
+				{:else}
+					{#each group.items as option (option.value)}
+						{@render row(option)}
+					{/each}
+				{/if}
+			{/each}
+		</ScrollArea>
+	{:else}
+		<!-- Kept mounted while empty (hidden) so the input's aria-controls always resolves. -->
+		<div id={controller.listboxId} role="listbox" aria-label={t.options} hidden></div>
+	{/if}
+</div>

package/dist/components/Form/Combobox/ComboboxPopup.svelte.d.ts

@@ -0,0 +1,28 @@
+import type { Snippet } from 'svelte';
+import type { Density, Sizes } from '../../../types/theme.js';
+import { useI18n } from '../../../i18n/context.svelte.js';
+import type { ComboboxController } from './combobox.state.svelte.js';
+import type { ComboboxOption } from './combobox.props.js';
+type PartClass = (props: {
+    size: Sizes;
+}) => string;
+type $$ComponentProps = {
+    controller: ComboboxController;
+    classes: {
+        loading: PartClass;
+        error: PartClass;
+        noOptions: PartClass;
+        group: PartClass;
+        groupLabel: PartClass;
+        separator: PartClass;
+    };
+    size: Sizes;
+    density: Density;
+    separators?: boolean;
+    item?: Snippet<[ComboboxOption]>;
+    isSelected?: (option: ComboboxOption) => boolean;
+    i18n?: Parameters<typeof useI18n>[0];
+};
+declare const ComboboxPopup: import("svelte").Component<$$ComponentProps, {}, "">;
+type ComboboxPopup = ReturnType<typeof ComboboxPopup>;
+export default ComboboxPopup;

package/dist/components/Form/Combobox/combobox.attributes.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The styling hooks a Combobox exposes. Attributes are presence attributes (set while the state
+ * holds, omitted otherwise) unless the description says they carry a value. The list sits in a
+ * Popover panel, whose CSS variables (`comboboxCssVariables`) it inherits.
+ */
+export declare const comboboxDataAttributes: {
+    readonly 'data-popup-open': "On the input and the field container around it: present while the list (or its empty, loading or error status) shows.";
+    readonly 'data-popup-side': "On the field container: the side of the field the list sits on.";
+    readonly 'data-disabled': "On the input: present while disabled. On an option: present while it is disabled.";
+    readonly 'data-highlighted': "On an option: present while the keyboard or the pointer highlights it.";
+    readonly 'data-selected': "On an option: present while it is the value.";
+    readonly 'data-open': "On the list panel: present while open.";
+    readonly 'data-closed': "On the list panel: present while its exit transition plays.";
+    readonly 'data-entering': "On the list panel: present while the enter transition plays.";
+    readonly 'data-exiting': "On the list panel: present while the exit transition plays.";
+    readonly 'data-side': "On the list panel: the side of the field it sits on after flipping.";
+    readonly 'data-align': "On the list panel: `start`, `center` or `end`.";
+};
+/** The name of a Combobox data attribute. */
+export type ComboboxDataAttribute = keyof typeof comboboxDataAttributes;
+/**
+ * The CSS variables a placement writes on the list panel's positioned wrapper, inherited by the
+ * list: the Popover set (`popoverCssVariables`). The option list caps its height with
+ * `--available-height`.
+ */
+export declare const comboboxCssVariables: {
+    readonly '--available-width': "The width in px the panel can take before it reaches the viewport edges, minus 20px.";
+    readonly '--available-height': "The room in px between the trigger and the viewport edge on the panel's side, minus 20px. Cap a scrolling list with `max-height: min(240px, var(--available-height))`.";
+    readonly '--anchor-width': "The trigger's width in px, snapped to the device pixel grid.";
+    readonly '--anchor-height': "The trigger's height in px, snapped to the device pixel grid.";
+    readonly '--transform-origin': "The panel corner facing the trigger, mirrored in right-to-left documents; the point the panel scales from.";
+};
+/** The name of a Combobox CSS variable. */
+export type ComboboxCssVariable = keyof typeof comboboxCssVariables;

package/dist/components/Form/Combobox/combobox.attributes.js

@@ -0,0 +1,25 @@
+import { popoverCssVariables } from '../../Popover/popover.attributes.js';
+/**
+ * The styling hooks a Combobox exposes. Attributes are presence attributes (set while the state
+ * holds, omitted otherwise) unless the description says they carry a value. The list sits in a
+ * Popover panel, whose CSS variables (`comboboxCssVariables`) it inherits.
+ */
+export const comboboxDataAttributes = {
+    'data-popup-open': 'On the input and the field container around it: present while the list (or its empty, loading or error status) shows.',
+    'data-popup-side': 'On the field container: the side of the field the list sits on.',
+    'data-disabled': 'On the input: present while disabled. On an option: present while it is disabled.',
+    'data-highlighted': 'On an option: present while the keyboard or the pointer highlights it.',
+    'data-selected': 'On an option: present while it is the value.',
+    'data-open': 'On the list panel: present while open.',
+    'data-closed': 'On the list panel: present while its exit transition plays.',
+    'data-entering': 'On the list panel: present while the enter transition plays.',
+    'data-exiting': 'On the list panel: present while the exit transition plays.',
+    'data-side': 'On the list panel: the side of the field it sits on after flipping.',
+    'data-align': 'On the list panel: `start`, `center` or `end`.'
+};
+/**
+ * The CSS variables a placement writes on the list panel's positioned wrapper, inherited by the
+ * list: the Popover set (`popoverCssVariables`). The option list caps its height with
+ * `--available-height`.
+ */
+export const comboboxCssVariables = popoverCssVariables;