@scalewing/react 1.30.0 → 1.31.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @scalewing/react
 
+## 1.31.0
+
+### Minor Changes
+
+- ae2d883: `Combobox` (with `ComboboxProps`, `ComboboxGroup`, `ComboboxOption`, `ComboboxBadge`, `ComboboxAction`, `ComboboxSize` and `comboboxSizes`): a text input with a list of suggestions, an ARIA 1.2 combobox with list autocomplete (`docs/requests/teisoro-combobox.md`, Teisoro F-011 release R5).
+
+  - `label`, `inputValue`, `onInputChange`, `groups` (`{ label?, options: { value, label, description?, badge?, disabled? }[] }[]`, filtered by the consumer), `onSelect`, `action?` (`{ label, onPress, badge? }`), `emptyText`, `note?`, `listLabel?`, `countText?` (`(count) => string`), and the Field props `labelVisuallyHidden`, `placeholder`, `description`, `error`, `required`, `disabled`, `size` (`md` | `xs`).
+  - Focus stays in the input; the arrow keys move `aria-activedescendant` and wrap; Enter or a press chooses; a disabled option is never chosen; Escape closes, then empties; Alt+ArrowUp, blur, Tab or a press outside closes; the pointer moves the active option; the active option is held by value across new results; input-method keys are ignored; an always-present polite live region announces the empty text and `countText`.
+  - The list is on the popup layer (`openPopups` gains `.sw-combobox-popup`), solid under reduced transparency, with forced-colours rules. Blank words, duplicate values, an unknown size or badge tone throw a `RangeError`.
+  - New classes `sw-combobox*`. No new tokens or dependencies.
+
+- c79024a: `Field` `variant="search"` (`fieldVariants`, `FieldVariant`), the web twin of the native search field (`docs/requests/teisoro-field-search.md`, Teisoro F-011 release R5): a hidden label that still names a `type="search"` input, a `leading` glyph slot, and, while the input holds text and is enabled and not read-only, a clear button named `clearLabel` that returns focus to the input and calls `onClear` (Escape too). The browser's own clear button is hidden; `enterKeyHint` defaults to `search`. Missing or blank `clearLabel`, missing `onClear`, `prefix`/`suffix`, a non-input or uncontrolled child, or the search props on an outlined field throw. New classes `sw-field-search-field`, `sw-field-search`, `sw-field-search-leading`, `sw-field-search-clear`, `sw-field-search-cross`. No new tokens or dependencies.
+
 ## 1.30.0
 
 ### Minor Changes

package/README.md

