@forwardreach/saas-ui 0.10.4 → 0.12.0

package/dist/components/combobox.d.ts

@@ -1,27 +1,6 @@
 import * as React from "react";
-export interface ComboboxOption {
-    value: string;
-    label: string;
-    /** Optional trailing content (e.g. a GMT offset) shown right-aligned. */
-    trailing?: React.ReactNode;
-    /**
-     * Optional secondary text shown next to the label, in the reading order a
-     * subtitle would take. Distinct from `trailing`, which is right-aligned and
-     * monospaced; an option may carry both.
-     */
-    description?: React.ReactNode;
-    /**
-     * Optional heading this option sits under. Consecutive options declaring the
-     * same group collapse into one heading, exactly as `<optgroup>` does — the
-     * component never reorders, so interleaved groups (`A, B, A`) render three
-     * headings, not two. Sort the list before passing it if that is not wanted.
-     *
-     * Grouped and ungrouped options may be mixed: an option declaring no group
-     * ends the run above it and renders outside every group, the way an
-     * `<option>` following an `</optgroup>` sits outside that group.
-     */
-    group?: string;
-}
+import type { ComboboxOption } from "./option-list.js";
+export type { ComboboxOption };
 export interface ComboboxProps {
     /** Full option list; the component filters it against the typed query. */
     options: ComboboxOption[];
@@ -35,8 +14,60 @@ export interface ComboboxProps {
     filter?: (option: ComboboxOption, query: string) => boolean;
     placeholder?: string;
     disabled?: boolean;
-    /** Message shown when no option matches. Defaults to "No matches". */
+    /**
+     * Message shown when no option matches. Defaults to "No matches". Not shown
+     * while a create entry is offered — the popup is offering an action, so
+     * saying there is nothing to do contradicts the row underneath it.
+     */
     emptyMessage?: React.ReactNode;
+    /**
+     * Offer the typed query as a new option. When set, a trailing create entry
+     * joins the listbox whenever the trimmed query is non-empty and equals no
+     * option's label or value; choosing it calls this instead of
+     * `onValueChange`.
+     *
+     * The query arrives trimmed and otherwise raw. Normalization — casing,
+     * separators, a leading `#` — is the consumer's, because it is a product
+     * rule about what the created thing is called, not something this control
+     * can know.
+     */
+    onCreate?: (query: string) => void;
+    /** Label for the create entry. Defaults to `Create "<query>"`. */
+    createLabel?: (query: string) => React.ReactNode;
+    /**
+     * Decide whether an existing option already covers the typed query, which is
+     * what suppresses the create entry. Defaults to case-insensitive equality
+     * against an option's `label` or `value`.
+     *
+     * The default is case-*insensitive* rather than exact because the offer is
+     * only useful if it agrees with what `onCreate` will do, and casing is the
+     * cheapest way for the two to disagree: with `urgent` in the list, typing
+     * `Urgent` under an exact comparison offers "Create Urgent", the consumer
+     * lowercases it on create, and the user has taken an action that either did
+     * nothing or made a duplicate.
+     *
+     * Casing is only the common half. A consumer whose normalization does more —
+     * hyphenating spaces, stripping a leading `#` — owns the rest, and this is
+     * where it says so, because the component cannot guess the rule it was
+     * deliberately not given in {@link ComboboxProps.onCreate}.
+     */
+    isDuplicate?: (query: string, option: ComboboxOption) => boolean;
+    /**
+     * Leave the popup open after a choice is committed, clearing the query for
+     * the next one instead of closing.
+     *
+     * For the caller whose control adds to a set rather than setting a value — a
+     * tag picker, an attendee list — where closing after each pick makes adding
+     * three things cost three round trips through opening the control. Such a
+     * caller typically pairs this with `value=""`, since a control that holds no
+     * selection has nothing to display once the choice has been applied
+     * elsewhere.
+     *
+     * Off by default: for an ordinary single-select, staying open after the one
+     * choice has been made is the wrong behaviour, and closing is what says the
+     * choice registered.
+     */
+    keepOpenOnSelect?: boolean;
     id?: string;
     name?: string;
     "aria-label"?: string;
@@ -50,5 +81,10 @@ export interface ComboboxProps {
  * highlight with wrap-around and scroll-into-view, Enter commits the active
  * option, Escape closes, and losing focus closes without committing a
  * partial value. Selection submits via a hidden input when `name` is set.
+ *
+ * For the list where search *is* the interaction — too long to read, or one
+ * the consumer offers to add to. A short list that only wants a themed popup is
+ * `SelectMenu`'s case; the four single-choice controls and which case each
+ * answers are tabled once, in `docs/packages/saas-ui.md`.
  */
 export declare const Combobox: React.ForwardRefExoticComponent<ComboboxProps & React.RefAttributes<HTMLInputElement>>;

package/dist/components/combobox.js

@@ -1,15 +1,22 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { ChevronDown } from "lucide-react";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronDown, Plus } from "lucide-react";
 import * as React from "react";
 import { cn } from "../utils/cn.js";
 import { useFormFieldProps } from "./form-field.js";
-function defaultFilter(option, query) {
-    const normalized = query.trim().toLowerCase().replaceAll(" ", "_");
-    if (!normalized)
-        return true;
-    return (option.value.toLowerCase().includes(normalized) ||
-        option.label.toLowerCase().replaceAll(" ", "_").includes(normalized));
+import { OptionListbox, OptionRow, defaultOptionFilter, nextActiveIndex, optionElementId, scrollOptionIntoView, } from "./option-list.js";
+/**
+ * The create entry's stand-in `value`. It exists only so the entry can travel
+ * through the same `ComboboxOption` shape as every real option — sharing the
+ * index space, the `data-index` lookup, and the `aria-activedescendant` id —
+ * rather than needing a parallel keyboard path beside the list. `commit`
+ * routes on it and it never reaches `onValueChange`.
+ */
+const CREATE_ENTRY_VALUE = "__ssui_combobox_create__";
+function defaultIsDuplicate(query, option) {
+    const normalized = query.toLowerCase();
+    return (option.value.toLowerCase() === normalized ||
+        option.label.toLowerCase() === normalized);
 }
 /**
  * Filterable single-select following the WAI-ARIA combobox pattern: a text
@@ -17,25 +24,91 @@ function defaultFilter(option, query) {
  * highlight with wrap-around and scroll-into-view, Enter commits the active
  * option, Escape closes, and losing focus closes without committing a
  * partial value. Selection submits via a hidden input when `name` is set.
+ *
+ * For the list where search *is* the interaction — too long to read, or one
+ * the consumer offers to add to. A short list that only wants a themed popup is
+ * `SelectMenu`'s case; the four single-choice controls and which case each
+ * answers are tabled once, in `docs/packages/saas-ui.md`.
  */
-export const Combobox = React.forwardRef(({ options, value, onValueChange, filter = defaultFilter, placeholder, disabled, emptyMessage = "No matches", className, name, ...ariaProps }, ref) => {
+export const Combobox = React.forwardRef(({ options, value, onValueChange, filter = defaultOptionFilter, placeholder, disabled, emptyMessage = "No matches", onCreate, createLabel, isDuplicate = defaultIsDuplicate, keepOpenOnSelect = false, className, name, ...ariaProps }, ref) => {
     const fieldProps = useFormFieldProps(ariaProps);
     const generatedId = React.useId();
     const id = fieldProps.id ?? generatedId;
     const listboxId = `${id}-listbox`;
+    const currentValueId = `${id}-current-value`;
     const [open, setOpen] = React.useState(false);
     const [query, setQuery] = React.useState(null);
     const [activeIndex, setActiveIndex] = React.useState(-1);
     const listRef = React.useRef(null);
     const selectedOption = options.find((option) => option.value === value);
-    const filtered = query === null
-        ? options
-        : options.filter((option) => filter(option, query));
-    const inputValue = query ?? selectedOption?.label ?? "";
-    const activeOption = activeIndex >= 0 ? filtered[activeIndex] : undefined;
+    // The predicate runs even with nothing typed, against an empty query. It used to be
+    // skipped entirely in that state, on the reasoning that "no query" means "show
+    // everything" — true of a predicate that only *searches*, and false of one that also
+    // *excludes*. A consumer hiding options it must not offer (an already-applied tag, a
+    // record already named) had its rule silently ignored for exactly as long as the field
+    // was empty, which is the state the popup opens in. `defaultFilter` returns true for
+    // an empty query, so nothing changes for a consumer that only searches.
+    const filtered = options.filter((option) => filter(option, query ?? ""));
+    // What the field shows: the live query while searching, the committed option's
+    // own text otherwise. `inputLabel` lets an option carry a fuller form for the
+    // collapsed field than the listbox row needs.
+    const committedLabel = selectedOption?.inputLabel ?? selectedOption?.label ?? "";
+    const inputValue = query ?? committedLabel;
+    // The committed value moves into the placeholder while searching, which is a
+    // presentation trick with two costs to pay off.
+    //
+    // Colour: a placeholder is styled `--ssui-text-subtle`, which is the pairing
+    // this release retired from `ChoiceCard`'s description for measuring 2.87:1.
+    // That is the right weight for a hint the user is meant to type over and the
+    // wrong one for the answer to "what is this set to right now?", so the value
+    // takes `--ssui-text-muted` and only a true placeholder stays subtle.
+    //
+    // Announcement: screen-reader handling of placeholder text is inconsistent
+    // and never guaranteed, so with the box cleared on focus a non-sighted user
+    // could lose the current value entirely. `aria-describedby` gives it a
+    // programmatic home that does not depend on how the placeholder is treated.
+    const showingValueAsPlaceholder = open && committedLabel !== "";
+    const describedBy = [fieldProps["aria-describedby"], showingValueAsPlaceholder ? currentValueId : null]
+        .filter(Boolean)
+        .join(" ") || undefined;
+    // Offered only when there is something to create that is not already there:
+    // a "Create X" row sitting above an existing X is an offer to do nothing.
+    // The comparison is against the whole option list rather than the filtered
+    // one, because a match hidden by a consumer's own `filter` is still an
+    // existing option. `isDuplicate` decides what counts as a match, and its
+    // default is case-insensitive — see the prop's own note for why exact
+    // equality is the wrong default here.
+    const trimmedQuery = (query ?? "").trim();
+    const createEntry = onCreate !== undefined &&
+        trimmedQuery.length > 0 &&
+        !options.some((option) => isDuplicate(trimmedQuery, option))
+        ? { value: CREATE_ENTRY_VALUE, label: trimmedQuery }
+        : null;
+    // The one list the keyboard model runs on. Appending the create entry here
+    // rather than rendering it as a footer is the whole of its integration:
+    // wrap-around, `activeIndex`, scroll-into-view and `aria-activedescendant`
+    // all keep working with no branch for it.
+    const navigable = createEntry ? [...filtered, createEntry] : filtered;
+    const activeOption = activeIndex >= 0 ? navigable[activeIndex] : undefined;
     function openList() {
         setOpen(true);
         setActiveIndex(-1);
+        // Focusing starts a search, and a search starts empty.
+        //
+        // Leaving the committed label in the box made the field read as editable
+        // text holding the setting: a caret landed in the middle of
+        // "America/New_York", typing appended to it, and the result matched
+        // nothing. The user had to notice their own value was in the way and clear
+        // it before the control would do the one thing it exists to do. It also
+        // invited the reasonable belief that the text was the value and could be
+        // corrected in place, which it never was — an uncommitted query is
+        // discarded on close.
+        //
+        // Empty on focus keeps the two modes distinct: unfocused the field displays
+        // a value, focused it takes a query. The value is not lost while searching —
+        // it becomes the placeholder below — and it cannot be edited into something
+        // that was never a choice.
+        setQuery("");
     }
     function close() {
         setOpen(false);
@@ -43,38 +116,28 @@ export const Combobox = React.forwardRef(({ options, value, onValueChange, filte
         setActiveIndex(-1);
     }
     function commit(option) {
-        onValueChange?.(option.value);
+        if (option.value === CREATE_ENTRY_VALUE) {
+            onCreate?.(option.label);
+        }
+        else {
+            onValueChange?.(option.value);
+        }
+        if (keepOpenOnSelect) {
+            // Back to the state a freshly opened popup is in — empty query, nothing
+            // active — rather than closed. `setQuery("")` and not `setQuery(null)`:
+            // null means "show the committed value", and this control is mid-search.
+            setQuery("");
+            setActiveIndex(-1);
+            return;
+        }
         close();
     }
     function moveActive(delta) {
-        if (filtered.length === 0)
+        if (navigable.length === 0)
             return;
-        const next = activeIndex < 0
-            ? delta === 1
-                ? 0
-                : filtered.length - 1
-            : (activeIndex + delta + filtered.length) % filtered.length;
+        const next = nextActiveIndex(activeIndex, delta, navigable.length);
         setActiveIndex(next);
-        const element = listRef.current?.querySelector(`[data-index="${next}"]`);
-        // Arriving at the first option of a group brings that group's heading into
-        // view as well as the option, so a keyboard user entering a group can see
-        // which one they are in. Both, and in this order — scrolling only the
-        // option leaves the 16px heading clipped above the scrollport, and
-        // scrolling only the heading is worse, because entering a group from below
-        // aligns the heading's bottom edge with the scrollport's and leaves the
-        // newly highlighted option out of view entirely.
-        //
-        // Two `nearest` calls settle both directions. Downward: the first brings
-        // the heading to the bottom edge, the second scrolls one option further,
-        // leaving heading and option both visible. Upward: the first aligns the
-        // heading to the top and the second is a no-op, the option having come
-        // with it. Never losing the highlight is the constraint; showing the
-        // heading is the preference.
-        const previous = element?.previousElementSibling ?? null;
-        if (previous?.getAttribute("role") === "presentation") {
-            previous.scrollIntoView({ block: "nearest" });
-        }
-        element?.scrollIntoView({ block: "nearest" });
+        scrollOptionIntoView(listRef.current, next);
     }
     function handleKeyDown(event) {
         if (event.key === "ArrowDown" || event.key === "ArrowUp") {
@@ -108,45 +171,34 @@ export const Combobox = React.forwardRef(({ options, value, onValueChange, filte
             }
         }
     }
-    const rows = [];
-    filtered.forEach((option, index) => {
-        const last = rows[rows.length - 1];
-        if (option.group === undefined) {
-            rows.push({ kind: "option", entry: { option, index } });
-            return;
-        }
-        if (last?.kind === "group" && last.group === option.group) {
-            last.entries.push({ option, index });
-            return;
-        }
-        rows.push({ kind: "group", group: option.group, entries: [{ option, index }] });
-    });
-    function renderOption({ option, index }) {
-        return (_jsxs("button", { "aria-selected": option.value === value, className: cn("flex w-full items-center justify-between gap-3 rounded-[var(--ssui-radius-sm)] px-2 py-1.5 text-left text-sm transition-colors", index === activeIndex && "bg-[color:var(--ssui-overlay-hover)]", option.value === value
-                ? "bg-[color:var(--ssui-surface-muted)] text-[color:var(--ssui-text)]"
-                : "text-[color:var(--ssui-text-muted)] hover:bg-[color:var(--ssui-overlay-hover)]"), "data-index": index, id: `${id}-option-${option.value}`, onClick: () => commit(option), onMouseDown: (event) => event.preventDefault(), onMouseMove: () => setActiveIndex(index), role: "option", tabIndex: -1, type: "button", children: [option.description !== undefined ? (_jsxs("span", { className: "flex min-w-0 items-baseline gap-1.5", children: [_jsx("span", { className: "truncate", children: option.label }), _jsx("span", { className: "truncate text-xs text-[color:var(--ssui-text-subtle)]", children: option.description })] })) : (_jsx("span", { className: "truncate", children: option.label })), option.trailing !== undefined ? (_jsx("span", { className: "shrink-0 font-mono text-xs text-[color:var(--ssui-text-subtle)]", children: option.trailing })) : null] }, option.value));
+    // The create entry is a row of its own kind — an action, not a value — but
+    // it is rendered through the same row primitive so wrap-around,
+    // `activeIndex`, scroll-into-view and `aria-activedescendant` all keep
+    // working with no branch for it.
+    function renderCreateEntry(option, index) {
+        return (_jsx(OptionRow, { active: index === activeIndex, idPrefix: id, index: index, onActivate: setActiveIndex, onCommit: commit, option: option, selected: false, children: _jsxs("span", { className: "flex min-w-0 items-center gap-3", children: [_jsx(Plus, { "aria-hidden": "true", className: "size-3.5 shrink-0" }), _jsx("span", { className: "min-w-0 truncate", children: createLabel ? (createLabel(option.label)) : (_jsxs(_Fragment, { children: ["Create", " ", _jsx("span", { className: "font-medium text-[color:var(--ssui-text)]", children: option.label })] })) })] }) }, option.value));
     }
     return (_jsxs("div", { className: cn("relative", className), onBlur: (event) => {
             if (!event.currentTarget.contains(event.relatedTarget)) {
                 close();
             }
-        }, children: [_jsx("input", { ...fieldProps, ref: ref, id: id, role: "combobox", type: "text", "aria-autocomplete": "list", "aria-controls": listboxId, "aria-expanded": open, "aria-haspopup": "listbox", "aria-activedescendant": open && activeOption ? `${id}-option-${activeOption.value}` : undefined, autoComplete: "off", className: "flex h-10 w-full rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border)] bg-[color:var(--ssui-surface)] py-2 pl-3 pr-9 text-sm text-[color:var(--ssui-text)] shadow-sm transition-colors placeholder:text-[color:var(--ssui-text-subtle)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ssui-focus-ring)] focus-visible:ring-offset-2 focus-visible:ring-offset-[color:var(--ssui-bg)] disabled:cursor-not-allowed disabled:bg-[color:var(--ssui-surface-muted)] disabled:opacity-70", disabled: disabled, onChange: (event) => {
+        }, children: [_jsx("input", { ...fieldProps, ref: ref, id: id, role: "combobox", type: "text", "aria-autocomplete": "list", "aria-controls": listboxId, "aria-expanded": open, "aria-haspopup": "listbox", "aria-activedescendant": open && activeOption ? optionElementId(id, activeOption.value) : undefined, "aria-describedby": describedBy, autoComplete: "off", className: cn("flex h-10 w-full rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border-control,var(--ssui-border))] bg-[color:var(--ssui-surface)] py-2 pl-3 pr-9 text-sm text-[color:var(--ssui-text)] shadow-sm transition-colors placeholder:text-[color:var(--ssui-text-subtle)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ssui-focus-ring)] focus-visible:ring-offset-2 focus-visible:ring-offset-[color:var(--ssui-bg)] disabled:cursor-not-allowed disabled:bg-[color:var(--ssui-surface-muted)] disabled:opacity-70", 
+                // Content, not a hint. `cn` is tailwind-merge, so this replaces the
+                // subtle placeholder colour above rather than racing it.
+                showingValueAsPlaceholder &&
+                    "placeholder:text-[color:var(--ssui-text-muted)]"), disabled: disabled, onChange: (event) => {
                     setQuery(event.target.value);
                     setOpen(true);
                     setActiveIndex(-1);
-                }, onFocus: openList, onKeyDown: handleKeyDown, placeholder: placeholder, value: inputValue }), _jsx("button", { "aria-label": "Show options", className: "absolute right-1 top-1 grid size-8 place-items-center rounded-[var(--ssui-radius-sm)] text-[color:var(--ssui-text-subtle)] transition-colors hover:bg-[color:var(--ssui-overlay-hover)] hover:text-[color:var(--ssui-text)] disabled:pointer-events-none disabled:opacity-50", disabled: disabled, onClick: () => {
-                    setQuery(null);
+                }, onFocus: openList, onKeyDown: handleKeyDown, 
+                // While searching, the committed value takes the placeholder's place, so
+                // emptying the box to type never hides what is currently set.
+                placeholder: open && committedLabel ? committedLabel : placeholder, value: inputValue }), _jsx("button", { "aria-label": "Show options", className: "absolute right-1 top-1 grid size-8 place-items-center rounded-[var(--ssui-radius-sm)] text-[color:var(--ssui-text-subtle)] transition-colors hover:bg-[color:var(--ssui-overlay-hover)] hover:text-[color:var(--ssui-text)] disabled:pointer-events-none disabled:opacity-50", disabled: disabled, onClick: () => {
                     openList();
                     document.getElementById(id)?.focus();
-                }, tabIndex: -1, type: "button", children: _jsx(ChevronDown, { "aria-hidden": "true", className: "size-4" }) }), name ? _jsx("input", { name: name, type: "hidden", value: value ?? "" }) : null, open ? (_jsx("div", { className: "absolute z-50 mt-1 max-h-64 w-full overflow-y-auto rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border)] bg-[color:var(--ssui-surface-elevated)] p-1 shadow-[var(--ssui-shadow-md)]", id: listboxId, ref: listRef, role: "listbox", children: rows.length > 0 ? (rows.map((row, rowIndex) => row.kind === "option" ? (renderOption(row.entry)) : (
-                // A run is wrapped in `role="group"` labelled by its heading —
-                // the APG grouped-listbox shape. Without it the grouping is
-                // conveyed to sighted users only: a roleless heading is not in
-                // the listbox's content model, so a screen-reader user hears a
-                // flat list of options and never learns which kind each is.
-                // The heading takes `role="presentation"` so it stays out of
-                // that content model while `aria-labelledby` still names the
-                // group from its text.
-                _jsxs("div", { "aria-labelledby": `${id}-group-${rowIndex}`, role: "group", children: [_jsx("div", { className: cn("px-2 pb-0.5 pt-4 text-xs font-medium uppercase tracking-wide text-[color:var(--ssui-text-subtle)]", rowIndex === 0 && "pt-1"), id: `${id}-group-${rowIndex}`, role: "presentation", children: row.group }), row.entries.map(renderOption)] }, `group-${rowIndex}`)))) : (_jsx("div", { className: "px-2 py-1.5 text-sm text-[color:var(--ssui-text-subtle)]", children: emptyMessage })) })) : null] }));
+                }, tabIndex: -1, type: "button", children: _jsx(ChevronDown, { "aria-hidden": "true", className: "size-4" }) }), showingValueAsPlaceholder ? (_jsx("span", { className: "sr-only", id: currentValueId, children: `Current selection: ${committedLabel}` })) : null, name ? _jsx("input", { name: name, type: "hidden", value: value ?? "" }) : null, open ? (_jsx(OptionListbox, { activeIndex: activeIndex, className: "absolute z-50 mt-1 max-h-64 w-full overflow-y-auto rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border)] bg-[color:var(--ssui-surface-elevated)] p-1 shadow-[var(--ssui-shadow-md)]", 
+                // The create entry is an action the reader can take, so saying there
+                // is nothing to do would contradict the row underneath it.
+                emptyMessage: createEntry ? null : emptyMessage, id: listboxId, idPrefix: id, onActivate: setActiveIndex, onCommit: commit, options: filtered, ref: listRef, value: value, children: createEntry ? renderCreateEntry(createEntry, filtered.length) : null })) : null] }));
 });
 Combobox.displayName = "Combobox";

package/dist/components/index.d.ts

@@ -24,11 +24,13 @@ export * from "./list-shell.js";
 export * from "./login.js";
 export * from "./overflow-menu.js";
 export * from "./page-header.js";
+export * from "./popover.js";
 export * from "./rail-toggle.js";
 export * from "./request-access.js";
 export * from "./role-menu.js";
 export * from "./scroll-area.js";
 export * from "./search-input.js";
+export * from "./select-menu.js";
 export * from "./select.js";
 export * from "./separator.js";
 export * from "./settings-layout.js";

package/dist/components/index.js

@@ -24,11 +24,13 @@ export * from "./list-shell.js";
 export * from "./login.js";
 export * from "./overflow-menu.js";
 export * from "./page-header.js";
+export * from "./popover.js";
 export * from "./rail-toggle.js";
 export * from "./request-access.js";
 export * from "./role-menu.js";
 export * from "./scroll-area.js";
 export * from "./search-input.js";
+export * from "./select-menu.js";
 export * from "./select.js";
 export * from "./separator.js";
 export * from "./settings-layout.js";

package/dist/components/input.js

@@ -2,5 +2,5 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import * as React from "react";
 import { cn } from "../utils/cn.js";
 import { useFormFieldProps } from "./form-field.js";
-export const Input = React.forwardRef(({ className, type = "text", ...props }, ref) => (_jsx("input", { ref: ref, type: type, className: cn("flex h-10 w-full rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border)] bg-[color:var(--ssui-surface)] px-3 py-2 text-sm text-[color:var(--ssui-text)] shadow-sm transition-colors placeholder:text-[color:var(--ssui-text-subtle)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ssui-focus-ring)] focus-visible:ring-offset-2 focus-visible:ring-offset-[color:var(--ssui-bg)] disabled:cursor-not-allowed disabled:bg-[color:var(--ssui-surface-muted)] disabled:opacity-70", className), ...useFormFieldProps(props) })));
+export const Input = React.forwardRef(({ className, type = "text", ...props }, ref) => (_jsx("input", { ref: ref, type: type, className: cn("flex h-10 w-full rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border-control,var(--ssui-border))] bg-[color:var(--ssui-surface)] px-3 py-2 text-sm text-[color:var(--ssui-text)] shadow-sm transition-colors placeholder:text-[color:var(--ssui-text-subtle)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ssui-focus-ring)] focus-visible:ring-offset-2 focus-visible:ring-offset-[color:var(--ssui-bg)] disabled:cursor-not-allowed disabled:bg-[color:var(--ssui-surface-muted)] disabled:opacity-70", className), ...useFormFieldProps(props) })));
 Input.displayName = "Input";

package/dist/components/option-list.d.ts

@@ -0,0 +1,140 @@
+import * as React from "react";
+/**
+ * One option, in the shape both `Combobox` and `SelectMenu` take. Two controls
+ * presenting the same list should not need two option types, so the shape lives
+ * here and each component re-exports it under the name its consumers know.
+ */
+export interface ComboboxOption {
+    value: string;
+    label: string;
+    /** Optional trailing content (e.g. a GMT offset) shown right-aligned. */
+    trailing?: React.ReactNode;
+    /**
+     * Optional secondary text shown next to the label, in the reading order a
+     * subtitle would take. Distinct from `trailing`, which is right-aligned and
+     * monospaced; an option may carry both.
+     */
+    description?: React.ReactNode;
+    /**
+     * Text the closed control shows once this option is committed, when that
+     * should differ from `label`. Defaults to `label`.
+     *
+     * For an option whose `trailing` content is part of its identity rather than
+     * decoration — a time zone's GMT offset, a currency's symbol — the collapsed
+     * control would otherwise drop it: `trailing` is a `ReactNode` rendered into
+     * the listbox row, and an input can only display a string. This is that
+     * string. `SelectMenu`'s trigger shows it too, for the same reason; the name
+     * predates that component and stays because renaming it would break shipped
+     * consumers to fix a word.
+     */
+    inputLabel?: string;
+    /**
+     * Optional heading this option sits under. Consecutive options declaring the
+     * same group collapse into one heading, exactly as `<optgroup>` does — the
+     * component never reorders, so interleaved groups (`A, B, A`) render three
+     * headings, not two. Sort the list before passing it if that is not wanted.
+     *
+     * Grouped and ungrouped options may be mixed: an option declaring no group
+     * ends the run above it and renders outside every group, the way an
+     * `<option>` following an `</optgroup>` sits outside that group.
+     */
+    group?: string;
+}
+/**
+ * Case-insensitive substring match on the option's value, label and
+ * `inputLabel`, with spaces treated as underscores so `new york` finds
+ * `America/New_York`. Returns true for an empty query.
+ */
+export declare function defaultOptionFilter(option: ComboboxOption, query: string): boolean;
+/**
+ * The DOM id of an option row, which `aria-activedescendant` points at.
+ *
+ * The value is a consumer's data — a user-defined field's option is whatever a
+ * person typed — and an id may not contain whitespace, while the single-IDREF
+ * attribute pointing at it has to resolve in every browser and screen reader.
+ * So the value is encoded into `[A-Za-z0-9-]`: every other character, `_`
+ * included so the encoding stays one-to-one, becomes `_<code point in hex>_`.
+ * Distinct values give distinct ids; a value that already fits passes through
+ * unchanged.
+ */
+export declare function optionElementId(prefix: string, value: string): string;
+/**
+ * The next highlight position after one arrow press: from nothing highlighted,
+ * down lands on the first entry and up on the last; otherwise the highlight
+ * wraps at both ends. `-1` when there is nothing to highlight.
+ */
+export declare function nextActiveIndex(current: number, delta: 1 | -1, length: number): number;
+/**
+ * Bring the highlighted row into view, and its group heading with it.
+ *
+ * Arriving at the first option of a group brings that group's heading into
+ * view as well as the option, so a keyboard user entering a group can see which
+ * one they are in. Both, and in this order — scrolling only the option leaves
+ * the 16px heading clipped above the scrollport, and scrolling only the heading
+ * is worse, because entering a group from below aligns the heading's bottom
+ * edge with the scrollport's and leaves the newly highlighted option out of
+ * view entirely.
+ *
+ * Two `nearest` calls settle both directions. Downward: the first brings the
+ * heading to the bottom edge, the second scrolls one option further, leaving
+ * heading and option both visible. Upward: the first aligns the heading to the
+ * top and the second is a no-op, the option having come with it. Never losing
+ * the highlight is the constraint; showing the heading is the preference.
+ */
+export declare function scrollOptionIntoView(list: HTMLElement | null, index: number): void;
+export interface OptionRowProps {
+    option: ComboboxOption;
+    /** Position in the navigable list; what `data-index` and the highlight key on. */
+    index: number;
+    /** Highlighted by keyboard or pointer. */
+    active: boolean;
+    /** The committed value, marked to assistive technology as well as visually. */
+    selected: boolean;
+    /** Prefix for the row's DOM id — the owning control's id. */
+    idPrefix: string;
+    onCommit: (option: ComboboxOption) => void;
+    onActivate: (index: number) => void;
+    /**
+     * Replaces the row's label and description, for a row that is an action
+     * rather than an option — `Combobox`'s create entry. The option's `trailing`
+     * content and the selected mark are the row's own and still render after it,
+     * so a custom row carrying either is marked like any other. Pass a row that
+     * needs neither, or leave those fields unset on its option.
+     */
+    children?: React.ReactNode;
+}
+/** One `role="option"` row. Pointer moves highlight it; clicks commit it. */
+export declare function OptionRow({ option, index, active, selected, idPrefix, onCommit, onActivate, children, }: OptionRowProps): import("react/jsx-runtime").JSX.Element;
+export interface OptionListboxProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "id" | "role"> {
+    /** The listbox's own DOM id, which the controlling element's `aria-controls` names. */
+    id: string;
+    /** Prefix for option and heading ids — the owning control's id. */
+    idPrefix: string;
+    /** The options to present, already filtered. Rendered in the order given. */
+    options: ComboboxOption[];
+    /** The committed value. */
+    value?: string;
+    /** Index into `options` of the highlighted row, or `-1`. */
+    activeIndex: number;
+    onActivate: (index: number) => void;
+    onCommit: (option: ComboboxOption) => void;
+    /**
+     * Shown when `options` is empty. Pass `null` to show nothing — for a caller
+     * that is rendering an action row of its own into `children` and so has not
+     * left the reader with nothing to do.
+     */
+    emptyMessage?: React.ReactNode;
+    /** Rows rendered after the options, inside the listbox — `Combobox`'s create entry. */
+    children?: React.ReactNode;
+}
+/**
+ * The popup list both `Combobox` and `SelectMenu` render: options walked into
+ * grouped runs under headings, each row a `role="option"` button, the highlight
+ * driven from outside by `activeIndex`. It owns no positioning and no keyboard
+ * handling — the owner decides which element holds focus and where the list
+ * sits — so the surrounding chrome is the owner's `className`.
+ *
+ * Internal to the package. Not exported from the barrel, so it is not an API
+ * this package has to keep.
+ */
+export declare const OptionListbox: React.ForwardRefExoticComponent<OptionListboxProps & React.RefAttributes<HTMLDivElement>>;