@forwardreach/saas-ui 0.10.4 → 0.12.0

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

@@ -1,9 +1,22 @@
 import * as React from "react";
-export interface SelectProps extends React.SelectHTMLAttributes<HTMLSelectElement> {
+export type SelectSize = "sm" | "md";
+export interface SelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, "size"> {
+    /**
+     * Control scale. Defaults to `"md"`, which matches `Input`. `"sm"` matches
+     * `Button size="sm"`, which is the reason it exists: a select in an inline
+     * row of small buttons.
+     */
+    size?: SelectSize;
 }
 /**
  * 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>>;