@@ -99,6 +99,8 @@ A disabled native text control (`<input>`, `<select>` or `<textarea>` on the can
 
 `Field` `prefix` and `suffix` put short text such as `$` or `%` inside the frame of one native `<input>` child, before or after the value. The text is not part of the value; the input is named by its label plus the adornment (`"Drop amount $"`), unless it names itself with its own `aria-label` or `aria-labelledby`, in which case the adornment joins its description. A press anywhere on the frame focuses the input. Formatting the value stays with the consumer. Any other child throws a `TypeError`.
 
+`Field` `variant="search"` (default `"outlined"`; `fieldVariants`) is a search box over one native `<input>` child with a `value`: the `label` is not drawn but still names the input, which becomes `type="search"` (a `searchbox`); `leading` is your glyph at the frame's start, such as a magnifier, hidden from assistive technology; and while the input holds text and is enabled and not read-only, a clear button named `clearLabel` ("Clear search") ends the frame, puts focus back in the input and calls `onClear` (set the value to `''`); Escape with text calls `onClear` too. The browser's own clear button is hidden, so there is one. The input gets `enterKeyHint="search"` unless you pass one. The frame is the adorned field's, so focus, `error`, `description`, `invalid` and the disabled look work as on any field; a press on the glyph focuses the input; the clear button is the 44 px target on a coarse pointer. A search field without a nonempty `clearLabel` or `onClear`, with `prefix` or `suffix`, or with a child that is not an `<input>` with a `value` throws; `leading`, `clearLabel` and `onClear` on an outlined field, or an unknown `variant`, throw too.
+
 ```tsx
 <Field label="Drop amount" prefix="$">
   <input inputMode="decimal" name="drop" />
@@ -408,6 +410,8 @@ A ledger read across as well as down takes `Table` `columnRules` (a hairline at
 </Inline>
 ```
 
+`Combobox` is a text input with a list of suggestions, an ARIA 1.2 combobox with list autocomplete. Pass the `label` (drawn above the input unless `labelVisuallyHidden`), the controlled `inputValue` and `onInputChange`, and `groups` you filter from the text yourself: `{ label?, options }`, each option `{ value, label, description?, badge?: { label, tone? }, disabled? }`. Typing, a press on the input or ArrowDown opens the list on the popover layer under the input, at least as wide; each group with a `label` is a `role="group"` under its heading. ArrowDown and ArrowUp move the active option (named by the input's `aria-activedescendant`; focus stays in the input) and wrap; Enter or a press chooses it and calls `onSelect(value)` (set `inputValue` to its label yourself), and a disabled option is shown and read as unavailable but never chosen. `action` (`{ label, onPress, badge? }`) ends the list as one more option, such as adding a new entry. `emptyText` shows when no group has an option, and a polite live region, always in the page, announces it (and, with `countText: (count) => string`, the number of options); `note` is a muted line under the list that describes the input while open. `listLabel` names the list when it differs from the input's label. The active option is held by its value, so it stays put when your results change under it. Escape closes the list and a second Escape empties the input; Alt+ArrowUp, Tab, a blur or a press outside closes it. The input is a `Field` input, so `description`, `error`, `required`, `disabled`, `placeholder` and `size` (`md` or `xs`; `comboboxSizes`) work as on any field. Blank words, duplicate option values, an unknown `size` or badge tone throw a `RangeError`, and an `action` without `onPress` a `TypeError`.
+
 `MultiSelect` is several choices from a short list behind one trigger, such as which kinds a list shows. The trigger reads the muted `label` and then `summary` (your words for what is chosen, such as "All entries" or "2 services") with a chevron; it opens a panel named by the label with `allLabel` and `clearLabel` commands over one checkbox per option, each with an optional `icon` (use a small `GlyphTile`, never a bare dot) and a hairline before an option with `separatorBefore`. `onChange` reports the checked values in the options' order. It is a disclosure of native checkboxes, not a listbox: the first checkbox takes focus as it opens, Escape closes it and returns focus to the trigger, focus or a press outside closes it, and disabling it while open closes it. Blank words, no or duplicate options, a value that is not an option, or an unknown `align` throw a `RangeError`.
 
 ```tsx

package/dist/components/Combobox.d.ts

@@ -0,0 +1,14 @@
+import { type ComboboxProps } from './combobox/types.js';
+export { comboboxSizes, type ComboboxAction, type ComboboxBadge, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type ComboboxSize, } from './combobox/types.js';
+/**
+ * A text input with a list of suggestions (ARIA 1.2 combobox, list
+ * autocomplete): typing, a press on the input or ArrowDown opens the list
+ * and the consumer filters `groups` from `inputValue`; the arrow keys move
+ * the active option (`aria-activedescendant`) while focus stays in the
+ * input; Enter or a press chooses it (`onSelect`) or runs the `action`;
+ * Escape closes the list, and a second Escape empties the input. A
+ * disabled option is shown and read as unavailable but never chosen. The
+ * active option is held by its value, so it stays the same option (or
+ * none) when the results change under it.
+ */
+export declare function Combobox(props: ComboboxProps): import("react").JSX.Element;

package/dist/components/Combobox.js

@@ -0,0 +1,125 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useRef, useState } from 'react';
+import { ComboboxPopup } from './combobox/ComboboxPopup.js';
+import { comboboxEntries } from './combobox/entries.js';
+import { assertCombobox } from './combobox/validate.js';
+import { Field } from './Field.js';
+export { comboboxSizes, } from './combobox/types.js';
+/** A key typed into an input method (Safari reports it as keyCode 229). */
+function isComposing(event) {
+    return event.nativeEvent.isComposing || event.keyCode === 229;
+}
+/**
+ * A text input with a list of suggestions (ARIA 1.2 combobox, list
+ * autocomplete): typing, a press on the input or ArrowDown opens the list
+ * and the consumer filters `groups` from `inputValue`; the arrow keys move
+ * the active option (`aria-activedescendant`) while focus stays in the
+ * input; Enter or a press chooses it (`onSelect`) or runs the `action`;
+ * Escape closes the list, and a second Escape empties the input. A
+ * disabled option is shown and read as unavailable but never chosen. The
+ * active option is held by its value, so it stays the same option (or
+ * none) when the results change under it.
+ */
+export function Combobox(props) {
+    assertCombobox(props);
+    const { action, countText, description, disabled = false, emptyText, error, groups, inputValue, label, labelVisuallyHidden = false, listLabel, note, onInputChange, onSelect, placeholder, required = false, size = 'md', } = props;
+    const listId = useId();
+    const noteId = useId();
+    const inputRef = useRef(null);
+    const [open, setOpen] = useState(false);
+    const [activeKey, setActiveKey] = useState(null);
+    // Disabling closes the list for good, so enabling never reopens it.
+    if (disabled && open) {
+        setOpen(false);
+        setActiveKey(null);
+    }
+    const entries = comboboxEntries(listId, groups, action);
+    const shown = open && !disabled;
+    const active = shown
+        ? entries.find((entry) => entry.key === activeKey)
+        : undefined;
+    // An active option that leaves the results is dropped, so it never comes
+    // back active on its own.
+    if (shown && activeKey !== null && !active)
+        setActiveKey(null);
+    const hasList = entries.length > 0;
+    const optionCount = entries.filter((entry) => entry.kind === 'option').length;
+    const announcement = !shown
+        ? ''
+        : optionCount === 0
+            ? emptyText
+            : (countText?.(optionCount) ?? '');
+    function close() {
+        setOpen(false);
+        setActiveKey(null);
+    }
+    function choose(entry) {
+        if (entry.kind === 'option') {
+            if (entry.option.disabled)
+                return;
+            close();
+            onSelect(entry.option.value);
+        }
+        else {
+            close();
+            entry.action.onPress();
+        }
+    }
+    function move(step) {
+        if (entries.length === 0)
+            return;
+        const last = entries.length - 1;
+        if (!shown || !active) {
+            setOpen(true);
+            setActiveKey(entries[step === 1 ? 0 : last].key);
+            return;
+        }
+        const next = (active.index + step + entries.length) % entries.length;
+        setActiveKey(entries[next].key);
+    }
+    function onKeyDown(event) {
+        if (isComposing(event))
+            return;
+        if (event.altKey && event.key === 'ArrowDown') {
+            event.preventDefault();
+            setOpen(true);
+        }
+        else if (event.altKey && event.key === 'ArrowUp') {
+            event.preventDefault();
+            close();
+        }
+        else if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+            event.preventDefault();
+            move(event.key === 'ArrowDown' ? 1 : -1);
+        }
+        else if (event.key === 'Enter') {
+            if (active) {
+                event.preventDefault();
+                choose(active);
+            }
+        }
+        else if (event.key === 'Escape') {
+            if (shown) {
+                event.preventDefault();
+                close();
+            }
+            else if (inputValue !== '') {
+                event.preventDefault();
+                onInputChange('');
+            }
+        }
+        // Tab moves focus out, and the blur closes the list.
+    }
+    return (_jsxs("div", { className: "sw-combobox", children: [_jsx(Field, { description: description, error: error, label: label, labelVisuallyHidden: labelVisuallyHidden, required: required, size: size, children: _jsx("input", { "aria-activedescendant": active?.id, "aria-autocomplete": "list", "aria-controls": shown && hasList ? listId : undefined, "aria-describedby": shown && note ? noteId : undefined, "aria-expanded": shown && hasList, autoComplete: "off", disabled: disabled, onBlur: close, onChange: (event) => {
+                        onInputChange(event.currentTarget.value);
+                        setOpen(true);
+                        setActiveKey(null);
+                    }, 
+                    // A press on the input opens the list, as the boards show it
+                    // under an empty field.
+                    onClick: () => {
+                        if (!shown)
+                            setOpen(true);
+                    }, onKeyDown: onKeyDown, placeholder: placeholder, ref: inputRef, role: "combobox", spellCheck: false, type: "text", value: inputValue }) }), _jsx("span", { "aria-live": "polite", className: "sw-sr-only", role: "status", children: announcement }), shown ? (_jsx(ComboboxPopup, { activeId: active?.id, emptyText: emptyText, entries: entries, groups: groups, inputRef: inputRef, listId: listId, listLabel: listLabel ?? label, note: note, noteId: noteId, onActivate: (entry) => setActiveKey(entry.key), onChoose: choose, onDismiss: close })) : null] }));
+}

package/dist/components/Field.d.ts

@@ -1,6 +1,8 @@
 import { type SpacingStep } from '@scalewing/tokens';
 import { type ReactNode } from 'react';
 export type FieldSize = 'xs' | 'md';
+export declare const fieldVariants: readonly ["outlined", "search"];
+export type FieldVariant = (typeof fieldVariants)[number];
 export type FieldProps = {
     children: ReactNode;
     gap?: SpacingStep;
@@ -35,5 +37,20 @@ export type FieldProps = {
     prefix?: string;
     /** Short text inside the control frame after the value, such as a unit. Not part of the value. */
     suffix?: string;
+    /**
+     * `outlined` (default) is the labelled form field. `search` is a search
+     * box: the label is not drawn (it stays the input's name), a `leading`
+     * glyph sits at the frame's start, the input is `type="search"`, and a
+     * clear button named `clearLabel` shows while the input holds text and
+     * is enabled; it calls `onClear` (set the value to `''`) and puts focus
+     * back in the input. Needs one native `input` child with a `value`.
+     */
+    variant?: FieldVariant;
+    /** A search field's glyph at its start, such as a magnifier; hidden from assistive technology. */
+    leading?: ReactNode;
+    /** A search field's clear button name, such as "Clear search". */
+    clearLabel?: string;
+    /** Called by a search field's clear button; the consumer empties the value. */
+    onClear?: () => void;
 };
 export declare function Field(props: FieldProps): import("react").JSX.Element;

package/dist/components/Field.js

@@ -1,10 +1,34 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { cloneElement, isValidElement, useId } from 'react';
+import { cloneElement, isValidElement, useId, } from 'react';
 import { adornedControlAria, FieldAdornment, } from './FieldAdornment.js';
 import { FieldErrorRegion } from './FieldErrorRegion.js';
 import { FieldLabelText } from './FieldLabelText.js';
+import { SearchFrame } from './field/SearchFrame.js';
 import { Stack } from './Stack.js';
+export const fieldVariants = ['outlined', 'search'];
+function assertSearch(props, child) {
+    const { variant = 'outlined' } = props;
+    if (!fieldVariants.includes(variant))
+        throw new RangeError(`Unknown Field variant: ${String(variant)}`);
+    if (variant !== 'search') {
+        if (props.leading !== undefined ||
+            props.clearLabel !== undefined ||
+            props.onClear !== undefined)
+            throw new TypeError('Field leading, clearLabel and onClear are for variant="search"');
+        return;
+    }
+    if (!props.clearLabel?.trim())
+        throw new RangeError('A search Field needs a nonempty clearLabel');
+    if (typeof props.onClear !== 'function')
+        throw new TypeError('A search Field needs onClear');
+    if (props.prefix || props.suffix)
+        throw new TypeError('A search Field takes leading, not prefix or suffix');
+    if (!isValidElement(child) || child.type !== 'input')
+        throw new TypeError('A search Field needs one native input child');
+    if (child.props.value === undefined)
+        throw new TypeError('A search Field needs a controlled input: pass value (and onChange)');
+}
 /**
  * `invalid` was passed, even as `false`, but not as `undefined` (a wrapper
  * forwarding an optional prop passes nothing): such a field needs one native
@@ -17,7 +41,9 @@ function passesInvalid(props) {
     return props.invalid !== undefined || props.changed !== undefined;
 }
 export function Field(props) {
-    const { children, gap = 1, label, labelVisuallyHidden = false, size = 'md', description, error, invalid = false, changed = false, required = false, prefix, suffix, } = props;
+    const { children, gap = 1, label, labelVisuallyHidden = false, size = 'md', description, error, invalid = false, changed = false, required = false, prefix, suffix, variant = 'outlined', leading, clearLabel = '', onClear, } = props;
+    assertSearch(props, children);
+    const search = variant === 'search';
     const controlId = useId();
     const descriptionId = useId();
     const errorId = useId();
@@ -32,17 +58,20 @@ export function Field(props) {
         'sw-field',
         size === 'xs' && 'sw-field-xs',
         marksInvalid && 'sw-field-invalid',
+        search && 'sw-field-search-field',
         changed && !marksInvalid && 'sw-field-changed',
     ]
         .filter(Boolean)
         .join(' ');
-    const labelText = (_jsx(FieldLabelText, { label: label, required: required, size: size, visuallyHidden: labelVisuallyHidden }));
+    // A search field hides its whole label element instead (see below).
+    const labelHidden = labelVisuallyHidden && !search;
+    const labelText = (_jsx(FieldLabelText, { label: label, required: required, size: size, visuallyHidden: labelHidden }));
     if (!isValidElement(children) ||
         typeof children.type !== 'string' ||
         !['input', 'select', 'textarea'].includes(children.type)) {
         if (needsControl)
             throw new TypeError('Field validation and adornments require one native input, select, or textarea child');
-        return (_jsxs(Stack, { as: "label", className: className, gap: labelVisuallyHidden ? 0 : gap, children: [labelText, children] }));
+        return (_jsxs(Stack, { as: "label", className: className, gap: labelHidden ? 0 : gap, children: [labelText, children] }));
     }
     if (adorned && children.type !== 'input')
         throw new TypeError('Field prefix and suffix require a native input child');
@@ -63,6 +92,26 @@ export function Field(props) {
         'aria-invalid': marksInvalid ? true : children.props['aria-invalid'],
         'aria-labelledby': adornment.labelledBy,
         required: required || children.props.required,
+        ...(search
+            ? {
+                type: 'search',
+                enterKeyHint: children.props.enterKeyHint ?? 'search',
+                // Escape empties the box through onClear, the one clearing path
+                // (WebKit and Blink would otherwise clear it themselves).
+                onKeyDown: (event) => {
+                    children.props.onKeyDown?.(event);
+                    if (event.key === 'Escape' &&
+                        !event.defaultPrevented &&
+                        !event.currentTarget.readOnly &&
+                        event.currentTarget.value !== '') {
+                        event.preventDefault();
+                        onClear?.();
+                    }
+                },
+            }
+            : {}),
     });
-    return (_jsxs(Stack, { as: "div", className: className, gap: labelVisuallyHidden ? 0 : gap, children: [_jsx("label", { htmlFor: children.props.id || controlId, id: labelId, children: labelText }), adorned ? (_jsx(FieldAdornment, { prefix: prefix, prefixId: prefixId, suffix: suffix, suffixId: suffixId, children: control })) : (control), description && !error ? (_jsx("span", { className: "sw-field-description", id: descriptionId, children: description })) : null, _jsx(FieldErrorRegion, { className: "sw-field-error", id: errorId, message: error })] }));
+    const value = children.props.value;
+    const hasText = value !== undefined && value !== null && String(value) !== '';
+    return (_jsxs(Stack, { as: "div", className: className, gap: labelHidden ? 0 : gap, children: [_jsx("label", { className: search ? 'sw-sr-only' : undefined, htmlFor: children.props.id || controlId, id: labelId, children: labelText }), search ? (_jsx(SearchFrame, { clearLabel: clearLabel, leading: leading, onClear: onClear, showClear: hasText && !children.props.disabled && !children.props.readOnly, children: control })) : adorned ? (_jsx(FieldAdornment, { prefix: prefix, prefixId: prefixId, suffix: suffix, suffixId: suffixId, children: control })) : (control), description && !error ? (_jsx("span", { className: "sw-field-description", id: descriptionId, children: description })) : null, _jsx(FieldErrorRegion, { className: "sw-field-error", id: errorId, message: error })] }));
 }

package/dist/components/combobox/ComboboxPopup.d.ts

@@ -0,0 +1,25 @@
+import { type RefObject } from 'react';
+import { type ComboboxEntry } from './entries.js';
+import { type ComboboxGroup } from './types.js';
+type ComboboxPopupProps = {
+    listId: string;
+    listLabel: string;
+    groups: readonly ComboboxGroup[];
+    entries: readonly ComboboxEntry[];
+    activeId: string | undefined;
+    emptyText: string;
+    note?: string;
+    noteId: string;
+    inputRef: RefObject<HTMLInputElement | null>;
+    onActivate: (entry: ComboboxEntry) => void;
+    onChoose: (entry: ComboboxEntry) => void;
+    onDismiss: () => void;
+};
+/**
+ * The open list beside the input, on the popover layer and at least as
+ * wide as the input: a heading per group, each option's label, badge and
+ * description, then the action; the empty text when nothing matches, and
+ * the note under it all.
+ */
+export declare function ComboboxPopup({ activeId, emptyText, entries, groups, inputRef, listId, listLabel, note, noteId, onActivate, onChoose, onDismiss, }: ComboboxPopupProps): import("react").JSX.Element;
+export {};

package/dist/components/combobox/ComboboxPopup.js

@@ -0,0 +1,68 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment, useLayoutEffect, useRef, } from 'react';
+import { cx } from '../../class-names.js';
+import { Badge } from '../Badge.js';
+import { useAnchoredPopover } from '../use-anchored-popover.js';
+function keepInputFocus(event) {
+    // A press in the list never takes focus from the input.
+    event.preventDefault();
+}
+function EntryBadge({ badge }) {
+    if (!badge)
+        return null;
+    return (_jsx(Badge, { size: "sm", tone: badge.tone ?? 'neutral', children: badge.label }));
+}
+/**
+ * The open list beside the input, on the popover layer and at least as
+ * wide as the input: a heading per group, each option's label, badge and
+ * description, then the action; the empty text when nothing matches, and
+ * the note under it all.
+ */
+export function ComboboxPopup({ activeId, emptyText, entries, groups, inputRef, listId, listLabel, note, noteId, onActivate, onChoose, onDismiss, }) {
+    const popupRef = useRef(null);
+    useAnchoredPopover(popupRef, inputRef, inputRef, onDismiss, {
+        align: 'start',
+        flipInline: true,
+    });
+    // At least as wide as the input, and kept so when the input resizes.
+    useLayoutEffect(() => {
+        const popup = popupRef.current;
+        const input = inputRef.current;
+        if (!popup || !input)
+            return;
+        const fit = () => {
+            popup.style.minWidth = `${input.offsetWidth}px`;
+        };
+        fit();
+        if (typeof ResizeObserver === 'undefined')
+            return;
+        const observer = new ResizeObserver(fit);
+        observer.observe(input);
+        return () => observer.disconnect();
+    }, [inputRef]);
+    useLayoutEffect(() => {
+        if (activeId)
+            document.getElementById(activeId)?.scrollIntoView?.({ block: 'nearest' });
+    }, [activeId]);
+    const options = entries.filter((entry) => entry.kind === 'option');
+    const action = entries.find((entry) => entry.kind === 'action');
+    function renderEntry(entry) {
+        const disabled = entry.kind === 'option' && entry.option.disabled;
+        return (_jsx("div", { "aria-disabled": disabled || undefined, "aria-selected": entry.id === activeId, className: cx('sw-combobox-option', entry.kind === 'action' && 'sw-combobox-action'), id: entry.id, onClick: () => onChoose(entry), onMouseDown: keepInputFocus, 
+            // The pointer moves the active option, as the arrow keys do.
+            onMouseMove: () => {
+                if (entry.id !== activeId)
+                    onActivate(entry);
+            }, role: "option", children: entry.kind === 'option' ? (_jsxs(_Fragment, { children: [_jsx("span", { className: "sw-combobox-label", children: entry.option.label }), _jsx(EntryBadge, { badge: entry.option.badge }), entry.option.description ? (_jsx("span", { className: "sw-combobox-description", children: entry.option.description })) : null] })) : (_jsxs(_Fragment, { children: [_jsx("span", { className: "sw-combobox-label", children: entry.action.label }), _jsx(EntryBadge, { badge: entry.action.badge })] })) }, entry.id));
+    }
+    return (_jsxs("div", { className: "sw-combobox-popup", onMouseDown: keepInputFocus, ref: popupRef, children: [entries.length > 0 ? (_jsxs("div", { "aria-label": listLabel, className: "sw-combobox-list", id: listId, role: "listbox", children: [groups.map((group, groupIndex) => {
+                        const groupEntries = options.filter((entry) => entry.kind === 'option' && entry.groupIndex === groupIndex);
+                        if (groupEntries.length === 0)
+                            return null;
+                        if (!group.label)
+                            return (_jsx(Fragment, { children: groupEntries.map(renderEntry) }, `${listId}-group-${groupIndex}`));
+                        const headingId = `${listId}-group-${groupIndex}`;
+                        return (_jsxs("div", { "aria-labelledby": headingId, role: "group", children: [_jsx("div", { className: "sw-combobox-heading", id: headingId, role: "presentation", children: group.label }), groupEntries.map(renderEntry)] }, headingId));
+                    }), action ? renderEntry(action) : null] })) : null, options.length === 0 ? (_jsx("div", { "aria-hidden": "true", className: "sw-combobox-empty", children: emptyText })) : null, note ? (_jsx("div", { className: "sw-combobox-note", id: noteId, children: note })) : null] }));
+}

package/dist/components/combobox/entries.d.ts

@@ -0,0 +1,18 @@
+import { type ComboboxAction, type ComboboxGroup, type ComboboxOption } from './types.js';
+/** One row the arrow keys move over: an option in a group, or the action. */
+export type ComboboxEntry = {
+    kind: 'option';
+    key: string;
+    id: string;
+    index: number;
+    option: ComboboxOption;
+    groupIndex: number;
+} | {
+    kind: 'action';
+    key: string;
+    id: string;
+    index: number;
+    action: ComboboxAction;
+};
+/** The list's rows in order, each with a stable key and a DOM id under `listId`. */
+export declare function comboboxEntries(listId: string, groups: readonly ComboboxGroup[], action: ComboboxAction | undefined): ComboboxEntry[];

package/dist/components/combobox/entries.js

@@ -0,0 +1,34 @@
+/*
+ * Each row's key and DOM id come from its value, not its place, so an
+ * option keeps its id (and stays the active one) when the consumer's
+ * results change under it, and a new option never inherits an old id.
+ */
+const encoder = new TextEncoder();
+/** The value as hex, so any value makes a unique, valid id part. */
+function idPart(value) {
+    return Array.from(encoder.encode(value), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/** The list's rows in order, each with a stable key and a DOM id under `listId`. */
+export function comboboxEntries(listId, groups, action) {
+    const entries = [];
+    groups.forEach((group, groupIndex) => {
+        for (const option of group.options)
+            entries.push({
+                kind: 'option',
+                key: `option:${option.value}`,
+                id: `${listId}-option-${idPart(option.value)}`,
+                index: entries.length,
+                option,
+                groupIndex,
+            });
+    });
+    if (action)
+        entries.push({
+            kind: 'action',
+            key: 'action',
+            id: `${listId}-action`,
+            index: entries.length,
+            action,
+        });
+    return entries;
+}

package/dist/components/combobox/types.d.ts

@@ -0,0 +1,63 @@
+import { type BadgeTone } from '../../css/css-data.js';
+/** A short tag after an option's label, such as "Warning" or "Blocked". */
+export type ComboboxBadge = {
+    label: string;
+    tone?: BadgeTone;
+};
+/** One suggestion in a Combobox. */
+export type ComboboxOption = {
+    value: string;
+    label: string;
+    /** A muted line of detail after the label, such as "3 items · updated Sep 28". */
+    description?: string;
+    badge?: ComboboxBadge;
+    /** Shown, read as unavailable, and never chosen, such as an archived item. */
+    disabled?: boolean;
+};
+/** A run of suggestions under a heading, such as "All items". */
+export type ComboboxGroup = {
+    /** The group's heading; a group without one has no heading. */
+    label?: string;
+    options: readonly ComboboxOption[];
+};
+/** A command at the end of the list, such as "+ New entry “acme”". */
+export type ComboboxAction = {
+    label: string;
+    onPress: () => void;
+    badge?: ComboboxBadge;
+};
+export declare const comboboxSizes: readonly ["md", "xs"];
+export type ComboboxSize = (typeof comboboxSizes)[number];
+export type ComboboxProps = {
+    /** The input's name, drawn above it unless `labelVisuallyHidden`. */
+    label: string;
+    labelVisuallyHidden?: boolean;
+    /** The text in the input; the consumer filters `groups` from it. */
+    inputValue: string;
+    onInputChange: (value: string) => void;
+    groups: readonly ComboboxGroup[];
+    /** Called with the chosen option's value; the consumer sets `inputValue`. */
+    onSelect: (value: string) => void;
+    action?: ComboboxAction;
+    /**
+     * Shown in the list, and announced, when no group has an option, such as
+     * "Nothing matches".
+     */
+    emptyText: string;
+    /**
+     * The words announced for the number of options while the list is open,
+     * such as `(n) => \`${n} items\``; without it only the empty text is
+     * announced.
+     */
+    countText?: (count: number) => string;
+    /** The list's name when it differs from the input's, such as "Results". */
+    listLabel?: string;
+    /** A muted line under the suggestions, such as how to find more. */
+    note?: string;
+    placeholder?: string;
+    description?: string;
+    error?: string;
+    required?: boolean;
+    disabled?: boolean;
+    size?: ComboboxSize;
+};

package/dist/components/combobox/types.js

@@ -0,0 +1 @@
+export const comboboxSizes = ['md', 'xs'];

package/dist/components/combobox/validate.d.ts

@@ -0,0 +1,3 @@
+import { type ComboboxProps } from './types.js';
+/** Fails closed on blank words, duplicate values and unknown sizes. */
+export declare function assertCombobox(props: ComboboxProps): void;

package/dist/components/combobox/validate.js

@@ -0,0 +1,44 @@
+import { badgeTones } from '../../css/css-data.js';
+import { comboboxSizes, } from './types.js';
+function blank(text) {
+    return typeof text !== 'string' || !text.trim();
+}
+function assertBadge(badge) {
+    if (badge === undefined)
+        return;
+    if (blank(badge.label))
+        throw new RangeError('A Combobox badge needs a nonempty label');
+    if (badge.tone !== undefined && !badgeTones.includes(badge.tone))
+        throw new RangeError(`Unknown Combobox badge tone: ${String(badge.tone)}`);
+}
+/** Fails closed on blank words, duplicate values and unknown sizes. */
+export function assertCombobox(props) {
+    if (blank(props.label))
+        throw new RangeError('Combobox needs a nonempty label');
+    if (blank(props.emptyText))
+        throw new RangeError('Combobox needs a nonempty emptyText');
+    if (props.listLabel !== undefined && blank(props.listLabel))
+        throw new RangeError('A Combobox listLabel must not be blank');
+    if (props.size !== undefined && !comboboxSizes.includes(props.size))
+        throw new RangeError(`Unknown Combobox size: ${String(props.size)}`);
+    const values = new Set();
+    for (const group of props.groups) {
+        if (group.label !== undefined && blank(group.label))
+            throw new RangeError('A Combobox group label must not be blank');
+        for (const option of group.options) {
+            if (blank(option.value) || blank(option.label))
+                throw new RangeError('Combobox options need nonempty values and labels');
+            if (values.has(option.value))
+                throw new RangeError(`Duplicate Combobox option: ${option.value}`);
+            values.add(option.value);
+            assertBadge(option.badge);
+        }
+    }
+    if (props.action) {
+        if (blank(props.action.label))
+            throw new RangeError('A Combobox action needs a nonempty label');
+        if (typeof props.action.onPress !== 'function')
+            throw new TypeError('A Combobox action needs onPress');
+        assertBadge(props.action.badge);
+    }
+}

package/dist/components/field/SearchFrame.d.ts

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react';
+type SearchFrameProps = {
+    children: ReactNode;
+    leading?: ReactNode;
+    clearLabel: string;
+    /** Shown while the input holds text and is enabled. */
+    showClear: boolean;
+    onClear: () => void;
+};
+/**
+ * The search field's frame: the consumer's glyph at the start (hidden from
+ * assistive technology), the input, and a clear button at the end while
+ * there is text. Clearing calls `onClear` and puts focus back in the input.
+ */
+export declare function SearchFrame({ children, clearLabel, leading, onClear, showClear, }: SearchFrameProps): import("react").JSX.Element;
+export {};

package/dist/components/field/SearchFrame.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * A press on the frame's chrome (the glyph or the padding) focuses the
+ * input, as on an adorned field; a press on the input keeps the browser's
+ * own caret placement, and the clear button runs its own action.
+ */
+function focusSearchInput(event) {
+    const input = event.currentTarget.querySelector('input');
+    const target = event.target;
+    if (!input || input.disabled || target === input)
+        return;
+    event.preventDefault();
+    // The clear button keeps focus in the input: no blur, and its click
+    // still runs.
+    if (target.closest('.sw-field-search-clear'))
+        return;
+    input.focus();
+}
+/**
+ * The search field's frame: the consumer's glyph at the start (hidden from
+ * assistive technology), the input, and a clear button at the end while
+ * there is text. Clearing calls `onClear` and puts focus back in the input.
+ */
+export function SearchFrame({ children, clearLabel, leading, onClear, showClear, }) {
+    return (_jsxs("span", { className: "sw-field-adorned sw-field-search", onMouseDown: focusSearchInput, children: [leading != null && leading !== false ? (_jsx("span", { "aria-hidden": "true", className: "sw-field-search-leading", children: leading })) : null, children, showClear ? (_jsx("button", { "aria-label": clearLabel, className: "sw-field-search-clear", onClick: (event) => {
+                    // Focus first, so a consumer that moves focus in onClear wins.
+                    event.currentTarget.parentElement
+                        ?.querySelector('input')
+                        ?.focus();
+                    onClear();
+                }, type: "button", children: _jsx("span", { "aria-hidden": "true", className: "sw-field-search-cross" }) })) : null] }));
+}

package/dist/css/css-combobox.d.ts

@@ -0,0 +1,2 @@
+export declare function cssComboboxClasses(): string;
+export declare function comboboxClassCatalog(): string[];

package/dist/css/css-combobox.js

@@ -0,0 +1,135 @@
+import { typographyVariants } from '@scalewing/tokens';
+import { zIndex } from './stacking.js';
+const caption = typographyVariants.caption;
+const label = typographyVariants.label;
+/*
+ * The combobox input is a Field's input. Its list is a glass popover on
+ * the popup layer (as Select's list), at least as wide as the input: a
+ * caption heading per group, then options at the md control height with
+ * the label, a badge and a muted description on one wrapping line. The
+ * active option (the one aria-activedescendant names) takes the soft
+ * muted fill; a hairline parts each option from the one before it, as
+ * the boards draw it; a disabled option is muted and not pressable; the action
+ * ends the list in the accent colour over a hairline. The empty text and
+ * the note are muted captions under the list.
+ */
+export function cssComboboxClasses() {
+    return `.sw-combobox {
+  max-width: 100%;
+  min-width: 0;
+}
+
+.sw-combobox-popup {
+  background: var(--sw-glass-fill);
+  border: 1px solid var(--sw-glass-border);
+  border-radius: var(--sw-radius-sm);
+  box-shadow: var(--sw-elevation-sm), inset 0 1px 0 var(--sw-glass-specular);
+  backdrop-filter: blur(var(--sw-glass-blur)) saturate(var(--sw-glass-saturate));
+  -webkit-backdrop-filter: blur(var(--sw-glass-blur)) saturate(var(--sw-glass-saturate));
+  box-sizing: border-box;
+  color: var(--sw-color-text);
+  inset: auto;
+  margin: 0;
+  max-height: min(var(--sw-select-max), calc(100% - var(--sw-space-2) - var(--sw-space-2)));
+  max-width: calc(100% - var(--sw-space-2) - var(--sw-space-2));
+  overflow: auto;
+  padding: var(--sw-space-1);
+  position: fixed;
+  ${zIndex('popup')}
+}
+
+.sw-combobox-heading {
+  color: var(--sw-color-muted);
+  font-family: var(--sw-font-sans);
+  font-size: ${caption.fontSize}px;
+  font-weight: ${label.fontWeight};
+  letter-spacing: ${caption.letterSpacing}px;
+  line-height: ${caption.lineHeight}px;
+  padding: var(--sw-space-2) var(--sw-space-3) var(--sw-space-1);
+}
+
+.sw-combobox-option {
+  align-items: center;
+  border-radius: var(--sw-radius-sm);
+  box-sizing: border-box;
+  column-gap: var(--sw-space-2);
+  cursor: pointer;
+  display: flex;
+  flex-wrap: wrap;
+  font-family: var(--sw-font-sans);
+  font-size: ${label.fontSize}px;
+  letter-spacing: ${label.letterSpacing}px;
+  line-height: ${label.lineHeight}px;
+  min-height: var(--sw-control-md-min-height);
+  overflow-wrap: anywhere;
+  padding: var(--sw-space-1) var(--sw-space-3);
+}
+
+.sw-combobox-option + .sw-combobox-option {
+  border-top: 1px solid var(--sw-color-border);
+}
+
+.sw-combobox-label {
+  font-weight: ${label.fontWeight};
+}
+
+.sw-combobox-description {
+  color: var(--sw-color-muted);
+  font-size: ${caption.fontSize}px;
+  letter-spacing: ${caption.letterSpacing}px;
+  line-height: ${caption.lineHeight}px;
+}
+
+.sw-combobox-option[aria-selected='true'] {
+  background: color-mix(in srgb, var(--sw-color-muted) 16%, transparent);
+}
+
+.sw-combobox-option[aria-disabled='true'] {
+  cursor: not-allowed;
+}
+
+.sw-combobox-option[aria-disabled='true'] .sw-combobox-label {
+  color: var(--sw-color-muted);
+}
+
+.sw-combobox-action {
+  border-top: 1px solid var(--sw-color-border);
+  color: var(--sw-color-accent);
+  margin-top: var(--sw-space-1);
+}
+
+.sw-combobox-empty,
+.sw-combobox-note {
+  color: var(--sw-color-muted);
+  font-family: var(--sw-font-sans);
+  font-size: ${caption.fontSize}px;
+  letter-spacing: ${caption.letterSpacing}px;
+  line-height: ${caption.lineHeight}px;
+  padding: var(--sw-space-2) var(--sw-space-3);
+}
+
+@media (forced-colors: active) {
+  .sw-combobox-popup { border-color: CanvasText; }
+  .sw-combobox-option[aria-selected='true'] { background: Highlight; color: HighlightText; forced-color-adjust: none; }
+  .sw-combobox-option[aria-selected='true'] .sw-combobox-description { color: HighlightText; }
+  .sw-combobox-option[aria-selected='true'] .sw-badge { forced-color-adjust: auto; }
+  .sw-combobox-option[aria-disabled='true'] .sw-combobox-label { color: GrayText; }
+  .sw-combobox-option[aria-selected='true'][aria-disabled='true'] .sw-combobox-label { color: HighlightText; }
+  .sw-combobox-option + .sw-combobox-option { border-color: CanvasText; }
+  .sw-combobox-action { border-color: CanvasText; }
+}`;
+}
+export function comboboxClassCatalog() {
+    return [
+        'sw-combobox',
+        'sw-combobox-popup',
+        'sw-combobox-list',
+        'sw-combobox-heading',
+        'sw-combobox-option',
+        'sw-combobox-label',
+        'sw-combobox-description',
+        'sw-combobox-action',
+        'sw-combobox-empty',
+        'sw-combobox-note',
+    ];
+}

package/dist/css/css-components.js

@@ -14,6 +14,7 @@ import { cssTableClasses } from './css-table.js';
 import { cssDateFieldClasses } from './css-date-field.js';
 import { cssDialogClasses } from './css-dialog.js';
 import { cssDialogFrameClasses } from './css-dialog-frame.js';
+import { cssComboboxClasses } from './css-combobox.js';
 import { cssSelectClasses } from './css-select.js';
 import { cssMultiSelectClasses } from './css-multi-select.js';
 import { cssSplitClasses } from './css-split.js';
@@ -64,6 +65,7 @@ function reducedTransparencyRules() {
   .sw-select-list,
   .sw-action-menu-list,
   .sw-multi-select-panel,
+  .sw-combobox-popup,
   .sw-date-field-calendar,
   .sw-toast {
     background: var(--sw-color-surface);
@@ -148,6 +150,7 @@ ${cssSelectClasses()}
 
 ${cssActionMenuClasses()}
 
+${cssComboboxClasses()}
 ${cssMultiSelectClasses()}
 
 ${cssActionBarClasses()}

package/dist/css/css-field-search.d.ts

@@ -0,0 +1,2 @@
+export declare function cssFieldSearchClasses(): string;
+export declare function fieldSearchClassCatalog(): string[];

package/dist/css/css-field-search.js

@@ -0,0 +1,118 @@
+import { coarsePointerQuery, touchTarget } from './touch-target.js';
+/*
+ * A search field is the adorned frame (the control surface, its focus
+ * ring, its danger and disabled looks) with the consumer's glyph in the
+ * muted colour at its start, a space-2 gap, and a clear button at its end:
+ * a muted disc with a cross in the surface colour, centred in an xs control
+ * square (the 44 px target on a coarse pointer) that reaches the frame's
+ * edge. The browser's own clear button and search glyph are hidden, so the
+ * field shows one of each.
+ */
+export function cssFieldSearchClasses() {
+    return `.sw-field-adorned.sw-field-search {
+  gap: var(--sw-space-2);
+  padding-inline-end: 0;
+}
+
+.sw-field-search-leading {
+  color: var(--sw-color-muted);
+  display: inline-flex;
+  flex: none;
+}
+
+[data-theme] .sw-field-search > input[type='search'] {
+  appearance: none;
+  -webkit-appearance: none;
+}
+
+.sw-field-search > input[type='search']::-webkit-search-cancel-button,
+.sw-field-search > input[type='search']::-webkit-search-decoration {
+  -webkit-appearance: none;
+  appearance: none;
+  display: none;
+}
+
+.sw-field-search > input:last-child {
+  margin-inline-end: var(--sw-control-md-padding-inline);
+}
+
+.sw-field-search-clear {
+  align-items: center;
+  align-self: stretch;
+  appearance: none;
+  background: transparent;
+  border: 0;
+  border-radius: var(--sw-radius-sm);
+  color: inherit;
+  cursor: pointer;
+  display: inline-flex;
+  flex: none;
+  justify-content: center;
+  margin: 0;
+  min-width: var(--sw-control-xs-min-height);
+  padding: 0 var(--sw-space-2);
+}
+
+.sw-field-search-clear:focus-visible {
+  outline: var(--sw-focus-ring-width) solid var(--sw-color-accent);
+  outline-offset: calc(-1 * var(--sw-focus-ring-width));
+}
+
+/* One ring at a time: the clear button's own while it has focus. */
+.sw-field-search:has(.sw-field-search-clear:focus-visible) {
+  outline: none;
+}
+
+.sw-field-search-clear:hover .sw-field-search-cross {
+  background: var(--sw-color-text);
+}
+
+.sw-field-xs .sw-field-search > input:last-child {
+  margin-inline-end: var(--sw-control-xs-padding-inline);
+}
+
+.sw-field-search-cross {
+  background: var(--sw-color-muted);
+  border-radius: var(--sw-radius-pill);
+  display: inline-block;
+  height: var(--sw-space-4);
+  position: relative;
+  width: var(--sw-space-4);
+}
+
+.sw-field-search-cross::before,
+.sw-field-search-cross::after {
+  background: var(--sw-color-surface);
+  border-radius: 1px;
+  content: '';
+  height: 2px;
+  inset: 0;
+  margin: auto;
+  position: absolute;
+  width: calc(var(--sw-space-2) + 2px);
+}
+
+.sw-field-search-cross::before { transform: rotate(45deg); }
+.sw-field-search-cross::after { transform: rotate(-45deg); }
+
+@media ${coarsePointerQuery} {
+  .sw-field-search-clear { min-width: ${touchTarget}; }
+}
+
+@media (forced-colors: active) {
+  .sw-field-search-leading { color: FieldText; }
+  /* Backgrounds are forced in this mode; the disc keeps its own system colours. */
+  .sw-field-search-cross { background: ButtonText; forced-color-adjust: none; }
+  .sw-field-search-cross::before,
+  .sw-field-search-cross::after { background: ButtonFace; }
+}`;
+}
+export function fieldSearchClassCatalog() {
+    return [
+        'sw-field-search-field',
+        'sw-field-search',
+        'sw-field-search-leading',
+        'sw-field-search-clear',
+        'sw-field-search-cross',
+    ];
+}

package/dist/css/css-field.js

@@ -1,6 +1,7 @@
 import { typographyVariants } from '@scalewing/tokens';
 import { controlSurface, disabledControlForcedColors, disabledControlSurface, } from './css-document.js';
 import { cssFieldChangedClasses } from './css-field-changed.js';
+import { cssFieldSearchClasses, fieldSearchClassCatalog, } from './css-field-search.js';
 const caption = typographyVariants.caption;
 /*
  * A prefix or suffix sits inside the control frame: the wrapper draws the
@@ -83,6 +84,8 @@ export function cssFieldClasses() {
 
 ${adornmentRules()}
 
+${cssFieldSearchClasses()}
+
 ${cssFieldChangedClasses()}
 
 @media (forced-colors: active) {
@@ -106,5 +109,6 @@ export function fieldClassCatalog() {
         'sw-field-adorned',
         'sw-field-prefix',
         'sw-field-suffix',
+        ...fieldSearchClassCatalog(),
     ];
 }

package/dist/css/stacking.js

@@ -17,7 +17,7 @@
  *    surface that scrolls up under it (the header is the page's way back, the
  *    strip its way between sections, and a popup opens downward).
  * 6. `popup`: a popup outside any lifted surface (Select list, ActionMenu
- *    list, MultiSelect panel, Tooltip, the DateField and CalendarButton
+ *    list, MultiSelect panel, Combobox list, Tooltip, the DateField and CalendarButton
  *    calendar) over everything in the page.
  *
  * Dialog and Toast sit on the browser's top layer, above all of these.
@@ -53,6 +53,9 @@ const openPopups = [
     // MultiSelect's panel. Rendered only while open; on the top layer where
     // the popover API exists.
     '.sw-multi-select-panel',
+    // Combobox's list. Rendered only while open; on the top layer where the
+    // popover API exists.
+    '.sw-combobox-popup',
     '.sw-tooltip:not([hidden])',
     // DateField and CalendarButton share it. Rendered only while open; on the
     // top layer where the popover API exists.

package/dist/css/stylesheet.js

@@ -39,6 +39,7 @@ import { dialogClassCatalog } from './css-dialog.js';
 import { dialogFrameClassCatalog } from './css-dialog-frame.js';
 import { selectClassCatalog } from './css-select.js';
 import { multiSelectClassCatalog } from './css-multi-select.js';
+import { comboboxClassCatalog } from './css-combobox.js';
 import { splitClassCatalog } from './css-split.js';
 import { toastClassCatalog } from './css-toast.js';
 import { toastCardClassCatalog } from './css-toast-card.js';
@@ -74,6 +75,7 @@ export function utilityClassCatalog() {
         ...selectClassCatalog(),
         ...actionMenuClassCatalog(),
         ...multiSelectClassCatalog(),
+        ...comboboxClassCatalog(),
         ...actionBarClassCatalog(),
         ...switchClassCatalog(),
         ...dateFieldClassCatalog(),

package/dist/index.d.ts

@@ -25,7 +25,7 @@ export { StatTile, type StatTileEmphasis, type StatTileProps, type StatTileTone,
 export { TabPanel, type TabItem, type TabPanelProps, Tabs, type TabsProps, tabId, tabPanelId, } from './components/Tabs.js';
 export { Toast, toastPlacements, toastTones, type ToastAction, type ToastPlacement, } from './components/Toast.js';
 export type { ToastProps, ToastTone } from './components/Toast.js';
-export { Field, type FieldProps, type FieldSize } from './components/Field.js';
+export { Field, fieldVariants, type FieldProps, type FieldSize, type FieldVariant, } from './components/Field.js';
 export { Step, type StepHeadingLevel, type StepProps, Steps, type StepsLabels, type StepsProps, type StepStatus, } from './components/Steps.js';
 export { Stepper, type StepperProps, type StepperWidth, } from './components/Stepper.js';
 export { Inline, type InlineProps } from './components/Inline.js';
@@ -34,6 +34,7 @@ export type { SplitProps } from './components/Split.js';
 export { Nav, type NavProps } from './components/Nav.js';
 export { SectionNav, sectionNavAppearances, type SectionNavAppearance, type SectionNavItem, type SectionNavProps, } from './components/SectionNav.js';
 export { SegmentedControl, type SegmentedControlProps, type SegmentedControlVariant, type SegmentedItem, } from './components/SegmentedControl.js';
+export { Combobox, comboboxSizes, type ComboboxAction, type ComboboxBadge, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type ComboboxSize, } from './components/Combobox.js';
 export { Select } from './components/Select.js';
 export type { SelectAction, SelectOption, SelectProps, SelectWidth, } from './components/Select.js';
 export { MultiSelect, type MultiSelectAlign, type MultiSelectOption, type MultiSelectProps, } from './components/MultiSelect.js';

package/dist/index.js

@@ -23,7 +23,7 @@ export { Dialog, dialogSizes, } from './components/Dialog.js';
 export { StatTile, statTileTones, } from './components/StatTile.js';
 export { TabPanel, Tabs, tabId, tabPanelId, } from './components/Tabs.js';
 export { Toast, toastPlacements, toastTones, } from './components/Toast.js';
-export { Field } from './components/Field.js';
+export { Field, fieldVariants, } from './components/Field.js';
 export { Step, Steps, } from './components/Steps.js';
 export { Stepper, } from './components/Stepper.js';
 export { Inline } from './components/Inline.js';
@@ -31,6 +31,7 @@ export { Split } from './components/Split.js';
 export { Nav } from './components/Nav.js';
 export { SectionNav, sectionNavAppearances, } from './components/SectionNav.js';
 export { SegmentedControl, } from './components/SegmentedControl.js';
+export { Combobox, comboboxSizes, } from './components/Combobox.js';
 export { Select } from './components/Select.js';
 export { MultiSelect, } from './components/MultiSelect.js';
 export { Stack, } from './components/Stack.js';

package/dist/styles.css

@@ -828,8 +828,8 @@ body {
 }
 
 /* Backdrop blur makes a glass surface its own stacking context, so it lifts while it holds an open popup (see stacking.ts). */
-.sw-card-glass:has(.sw-select-list, .sw-action-menu-list, .sw-multi-select-panel, .sw-tooltip:not([hidden]), .sw-date-field-calendar),
-.sw-accordion:has(.sw-select-list, .sw-action-menu-list, .sw-multi-select-panel, .sw-tooltip:not([hidden]), .sw-date-field-calendar) {
+.sw-card-glass:has(.sw-select-list, .sw-action-menu-list, .sw-multi-select-panel, .sw-combobox-popup, .sw-tooltip:not([hidden]), .sw-date-field-calendar),
+.sw-accordion:has(.sw-select-list, .sw-action-menu-list, .sw-multi-select-panel, .sw-combobox-popup, .sw-tooltip:not([hidden]), .sw-date-field-calendar) {
   position: relative;
   z-index: 4;
 }
@@ -3020,6 +3020,110 @@ body {
   }
 }
 
+.sw-combobox {
+  max-width: 100%;
+  min-width: 0;
+}
+
+.sw-combobox-popup {
+  background: var(--sw-glass-fill);
+  border: 1px solid var(--sw-glass-border);
+  border-radius: var(--sw-radius-sm);
+  box-shadow: var(--sw-elevation-sm), inset 0 1px 0 var(--sw-glass-specular);
+  backdrop-filter: blur(var(--sw-glass-blur)) saturate(var(--sw-glass-saturate));
+  -webkit-backdrop-filter: blur(var(--sw-glass-blur)) saturate(var(--sw-glass-saturate));
+  box-sizing: border-box;
+  color: var(--sw-color-text);
+  inset: auto;
+  margin: 0;
+  max-height: min(var(--sw-select-max), calc(100% - var(--sw-space-2) - var(--sw-space-2)));
+  max-width: calc(100% - var(--sw-space-2) - var(--sw-space-2));
+  overflow: auto;
+  padding: var(--sw-space-1);
+  position: fixed;
+  z-index: 10;
+}
+
+.sw-combobox-heading {
+  color: var(--sw-color-muted);
+  font-family: var(--sw-font-sans);
+  font-size: 13px;
+  font-weight: 600;
+  letter-spacing: -0.08px;
+  line-height: 18px;
+  padding: var(--sw-space-2) var(--sw-space-3) var(--sw-space-1);
+}
+
+.sw-combobox-option {
+  align-items: center;
+  border-radius: var(--sw-radius-sm);
+  box-sizing: border-box;
+  column-gap: var(--sw-space-2);
+  cursor: pointer;
+  display: flex;
+  flex-wrap: wrap;
+  font-family: var(--sw-font-sans);
+  font-size: 15px;
+  letter-spacing: -0.2px;
+  line-height: 20px;
+  min-height: var(--sw-control-md-min-height);
+  overflow-wrap: anywhere;
+  padding: var(--sw-space-1) var(--sw-space-3);
+}
+
+.sw-combobox-option + .sw-combobox-option {
+  border-top: 1px solid var(--sw-color-border);
+}
+
+.sw-combobox-label {
+  font-weight: 600;
+}
+
+.sw-combobox-description {
+  color: var(--sw-color-muted);
+  font-size: 13px;
+  letter-spacing: -0.08px;
+  line-height: 18px;
+}
+
+.sw-combobox-option[aria-selected='true'] {
+  background: color-mix(in srgb, var(--sw-color-muted) 16%, transparent);
+}
+
+.sw-combobox-option[aria-disabled='true'] {
+  cursor: not-allowed;
+}
+
+.sw-combobox-option[aria-disabled='true'] .sw-combobox-label {
+  color: var(--sw-color-muted);
+}
+
+.sw-combobox-action {
+  border-top: 1px solid var(--sw-color-border);
+  color: var(--sw-color-accent);
+  margin-top: var(--sw-space-1);
+}
+
+.sw-combobox-empty,
+.sw-combobox-note {
+  color: var(--sw-color-muted);
+  font-family: var(--sw-font-sans);
+  font-size: 13px;
+  letter-spacing: -0.08px;
+  line-height: 18px;
+  padding: var(--sw-space-2) var(--sw-space-3);
+}
+
+@media (forced-colors: active) {
+  .sw-combobox-popup { border-color: CanvasText; }
+  .sw-combobox-option[aria-selected='true'] { background: Highlight; color: HighlightText; forced-color-adjust: none; }
+  .sw-combobox-option[aria-selected='true'] .sw-combobox-description { color: HighlightText; }
+  .sw-combobox-option[aria-selected='true'] .sw-badge { forced-color-adjust: auto; }
+  .sw-combobox-option[aria-disabled='true'] .sw-combobox-label { color: GrayText; }
+  .sw-combobox-option[aria-selected='true'][aria-disabled='true'] .sw-combobox-label { color: HighlightText; }
+  .sw-combobox-option + .sw-combobox-option { border-color: CanvasText; }
+  .sw-combobox-action { border-color: CanvasText; }
+}
 .sw-multi-select {
   display: inline-flex;
   max-width: 100%;
@@ -4516,6 +4620,104 @@ body {
 
 [data-theme] .sw-field-adorned > input:disabled { background: transparent; }
 
+.sw-field-adorned.sw-field-search {
+  gap: var(--sw-space-2);
+  padding-inline-end: 0;
+}
+
+.sw-field-search-leading {
+  color: var(--sw-color-muted);
+  display: inline-flex;
+  flex: none;
+}
+
+[data-theme] .sw-field-search > input[type='search'] {
+  appearance: none;
+  -webkit-appearance: none;
+}
+
+.sw-field-search > input[type='search']::-webkit-search-cancel-button,
+.sw-field-search > input[type='search']::-webkit-search-decoration {
+  -webkit-appearance: none;
+  appearance: none;
+  display: none;
+}
+
+.sw-field-search > input:last-child {
+  margin-inline-end: var(--sw-control-md-padding-inline);
+}
+
+.sw-field-search-clear {
+  align-items: center;
+  align-self: stretch;
+  appearance: none;
+  background: transparent;
+  border: 0;
+  border-radius: var(--sw-radius-sm);
+  color: inherit;
+  cursor: pointer;
+  display: inline-flex;
+  flex: none;
+  justify-content: center;
+  margin: 0;
+  min-width: var(--sw-control-xs-min-height);
+  padding: 0 var(--sw-space-2);
+}
+
+.sw-field-search-clear:focus-visible {
+  outline: var(--sw-focus-ring-width) solid var(--sw-color-accent);
+  outline-offset: calc(-1 * var(--sw-focus-ring-width));
+}
+
+/* One ring at a time: the clear button's own while it has focus. */
+.sw-field-search:has(.sw-field-search-clear:focus-visible) {
+  outline: none;
+}
+
+.sw-field-search-clear:hover .sw-field-search-cross {
+  background: var(--sw-color-text);
+}
+
+.sw-field-xs .sw-field-search > input:last-child {
+  margin-inline-end: var(--sw-control-xs-padding-inline);
+}
+
+.sw-field-search-cross {
+  background: var(--sw-color-muted);
+  border-radius: var(--sw-radius-pill);
+  display: inline-block;
+  height: var(--sw-space-4);
+  position: relative;
+  width: var(--sw-space-4);
+}
+
+.sw-field-search-cross::before,
+.sw-field-search-cross::after {
+  background: var(--sw-color-surface);
+  border-radius: 1px;
+  content: '';
+  height: 2px;
+  inset: 0;
+  margin: auto;
+  position: absolute;
+  width: calc(var(--sw-space-2) + 2px);
+}
+
+.sw-field-search-cross::before { transform: rotate(45deg); }
+.sw-field-search-cross::after { transform: rotate(-45deg); }
+
+@media (pointer: coarse) {
+  .sw-field-search-clear { min-width: var(--sw-control-md-min-height); }
+}
+
+@media (forced-colors: active) {
+  .sw-field-search-leading { color: FieldText; }
+  /* Backgrounds are forced in this mode; the disc keeps its own system colours. */
+  .sw-field-search-cross { background: ButtonText; forced-color-adjust: none; }
+  .sw-field-search-cross::before,
+  .sw-field-search-cross::after { background: ButtonFace; }
+}
+
 [data-theme] .sw-field-changed > :is(input, select, textarea),
 .sw-field-changed .sw-field-adorned {
   border-color: var(--sw-color-accent);
@@ -5118,6 +5320,7 @@ body {
   .sw-select-list,
   .sw-action-menu-list,
   .sw-multi-select-panel,
+  .sw-combobox-popup,
   .sw-date-field-calendar,
   .sw-toast {
     background: var(--sw-color-surface);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalewing/react",
-  "version": "1.30.0",
+  "version": "1.31.0",
   "description": "Scalewing DOM components and package-owned CSS utilities.",
   "type": "module",
   "license": "MIT",