@forwardreach/saas-ui 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## 0.12.0
+
+### Minor Changes
+
+- **`SelectMenu`: a single choice whose popup this package draws.** A native
+  `<select>` styled down to a line of text has exactly one piece of chrome left —
+  the platform's own popup — and it is the one piece CSS cannot reach. This is
+  the component for that case. It is additive in API — no existing export
+  changes shape — and the one existing call site that renders differently is
+  named below.
+
+  - **Two trigger presentations.** `variant="control"` (the default) is `Select`'s
+    bounded field with a chevron, in the same `sm`/`md` scale, so swapping one for
+    the other returns the same field with a themed popup. `variant="inline"` draws
+    no box at rest: the trigger is the label's own text at the size of the line it
+    sits in, with the hover surface, the chevron, and a focus ring without an
+    offset arriving on hover, focus, and while open. The inline variant is why the
+    component exists, and shipping it is what keeps a consumer from forcing a 40px
+    bordered control down to a 20px line through `className` and child selectors.
+  - **The same options `Combobox` takes**, groups included: consecutive options
+    declaring one group collapse under one heading, an ungrouped option ends the
+    run above it, and the component never reorders. The option list, its keyboard
+    model, and its group semantics are `Combobox`'s own, extracted into an
+    internal module both components render — `Combobox`'s suite passes unedited
+    across the extraction.
+  - **A filter once the list is long enough**, at `SELECT_MENU_SEARCH_THRESHOLD`
+    options (eight) and not before; `searchable` forces it either way. With a
+    filter, focus stays in the field while the list is navigated; without one, the
+    listbox itself holds focus. Both run the listbox pattern through
+    `aria-activedescendant`.
+  - **`emptyLabel`** offers clearing the value as a row that reports `""`.
+    **`placeholder`** is what the trigger shows when no option matches `value` — a
+    field holding nothing, or one holding a value the list no longer offers, which
+    is neither shown as chosen nor replaced by whatever happens to be first.
+  - **`defaultOpen`, `open`, `onOpenChange`**, for the consumer whose control
+    appears in response to an edit gesture: open the popup as the row enters edit
+    mode, so choosing costs one click rather than two, and read a close that
+    followed no `onValueChange` as a cancel.
+  - **Form participation and `FormField` wiring** exactly as `RoleMenu` does
+    them: a hidden input when `name` is set, nothing submitted while disabled, the
+    enclosing field's label naming the trigger, and `aria-label` composing purpose
+    with the current value.
+
+  **The option list is drawn to be read as the choice**, which is the one
+  visible change to an existing component: `Combobox` renders the same list, so
+  its popup picks all three corrections up. Options take the full text colour
+  rather than the muted one, which came from a popup that hangs under a field
+  holding the answer; where the popup *is* the choice, options dimmer than the
+  heading over them read as less available than the label for them. The current
+  option carries a check and a medium weight rather than a fill alone, because
+  that fill is `--ssui-surface-muted` on `--ssui-surface-elevated` — a clear step
+  in a light theme and almost none in a dark one. And the keyboard highlight now
+  wins the background over the selected fill, so it stays visible on the selected
+  row, which for `SelectMenu` is the row a popup opens on.
+
+  **A bounded popup starts at the field's own width** and grows only if an option
+  needs more, so the two read as one control. It used to carry a fixed minimum for
+  both variants, which made the popup of any field narrower than that minimum
+  overhang it. An inline trigger is as wide as its text, which is no width for a
+  list, so it keeps a floor of its own.
+
+  **`Popover`** — `Popover`, `PopoverTrigger`, `PopoverContent`, `PopoverAnchor`,
+  `PopoverClose`, `PopoverPortal` — is exported alongside it: the thin styled
+  wrapper `DropdownMenu` already has, on `@radix-ui/react-popover`, a new direct
+  dependency sharing its internals with the dialog and dropdown-menu packages
+  already here. `SelectMenu` is built on it rather than on `DropdownMenu` because a
+  menu's roving focus and typeahead both fight a filter field.
+
+  **What this does not do, on purpose.** It does not replace `Select`. On a phone
+  a native `<select>` opens the platform's own picker — thumb-sized, familiar,
+  outside the page — and `SelectMenu` cannot and will not. For a bounded field in
+  an ordinary form that is worth more than a themed popup, and `Select` stays the
+  default there. `docs/packages/saas-ui.md` now tables all four single-choice
+  controls — `Select`, `SelectMenu`, `Combobox`, `RoleMenu` — and which case each
+  answers, and the three older components' doc comments point at that table
+  rather than carrying partial copies of it. No multi-select: a chip-holding
+  trigger and checkable rows roughly double the API and the test matrix, and are
+  a change of their own.
+
 ## 0.11.0
 
 ### Minor Changes
@@ -64,7 +143,7 @@
   - **`ChoiceCard` no longer misreports what was saved.** React resets a
     `<form action={fn}>` once the action resolves, and a reset restores every
     control to its content attribute. A controlled radio only ever had its
-    `checked` *property* written, so after a successful save the group snapped
+    `checked` _property_ written, so after a successful save the group snapped
     back to whatever was selected on first render, while the surrounding state,
     the hidden inputs, and the stored value all held the new selection. The write
     succeeded and only the control disagreed, which reads to a user as "my change
@@ -85,7 +164,7 @@
 
   - **A consumer's `filter` now runs with an empty query** rather than being
     skipped while nothing is typed. A predicate that only searches is
-    unaffected; one that *excludes* had its rule ignored for exactly as long as
+    unaffected; one that _excludes_ had its rule ignored for exactly as long as
     the field was empty, which is the state the popup opens in.
 
   Two more came out of the same consumer looking at the running app a second
@@ -116,7 +195,7 @@
 
   - **The list variant no longer clips its own focus ring.** The container
     carried `overflow-hidden` to keep the first and last row's fills inside its
-    radius. A Tailwind ring is a box-shadow drawn *outside* the element, and a
+    radius. A Tailwind ring is a box-shadow drawn _outside_ the element, and a
     list row has no border or radius of its own, so it fills the container's
     padding box exactly — the clip amputated both vertical sides of every row's
     focus indicator plus the outer edges of the first and last. A keyboard user
@@ -163,7 +242,7 @@
 
   This was established the expensive way: a third attempt generated and signed a
   sigstore bundle and the registry rejected it with `422 ... Unsupported GitHub
-  Actions source repository visibility: "private"`. That attempt published
+Actions source repository visibility: "private"`. That attempt published
   nothing, so `0.10.4` is the current release.
 
 ## 0.10.3

package/dist/components/combobox.d.ts

@@ -1,37 +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;
-    /**
-     * Text the field 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
-     * field 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.
-     */
-    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;
-}
+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[];
@@ -112,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,9 +1,10 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+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";
+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
@@ -12,19 +13,6 @@ import { useFormFieldProps } from "./form-field.js";
  * routes on it and it never reaches `onValueChange`.
  */
 const CREATE_ENTRY_VALUE = "__ssui_combobox_create__";
-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) ||
-        // `inputLabel` is what the collapsed field showed, so it is what a user
-        // retypes after focusing clears the box. Searching only `label` would leave
-        // an option findable by a string it never displayed and unfindable by the
-        // one it did.
-        (option.inputLabel !== undefined &&
-            option.inputLabel.toLowerCase().replaceAll(" ", "_").includes(normalized)));
-}
 function defaultIsDuplicate(query, option) {
     const normalized = query.toLowerCase();
     return (option.value.toLowerCase() === normalized ||
@@ -36,8 +24,13 @@ function defaultIsDuplicate(query, option) {
  * 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", onCreate, createLabel, isDuplicate = defaultIsDuplicate, keepOpenOnSelect = false, 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;
@@ -142,32 +135,9 @@ export const Combobox = React.forwardRef(({ options, value, onValueChange, filte
     function moveActive(delta) {
         if (navigable.length === 0)
             return;
-        const next = activeIndex < 0
-            ? delta === 1
-                ? 0
-                : navigable.length - 1
-            : (activeIndex + delta + navigable.length) % navigable.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") {
@@ -201,32 +171,18 @@ 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 (_jsxs("button", { "aria-selected": false, className: cn("flex w-full items-center gap-3 rounded-[var(--ssui-radius-sm)] px-2 py-1.5 text-left text-sm text-[color:var(--ssui-text-muted)] transition-colors hover:bg-[color:var(--ssui-overlay-hover)]", index === activeIndex && "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: [_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 (_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, "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", 
+        }, 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 &&
@@ -240,15 +196,9 @@ export const Combobox = React.forwardRef(({ options, value, onValueChange, filte
                 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" }) }), showingValueAsPlaceholder ? (_jsx("span", { className: "sr-only", id: currentValueId, children: `Current selection: ${committedLabel}` })) : null, name ? _jsx("input", { name: name, type: "hidden", value: value ?? "" }) : null, open ? (_jsxs("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.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}`))), createEntry ? renderCreateEntry(createEntry, filtered.length) : null, rows.length === 0 && !createEntry ? (_jsx("div", { className: "px-2 py-1.5 text-sm text-[color:var(--ssui-text-subtle)]", children: emptyMessage })) : null] })) : 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/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>>;

package/dist/components/option-list.js

@@ -0,0 +1,142 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Check } from "lucide-react";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+/**
+ * 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 function defaultOptionFilter(option, query) {
+    const normalized = query.trim().toLowerCase().replaceAll(" ", "_");
+    if (!normalized)
+        return true;
+    return (option.value.toLowerCase().includes(normalized) ||
+        option.label.toLowerCase().replaceAll(" ", "_").includes(normalized) ||
+        // `inputLabel` is what the collapsed control showed, so it is what a user
+        // retypes after focusing clears the box. Searching only `label` would leave
+        // an option findable by a string it never displayed and unfindable by the
+        // one it did.
+        (option.inputLabel !== undefined &&
+            option.inputLabel.toLowerCase().replaceAll(" ", "_").includes(normalized)));
+}
+/**
+ * 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 function optionElementId(prefix, value) {
+    const encoded = value.replace(/[^A-Za-z0-9-]/g, (char) => `_${char.codePointAt(0)?.toString(16)}_`);
+    return `${prefix}-option-${encoded}`;
+}
+/**
+ * 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 function nextActiveIndex(current, delta, length) {
+    if (length === 0)
+        return -1;
+    if (current < 0)
+        return delta === 1 ? 0 : length - 1;
+    return (current + delta + length) % length;
+}
+/**
+ * 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 function scrollOptionIntoView(list, index) {
+    const element = list?.querySelector(`[data-index="${index}"]`);
+    const previous = element?.previousElementSibling ?? null;
+    if (previous?.getAttribute("role") === "presentation") {
+        previous.scrollIntoView({ block: "nearest" });
+    }
+    element?.scrollIntoView({ block: "nearest" });
+}
+/** One `role="option"` row. Pointer moves highlight it; clicks commit it. */
+export function OptionRow({ option, index, active, selected, idPrefix, onCommit, onActivate, children, }) {
+    return (_jsxs("button", { "aria-selected": selected, className: cn(
+        // Every row takes the full text colour. The muted weight this used to
+        // carry belongs to a list read *beside* the answer — `Combobox`'s field
+        // holds the committed value above its own popup — and reads wrong where
+        // the popup is the choice: options dimmer than the heading over them
+        // make the things you may pick look less available than the label for
+        // them.
+        // The label takes the free space rather than the row distributing it:
+        // `justify-between` spreads three children across the row, so a row
+        // carrying both trailing content and the selected mark would strand its
+        // trailing content in the middle. Pushing off the first child instead
+        // packs everything after it to the right, for any number of them.
+        "flex w-full items-center gap-3 rounded-[var(--ssui-radius-sm)] px-2 py-1.5 text-left text-sm text-[color:var(--ssui-text)] transition-colors [&>:first-child]:mr-auto", 
+        // Selection is carried by the check and the weight, with the fill as
+        // support rather than as the signal. The fill is `--ssui-surface-muted`
+        // on `--ssui-surface-elevated`, which is a clear step in a light theme
+        // and almost none in a dark one, so a reader in dark had no reliable way
+        // to tell which row was current.
+        selected && "bg-[color:var(--ssui-surface-muted)] font-medium", 
+        // The highlight is where the pointer or the keyboard is *now*, so it
+        // wins the background: it lands last, and `cn` is tailwind-merge. The
+        // other order hid the highlight on the selected row, which is the row a
+        // popup opens on.
+        active ? "bg-[color:var(--ssui-overlay-hover)]" : "hover:bg-[color:var(--ssui-overlay-hover)]"), "data-index": index, id: optionElementId(idPrefix, option.value), onClick: () => onCommit(option), 
+        // Keep focus where the keyboard model lives — the input or the listbox —
+        // rather than letting a click move it onto the row.
+        onMouseDown: (event) => event.preventDefault(), onMouseMove: () => onActivate(index), role: "option", tabIndex: -1, type: "button", children: [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, selected ? _jsx(Check, { "aria-hidden": "true", className: "size-4 shrink-0" }) : null] }));
+}
+/**
+ * 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 const OptionListbox = React.forwardRef(({ id, idPrefix, options, value, activeIndex, onActivate, onCommit, emptyMessage = "No matches", children, className, ...rest }, ref) => {
+    const rows = [];
+    options.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 }] });
+    });
+    const renderOption = ({ option, index }) => (_jsx(OptionRow, { active: index === activeIndex, idPrefix: idPrefix, index: index, onActivate: onActivate, onCommit: onCommit, option: option, selected: option.value === value }, option.value));
+    return (_jsxs("div", { ...rest, className: className, id: id, ref: ref, role: "listbox", children: [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": `${idPrefix}-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: `${idPrefix}-group-${rowIndex}`, role: "presentation", children: row.group }), row.entries.map(renderOption)] }, `group-${rowIndex}`))), children, rows.length === 0 && emptyMessage !== null ? (_jsx("div", { className: "px-2 py-1.5 text-sm text-[color:var(--ssui-text-subtle)]", children: emptyMessage })) : null] }));
+});
+OptionListbox.displayName = "OptionListbox";

package/dist/components/popover.d.ts

@@ -0,0 +1,23 @@
+import * as PopoverPrimitive from "@radix-ui/react-popover";
+import * as React from "react";
+/**
+ * The thin styled wrapper `dropdown-menu.tsx` gives its primitive, for the
+ * anchored panel that is not a menu: a popup holding a filter field, a form, or
+ * a list that keeps its own keyboard model. Radix supplies the portal, the
+ * collision-aware placement, and dismissal on outside click or Escape, and
+ * imposes no roving focus or typeahead of its own — which is what separates it
+ * from `DropdownMenu` and why `SelectMenu` is built on it.
+ */
+export declare const Popover: React.FC<PopoverPrimitive.PopoverProps>;
+export declare const PopoverTrigger: React.ForwardRefExoticComponent<PopoverPrimitive.PopoverTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const PopoverAnchor: React.ForwardRefExoticComponent<PopoverPrimitive.PopoverAnchorProps & React.RefAttributes<HTMLDivElement>>;
+export declare const PopoverClose: React.ForwardRefExoticComponent<PopoverPrimitive.PopoverCloseProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const PopoverPortal: React.FC<PopoverPrimitive.PopoverPortalProps>;
+export declare const PopoverContent: React.ForwardRefExoticComponent<Omit<PopoverPrimitive.PopoverContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
+    /**
+     * Render the panel through a portal to `document.body` (the default). Pass
+     * `false` to render it inline, next to the trigger, when the panel must stay
+     * inside a subtree that tracks focus or owns its own stacking context.
+     */
+    portal?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;

package/dist/components/popover.js

@@ -0,0 +1,32 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as PopoverPrimitive from "@radix-ui/react-popover";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+/**
+ * The thin styled wrapper `dropdown-menu.tsx` gives its primitive, for the
+ * anchored panel that is not a menu: a popup holding a filter field, a form, or
+ * a list that keeps its own keyboard model. Radix supplies the portal, the
+ * collision-aware placement, and dismissal on outside click or Escape, and
+ * imposes no roving focus or typeahead of its own — which is what separates it
+ * from `DropdownMenu` and why `SelectMenu` is built on it.
+ */
+export const Popover = PopoverPrimitive.Root;
+export const PopoverTrigger = PopoverPrimitive.Trigger;
+export const PopoverAnchor = PopoverPrimitive.Anchor;
+export const PopoverClose = PopoverPrimitive.Close;
+export const PopoverPortal = PopoverPrimitive.Portal;
+export const PopoverContent = React.forwardRef(({ align = "start", className, collisionPadding = 8, portal = true, sideOffset = 6, ...props }, ref) => {
+    const content = (_jsx(PopoverPrimitive.Content, { ref: ref, align: align, collisionPadding: collisionPadding, sideOffset: sideOffset, className: cn(
+        // The panel is bounded by the space actually available at its
+        // placement. Radix measures that per placement and publishes it here.
+        // Without a ceiling the panel is sized by its widest content, and
+        // collision handling *shifts* a panel rather than shrinking it, so past
+        // the viewport there is nowhere left to shift to. Content that can
+        // ellipsize then does; content that cannot scrolls. `cn` is
+        // tailwind-merge, so a caller needing a different bound says so in
+        // `className` and replaces this rather than racing it.
+        "z-50 min-w-44 max-w-[var(--radix-popover-content-available-width)] rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border)] bg-[color:var(--ssui-surface-elevated)] p-1 text-[color:var(--ssui-text)] shadow-[var(--ssui-shadow-md)] outline-none", className), ...props }));
+    return portal ? _jsx(PopoverPrimitive.Portal, { children: content }) : content;
+});
+PopoverContent.displayName = PopoverPrimitive.Content.displayName;

package/dist/components/role-menu.d.ts

@@ -72,11 +72,13 @@ export interface RoleMenuProps {
 /**
  * Single choice from a small closed set where each option needs a sentence.
  *
- * The third answer to "pick one of a few" in this package, and the one to reach
- * for when the options need explaining: `Select` is a native `<select>` whose
- * options may hold only text, and `Combobox` is a filterable input for lists long
- * enough to search. A role set is neither — two or three options, each carrying a
- * meaning the reader cannot infer from its name.
+ * One of four answers to "pick one" in this package, and the one to reach for
+ * when the options need explaining: `Select` is a native `<select>` whose
+ * options may hold only text, `Combobox` is a filterable input for lists long
+ * enough to search, and `SelectMenu` is the `Select` slot drawn as a menu. A
+ * role set is none of those — two or three options, each carrying a meaning the
+ * reader cannot infer from its name. The four and which case each answers are
+ * tabled once, in `docs/packages/saas-ui.md`.
  *
  * Options are radio items rather than plain menu items, so assistive technology
  * announces the option set and which member of it is current instead of leaving

package/dist/components/role-menu.js

@@ -9,11 +9,13 @@ import { useFormField, useFormFieldProps } from "./form-field.js";
 /**
  * Single choice from a small closed set where each option needs a sentence.
  *
- * The third answer to "pick one of a few" in this package, and the one to reach
- * for when the options need explaining: `Select` is a native `<select>` whose
- * options may hold only text, and `Combobox` is a filterable input for lists long
- * enough to search. A role set is neither — two or three options, each carrying a
- * meaning the reader cannot infer from its name.
+ * One of four answers to "pick one" in this package, and the one to reach for
+ * when the options need explaining: `Select` is a native `<select>` whose
+ * options may hold only text, `Combobox` is a filterable input for lists long
+ * enough to search, and `SelectMenu` is the `Select` slot drawn as a menu. A
+ * role set is none of those — two or three options, each carrying a meaning the
+ * reader cannot infer from its name. The four and which case each answers are
+ * tabled once, in `docs/packages/saas-ui.md`.
  *
  * Options are radio items rather than plain menu items, so assistive technology
  * announces the option set and which member of it is current instead of leaving

package/dist/components/select-menu.d.ts

@@ -0,0 +1,128 @@
+import * as React from "react";
+import type { ComboboxOption } from "./option-list.js";
+import type { SelectSize } from "./select.js";
+export type SelectMenuVariant = "control" | "inline";
+/**
+ * The option count at which `SelectMenu` shows a filter when the consumer has
+ * not said either way. Below it the whole list is on screen at once, and a
+ * filter is a row to skip past on the way to an answer already visible; above
+ * it the reader is scanning. Exported so a consumer can compare against it
+ * rather than duplicate the number.
+ */
+export declare const SELECT_MENU_SEARCH_THRESHOLD = 8;
+export interface SelectMenuProps {
+    /** The same option shape `Combobox` takes, groups included. Never reordered. */
+    options: ReadonlyArray<ComboboxOption>;
+    /** Selected option value. The component never changes this itself. */
+    value?: string;
+    /** Called with the chosen value; never fired for the option already selected. */
+    onValueChange?: (value: string) => void | Promise<void>;
+    /**
+     * How the trigger is drawn. `"control"` (the default) is `Select`'s bounded
+     * field with a chevron, in the same `sm`/`md` scale, so swapping one for the
+     * other returns the same field with a themed popup. `"inline"` draws no box
+     * at rest: the trigger is the label's own text on the row's own background,
+     * sized by the line it sits in, with the chevron and hover surface appearing
+     * on hover and focus. That is the presentation a dense properties row needs,
+     * and the reason this component exists — see `docs/packages/saas-ui.md`.
+     */
+    variant?: SelectMenuVariant;
+    /** Control scale for `variant="control"`. Ignored by `"inline"`, which takes its line from the text around it. */
+    size?: SelectSize;
+    /**
+     * Whether the popup carries a filter field. Left unset, the component decides
+     * from the option count: a filter at `SELECT_MENU_SEARCH_THRESHOLD` options
+     * or more, none below. `true` forces one onto a short list; `false` keeps one
+     * off a long one.
+     */
+    searchable?: boolean;
+    /** Placeholder for the filter field. Defaults to "Search". */
+    searchPlaceholder?: string;
+    /**
+     * Shown in the popup when there is nothing to list. Defaults to "No matches"
+     * when a filter is shown and "No options" when there is none — a list that
+     * has not loaded has not failed a search. `null` shows nothing at all, the
+     * meaning it carries on `Combobox`.
+     */
+    emptyMessage?: React.ReactNode;
+    /**
+     * Offer clearing the value as a row among the options, labelled with this
+     * text — "Empty", "None", "Unassigned". Choosing it reports `""`. Absent, no
+     * such row is offered.
+     */
+    emptyLabel?: string;
+    /**
+     * What the trigger shows when no option matches `value` — a field with
+     * nothing chosen, or one holding a value the list no longer offers. Rendered
+     * in the subtle text colour so it reads as a prompt rather than a choice.
+     */
+    placeholder?: React.ReactNode;
+    /** Submits the selected value with the surrounding form through a hidden input. */
+    name?: string;
+    disabled?: boolean;
+    /**
+     * Which edge of the trigger the popup aligns to. Defaults to `"start"`; a
+     * right-aligned trigger wants `"end"` so the popup opens inward rather than
+     * relying on collision detection to rescue it.
+     */
+    align?: "start" | "center" | "end";
+    /** Controlled open state. */
+    open?: boolean;
+    /**
+     * Open on mount. For a consumer whose control appears in response to an edit
+     * gesture — a click on the value it replaces — so that choosing a value is
+     * one click from the row rather than two.
+     */
+    defaultOpen?: boolean;
+    /**
+     * Notified whenever the popup opens or closes, whichever side asked for it.
+     * `false` after a choice and after a dismissal alike; a consumer that treats
+     * "closed without choosing" as a cancel reads it together with
+     * `onValueChange`, which fires first.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /** Trigger id. Supplied by an enclosing `FormField` when there is one. */
+    id?: string;
+    /**
+     * Names the trigger's purpose, e.g. `"Owner"` on a record's properties. The
+     * current value is appended — the accessible name has to contain the
+     * trigger's visible text for voice control (WCAG 2.5.3), and a card of ten
+     * triggers all named by their values says nothing about what each one sets.
+     * Inside a `FormField` the field's visible label already names the control,
+     * so leave this unset there: an explicit `aria-label` still wins over the
+     * label, as it does on `RoleMenu`. With neither, the visible text is the name.
+     */
+    "aria-label"?: string;
+    "aria-describedby"?: string;
+    "aria-invalid"?: React.AriaAttributes["aria-invalid"];
+    /** Extra classes for the trigger. */
+    className?: string;
+}
+/**
+ * Single choice from a list, in a popup this package draws.
+ *
+ * The fourth answer to "choose one" here, and the one to reach for when the
+ * popup's appearance is the point: `Select` is the native control, whose popup
+ * belongs to the platform and cannot be themed past its background colour;
+ * `Combobox` is a search field for lists too long to read; `RoleMenu` is for
+ * two or three options that each need a sentence. `SelectMenu` is the `Select`
+ * slot drawn as a menu — a trigger that can read as bounded field or as plain
+ * text, an option list with headings, and a filter once the list is long
+ * enough to want one. The table in `docs/packages/saas-ui.md` says which of the
+ * four answers which case.
+ *
+ * Built on `Popover` rather than `DropdownMenu` because a menu's roving focus
+ * and typeahead both fight a filter field. Inside the popup the list runs the
+ * listbox pattern with `aria-activedescendant`: focus stays in the filter field
+ * when there is one, or on the listbox itself when there is not, and the
+ * highlight moves independently — the model `Combobox` already implements, and
+ * the same option list rendering, extracted so the two cannot drift.
+ *
+ * What it gives up, stated plainly: on a phone a native `<select>` opens the
+ * platform's own picker, and this cannot. `Select` stays for the bounded form
+ * field where that is worth more than a themed popup.
+ */
+export declare function SelectMenu({ options, value, onValueChange, variant, size, searchable, searchPlaceholder, emptyMessage, emptyLabel, placeholder, name, disabled, align, open: openProp, defaultOpen, onOpenChange, className, ...ariaProps }: SelectMenuProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace SelectMenu {
+    var displayName: string;
+}

package/dist/components/select-menu.js

@@ -0,0 +1,219 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ChevronDown } from "lucide-react";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+import { useFormFieldProps } from "./form-field.js";
+import { OptionListbox, defaultOptionFilter, nextActiveIndex, optionElementId, scrollOptionIntoView, } from "./option-list.js";
+import { Popover, PopoverContent, PopoverTrigger } from "./popover.js";
+/**
+ * The option count at which `SelectMenu` shows a filter when the consumer has
+ * not said either way. Below it the whole list is on screen at once, and a
+ * filter is a row to skip past on the way to an answer already visible; above
+ * it the reader is scanning. Exported so a consumer can compare against it
+ * rather than duplicate the number.
+ */
+export const SELECT_MENU_SEARCH_THRESHOLD = 8;
+// Height, text and padding are held together per size rather than split across
+// rules, matching `Select`, so the two controls line up when swapped.
+const CONTROL_SIZE_CLASSES = {
+    md: "h-10 py-2 pl-3 pr-3 text-sm",
+    sm: "h-8 py-1 pl-2.5 pr-2.5 text-xs",
+};
+/**
+ * Single choice from a list, in a popup this package draws.
+ *
+ * The fourth answer to "choose one" here, and the one to reach for when the
+ * popup's appearance is the point: `Select` is the native control, whose popup
+ * belongs to the platform and cannot be themed past its background colour;
+ * `Combobox` is a search field for lists too long to read; `RoleMenu` is for
+ * two or three options that each need a sentence. `SelectMenu` is the `Select`
+ * slot drawn as a menu — a trigger that can read as bounded field or as plain
+ * text, an option list with headings, and a filter once the list is long
+ * enough to want one. The table in `docs/packages/saas-ui.md` says which of the
+ * four answers which case.
+ *
+ * Built on `Popover` rather than `DropdownMenu` because a menu's roving focus
+ * and typeahead both fight a filter field. Inside the popup the list runs the
+ * listbox pattern with `aria-activedescendant`: focus stays in the filter field
+ * when there is one, or on the listbox itself when there is not, and the
+ * highlight moves independently — the model `Combobox` already implements, and
+ * the same option list rendering, extracted so the two cannot drift.
+ *
+ * What it gives up, stated plainly: on a phone a native `<select>` opens the
+ * platform's own picker, and this cannot. `Select` stays for the bounded form
+ * field where that is worth more than a themed popup.
+ */
+export function SelectMenu({ options, value, onValueChange, variant = "control", size = "md", searchable, searchPlaceholder = "Search", emptyMessage, emptyLabel, placeholder, name, disabled, align = "start", open: openProp, defaultOpen = false, onOpenChange, className, ...ariaProps }) {
+    // An enclosing `FormField` owns the trigger's id and error wiring, as it does
+    // for `Input`, `Combobox` and `RoleMenu`.
+    const { "aria-label": ariaLabel, ...fieldProps } = useFormFieldProps(ariaProps);
+    const generatedId = React.useId();
+    const id = fieldProps.id ?? generatedId;
+    const listboxId = `${id}-listbox`;
+    const filterId = `${id}-filter`;
+    const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen);
+    const open = openProp ?? uncontrolledOpen;
+    const [query, setQuery] = React.useState("");
+    const [activeIndex, setActiveIndex] = React.useState(-1);
+    const filterRef = React.useRef(null);
+    const listRef = React.useRef(null);
+    const triggerRef = React.useRef(null);
+    // The empty choice is a real option at the head of the list — it shares the
+    // index space, the highlight and `aria-activedescendant` — so no second
+    // keyboard path exists for it. `""` is what it reports. An empty `value` is
+    // "nothing chosen" everywhere below rather than "the empty row is chosen":
+    // the trigger shows its placeholder, no row is marked current, and the list
+    // opens with nothing highlighted.
+    const chosen = value === "" ? undefined : value;
+    const selected = options.find((option) => option.value === chosen);
+    const selectedLabel = selected?.inputLabel ?? selected?.label;
+    const offered = emptyLabel !== undefined ? [{ value: "", label: emptyLabel }, ...options] : [...options];
+    const showFilter = searchable ?? options.length >= SELECT_MENU_SEARCH_THRESHOLD;
+    // A freshly opened list starts with nothing typed and the current value
+    // highlighted, so Enter with no other key confirms what is already set and an
+    // arrow moves from it rather than from the top. The reset keys on the open
+    // state itself rather than on the trigger, because the trigger is only one
+    // way in: `defaultOpen` and a consumer flipping `open` from its own gesture —
+    // the click-to-edit row this component exists for — never touch it. Done
+    // during render, in the pattern React documents for reacting to a prop
+    // change, so the popup's first frame is already reset rather than one frame
+    // stale.
+    const [wasOpen, setWasOpen] = React.useState(false);
+    if (open !== wasOpen) {
+        setWasOpen(open);
+        if (open) {
+            setQuery("");
+            setActiveIndex(chosen === undefined ? -1 : offered.findIndex((option) => option.value === chosen));
+        }
+    }
+    const navigable = showFilter ? offered.filter((option) => defaultOptionFilter(option, query)) : offered;
+    const activeOption = activeIndex >= 0 ? navigable[activeIndex] : undefined;
+    function setOpen(next) {
+        if (next === open)
+            return;
+        if (openProp === undefined)
+            setUncontrolledOpen(next);
+        onOpenChange?.(next);
+    }
+    function commit(option) {
+        if (option.value !== (value ?? ""))
+            void onValueChange?.(option.value);
+        setOpen(false);
+    }
+    function moveActive(delta) {
+        if (navigable.length === 0)
+            return;
+        const next = nextActiveIndex(activeIndex, delta, navigable.length);
+        setActiveIndex(next);
+        scrollOptionIntoView(listRef.current, next);
+    }
+    function handleKeyDown(event) {
+        if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+            event.preventDefault();
+            moveActive(event.key === "ArrowDown" ? 1 : -1);
+            return;
+        }
+        if (event.key === "Home" || event.key === "End") {
+            if (navigable.length === 0)
+                return;
+            event.preventDefault();
+            const next = event.key === "Home" ? 0 : navigable.length - 1;
+            setActiveIndex(next);
+            scrollOptionIntoView(listRef.current, next);
+            return;
+        }
+        if (event.key === "Enter") {
+            // The open popup owns Enter whether or not anything is highlighted, so a
+            // stray press cannot reach the form behind the control.
+            event.preventDefault();
+            if (activeOption)
+                commit(activeOption);
+        }
+        // Escape is left to the popover, which closes on it and returns focus to
+        // the trigger; stopping it here would keep the popup open.
+    }
+    function handleTriggerKeyDown(event) {
+        // A native `<select>` opens on either arrow, and so does `RoleMenu`; a user
+        // swapping `Select` for this keeps the key. Space and Enter are the button's
+        // own, and the open state's reset above does the rest.
+        if (open || (event.key !== "ArrowDown" && event.key !== "ArrowUp"))
+            return;
+        event.preventDefault();
+        setOpen(true);
+    }
+    // The name carries purpose and current value, as `RoleMenu`'s does. A
+    // `FormField`'s visible label does that job better, so a consumer inside one
+    // passes no `aria-label`; one that does gets what it asked for, as it would
+    // from `RoleMenu`. With neither, the button's own text — the current value —
+    // is its name.
+    const currentText = selectedLabel ?? (typeof placeholder === "string" ? placeholder : "none");
+    const triggerLabel = ariaLabel ? `${ariaLabel} (current: ${currentText})` : undefined;
+    const activeDescendant = open && activeOption ? optionElementId(id, activeOption.value) : undefined;
+    return (_jsxs(_Fragment, { children: [name ? _jsx("input", { disabled: disabled, name: name, type: "hidden", value: value ?? "" }) : null, _jsxs(Popover, { onOpenChange: setOpen, open: open, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs("button", { ...fieldProps, "aria-controls": open ? listboxId : undefined, "aria-haspopup": "listbox", "aria-label": triggerLabel, className: cn("group/select-menu inline-flex items-center gap-1.5 text-left transition-colors focus-visible:outline-none", variant === "control"
+                                ? cn(
+                                // `Select`'s field, so the two line up when swapped: same
+                                // radius, border, shadow, sizes, and ring with an offset.
+                                "w-full justify-between rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border-control,var(--ssui-border))] bg-[color:var(--ssui-surface)] text-[color:var(--ssui-text)] shadow-sm 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:pointer-events-none disabled:cursor-not-allowed disabled:bg-[color:var(--ssui-surface-muted)] disabled:opacity-70", CONTROL_SIZE_CLASSES[size])
+                                : // No box at rest: the row's own text on the row's own background,
+                                    // and only as wide as that text — `w-fit`, because a grid or flex
+                                    // cell would otherwise stretch it, and a hover surface the width
+                                    // of the row reads as a bar rather than as the value lighting up.
+                                    // The hover surface and the chevron arrive on hover, focus and
+                                    // while open, and the focus ring carries no offset — an inline
+                                    // trigger sits in a line with a couple of pixels to give, and a
+                                    // ring pushed outside it lands on the lines above and below
+                                    // rather than on this one. The ring is 2px, so with no offset
+                                    // it fits exactly the gutter a dense list keeps. Disabled, the
+                                    // pointer gets nothing: hover is the whole signal this variant
+                                    // uses to say "operable", so it must not light up and grow a
+                                    // chevron for a trigger that will then do nothing.
+                                    "-mx-1 w-fit max-w-full rounded-[var(--ssui-radius-sm)] px-1 text-[color:var(--ssui-text)] hover:bg-[color:var(--ssui-overlay-hover)] focus-visible:ring-2 focus-visible:ring-[color:var(--ssui-focus-ring)] data-[state=open]:bg-[color:var(--ssui-overlay-hover)] disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-70", className), disabled: disabled, onKeyDown: handleTriggerKeyDown, ref: triggerRef, type: "button", children: [_jsx("span", { className: cn("min-w-0 truncate", selectedLabel === undefined && "text-[color:var(--ssui-text-subtle)]"), children: selectedLabel ?? placeholder }), _jsx(ChevronDown, { "aria-hidden": "true", className: cn("shrink-0 text-[color:var(--ssui-text-subtle)]", variant === "control"
+                                        ? size === "sm"
+                                            ? "size-3.5"
+                                            : "size-4"
+                                        : "size-3.5 opacity-0 transition-opacity group-hover/select-menu:opacity-100 group-focus-visible/select-menu:opacity-100 group-data-[state=open]/select-menu:opacity-100") })] }) }), _jsxs(PopoverContent, { align: align, 
+                        // The panel's own padding plus a row's puts an option's text 12px
+                        // inside the panel, while an inline trigger's text sits 4px inside the
+                        // box the panel aligns to. Pulling the panel back by the difference
+                        // lands the options directly under the value they replace, so the
+                        // popup reads as that value opening rather than as a panel arriving
+                        // beside it. A bounded trigger's own padding already matches, so it
+                        // needs no correction.
+                        alignOffset: variant === "inline" ? -8 : 0, className: cn("p-1", 
+                        // A bounded trigger's popup starts at the field's own width, so the two
+                        // read as one control rather than as a panel that happens to be near it,
+                        // and grows only if an option needs more than the field has. A fixed
+                        // width would truncate those options; a fixed minimum — which this used
+                        // to carry for both variants — made every narrow field's popup overhang
+                        // it, which is what the field-type control showed. An inline trigger is
+                        // as wide as its text, which is no width for a list, so it keeps a floor
+                        // of its own.
+                        variant === "control" ? "min-w-[var(--radix-popover-trigger-width)]" : "min-w-56"), onCloseAutoFocus: (event) => {
+                            // Focus returns to the trigger on close — unless the trigger has
+                            // left the document with the popup, as it does when a consumer
+                            // unmounts the control on a choice or a cancel. Returning focus to
+                            // a detached element is a no-op that still pre-empts wherever the
+                            // consumer then puts it, so the return is skipped and left to them.
+                            if (!triggerRef.current?.isConnected)
+                                event.preventDefault();
+                        }, onOpenAutoFocus: (event) => {
+                            // Focus goes to whichever element runs the keyboard model — the
+                            // filter field, or the listbox itself when there is none — not to
+                            // the first tabbable thing Radix would pick.
+                            event.preventDefault();
+                            (filterRef.current ?? listRef.current)?.focus();
+                        }, 
+                        // The panel is a listbox popup, not a dialog: the element that holds
+                        // focus inside it announces itself, and a "dialog" wrapper around a
+                        // select's options would be one more thing to hear on the way to them.
+                        role: "presentation", children: [showFilter ? (_jsx("input", { "aria-activedescendant": activeDescendant, "aria-autocomplete": "list", "aria-controls": listboxId, "aria-expanded": "true", "aria-label": searchPlaceholder, autoComplete: "off", className: "mb-1 flex h-8 w-full rounded-[var(--ssui-radius-sm)] border border-[color:var(--ssui-border-control,var(--ssui-border))] bg-[color:var(--ssui-surface)] px-2 text-sm text-[color:var(--ssui-text)] placeholder:text-[color:var(--ssui-text-subtle)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ssui-focus-ring)]", id: filterId, onChange: (event) => {
+                                    setQuery(event.target.value);
+                                    setActiveIndex(-1);
+                                }, onKeyDown: handleKeyDown, placeholder: searchPlaceholder, ref: filterRef, role: "combobox", type: "text", value: query })) : null, _jsx(OptionListbox, { activeIndex: activeIndex, "aria-activedescendant": showFilter ? undefined : activeDescendant, "aria-label": showFilter ? undefined : ariaLabel, className: "max-h-64 overflow-y-auto outline-none", 
+                                // `undefined` is "the consumer said nothing"; `null` is "show
+                                // nothing", which the list documents and `Combobox` honours. `??`
+                                // would swallow the second, so the test is on `undefined` alone.
+                                emptyMessage: emptyMessage !== undefined ? emptyMessage : showFilter ? "No matches" : "No options", id: listboxId, idPrefix: id, onActivate: setActiveIndex, onCommit: commit, onKeyDown: showFilter ? undefined : handleKeyDown, options: navigable, ref: listRef, tabIndex: showFilter ? undefined : -1, value: chosen })] })] })] }));
+}
+SelectMenu.displayName = "SelectMenu";

package/dist/components/select.d.ts

@@ -12,5 +12,11 @@ export interface SelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectE
  * Styled native `<select>` matching the shared `Input` look, with a trailing
  * chevron. Native on purpose: correct mobile behavior and form participation
  * with zero positioning code. Participates in `FormField` wiring.
+ *
+ * The default for a bounded field in an ordinary form. Its popup belongs to the
+ * platform and cannot be themed past its background colour; where that popup is
+ * the whole of what the reader sees — a choice presented as inline text — reach
+ * for `SelectMenu` instead. The four single-choice controls and which case each
+ * answers are tabled once, in `docs/packages/saas-ui.md`.
  */
 export declare const Select: React.ForwardRefExoticComponent<SelectProps & React.RefAttributes<HTMLSelectElement>>;

package/dist/components/select.js

@@ -14,6 +14,12 @@ const SIZE_CLASSES = {
  * Styled native `<select>` matching the shared `Input` look, with a trailing
  * chevron. Native on purpose: correct mobile behavior and form participation
  * with zero positioning code. Participates in `FormField` wiring.
+ *
+ * The default for a bounded field in an ordinary form. Its popup belongs to the
+ * platform and cannot be themed past its background colour; where that popup is
+ * the whole of what the reader sees — a choice presented as inline text — reach
+ * for `SelectMenu` instead. The four single-choice controls and which case each
+ * answers are tabled once, in `docs/packages/saas-ui.md`.
  */
 export const Select = React.forwardRef(({ className, children, size = "md", ...props }, ref) => (_jsxs("div", { className: cn("relative", className), children: [_jsx("select", { ref: ref, className: cn("flex w-full cursor-pointer appearance-none rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border-control,var(--ssui-border))] bg-[color:var(--ssui-surface)] text-[color:var(--ssui-text)] shadow-sm transition-colors 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", SIZE_CLASSES[size].select), ...useFormFieldProps(props), children: children }), _jsx(ChevronDown, { "aria-hidden": "true", className: cn("pointer-events-none absolute top-1/2 -translate-y-1/2 text-[color:var(--ssui-text-subtle)]", SIZE_CLASSES[size].chevron) })] })));
 Select.displayName = "Select";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardreach/saas-ui",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Brand-neutral React UI primitives and SaaS app patterns for ForwardReach-owned business applications.",
   "type": "module",
   "private": false,
@@ -51,6 +51,7 @@
     "@radix-ui/react-avatar": "^1.1.10",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-popover": "^1.1.23",
     "@radix-ui/react-scroll-area": "^1.2.10",
     "@radix-ui/react-separator": "^1.1.7",
     "@radix-ui/react-slot": "^1.2.4",
@@ -72,7 +73,7 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.4"
   },
-  "gitHead": "544931dd34ff3f738a58cf9e7ad161fb8fa8763f",
+  "gitHead": "7517a542f48380e40fb8d7632f12ce352151487d",
   "scripts": {
     "build": "pnpm clean && tsc -p tsconfig.build.json && node scripts/copy-styles.mjs",
     "dev": "node scripts/copy-styles.mjs && tsc -p tsconfig.build.json --watch",