@forwardreach/saas-ui 0.11.0 → 0.13.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/page-container.d.ts

@@ -0,0 +1,7 @@
+import * as React from "react";
+export type PageContainerWidth = "narrow" | "wide" | "full";
+export interface PageContainerProps extends React.HTMLAttributes<HTMLDivElement> {
+    asChild?: boolean;
+    width?: PageContainerWidth;
+}
+export declare const PageContainer: React.ForwardRefExoticComponent<PageContainerProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/page-container.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Slot } from "@radix-ui/react-slot";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+/**
+ * The centered column a page sits in. The widths are a vocabulary, not numbers: `narrow` is a
+ * reading column (a timeline, a record), `wide` a working column (a collection, a list of
+ * things to act on), and `full` a workspace that fills what it is given (an inbox, an editor).
+ * `full` exists so a full-bleed page still declares that it made a choice.
+ */
+const widthClasses = {
+    narrow: "mx-auto w-full max-w-3xl px-4 py-5 md:px-8 md:py-8",
+    wide: "mx-auto w-full max-w-5xl px-4 py-5 md:px-8 md:py-8",
+    full: "w-full"
+};
+export const PageContainer = React.forwardRef(({ asChild = false, className, width = "wide", ...props }, ref) => {
+    const Comp = asChild ? Slot : "div";
+    return (_jsx(Comp, { ref: ref, className: cn(widthClasses[width], className), "data-width": width, ...props }));
+});
+PageContainer.displayName = "PageContainer";

package/dist/components/page-header.d.ts

@@ -1,10 +1,30 @@
 import * as React from "react";
 export interface PageHeaderProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
     actions?: React.ReactNode;
+    /**
+     * Context that is not an action — today's date, a count — rendered on the title's baseline
+     * at the right edge of the title row. The slot sets no type; size it as the page wants.
+     * `actions` keeps its own slot, so the two never share a line at narrow widths.
+     */
+    aside?: React.ReactNode;
     breadcrumbs?: React.ReactNode;
     description?: React.ReactNode;
+    /** Draw the bottom rule. Off by default: a main page has none, a settings page opts in. */
+    divider?: boolean;
     eyebrow?: React.ReactNode;
     metadata?: React.ReactNode;
     title: React.ReactNode;
 }
-export declare function PageHeader({ actions, breadcrumbs, className, description, eyebrow, metadata, title, ...props }: PageHeaderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * The page title in the shape a host draws its own main pages in: `text-xl` rising to
+ * `text-2xl` at the small breakpoint, no rule beneath unless asked for. A page built only
+ * from shared parts should be indistinguishable from one the host draws by hand, which is
+ * why the default is the host's shape and the previous one is a prop away.
+ *
+ * From the small breakpoint the title and actions share a row only while both fit: the row
+ * wraps, so a toolbar wider than the space beside the title drops beneath it (as it does on a
+ * phone) rather than squeezing the title to nothing or running past the page edge. The title
+ * column's basis is its own min-content — the whole title, since the heading does not wrap — so
+ * the row breaks exactly when the full title and the actions no longer fit side by side.
+ */
+export declare function PageHeader({ actions, aside, breadcrumbs, className, description, divider, eyebrow, metadata, title, ...props }: PageHeaderProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/page-header.js

@@ -1,6 +1,18 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { cn } from "../utils/cn.js";
-export function PageHeader({ actions, breadcrumbs, className, description, eyebrow, metadata, title, ...props }) {
-    return (_jsxs("header", { className: cn("flex flex-col gap-4 border-b border-[color:var(--ssui-border)] pb-4 sm:flex-row sm:items-end sm:justify-between", className), ...props, children: [_jsxs("div", { className: "min-w-0 space-y-2", children: [breadcrumbs ? _jsx("div", { children: breadcrumbs }) : null, eyebrow ? (_jsx("div", { className: "text-xs font-medium uppercase text-[color:var(--ssui-text-muted)]", children: eyebrow })) : null, _jsxs("div", { className: "space-y-1", children: [_jsx("h1", { className: "truncate text-2xl font-semibold text-[color:var(--ssui-text)]", children: title }), description ? (_jsx("div", { className: "max-w-3xl text-sm text-[color:var(--ssui-text-muted)]", children: description })) : null] }), metadata ? _jsx("div", { className: "flex flex-wrap gap-2", children: metadata }) : null] }), actions ? _jsx("div", { className: "flex shrink-0 flex-wrap gap-2", children: actions }) : null] }));
+/**
+ * The page title in the shape a host draws its own main pages in: `text-xl` rising to
+ * `text-2xl` at the small breakpoint, no rule beneath unless asked for. A page built only
+ * from shared parts should be indistinguishable from one the host draws by hand, which is
+ * why the default is the host's shape and the previous one is a prop away.
+ *
+ * From the small breakpoint the title and actions share a row only while both fit: the row
+ * wraps, so a toolbar wider than the space beside the title drops beneath it (as it does on a
+ * phone) rather than squeezing the title to nothing or running past the page edge. The title
+ * column's basis is its own min-content — the whole title, since the heading does not wrap — so
+ * the row breaks exactly when the full title and the actions no longer fit side by side.
+ */
+export function PageHeader({ actions, aside, breadcrumbs, className, description, divider = false, eyebrow, metadata, title, ...props }) {
+    return (_jsxs("header", { className: cn("flex flex-col gap-4 sm:flex-row sm:flex-wrap sm:items-end sm:justify-between", divider && "border-b border-[color:var(--ssui-border)] pb-4", className), ...props, children: [_jsxs("div", { className: "min-w-0 flex-[1_1_min-content] space-y-2", children: [breadcrumbs ? _jsx("div", { children: breadcrumbs }) : null, eyebrow ? (_jsx("div", { className: "text-xs font-medium uppercase text-[color:var(--ssui-text-muted)]", children: eyebrow })) : null, _jsxs("div", { className: "space-y-1", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3", children: [_jsx("h1", { className: "min-w-0 truncate text-xl font-semibold text-[color:var(--ssui-text)] sm:text-2xl", children: title }), aside ? (_jsx("div", { className: "ml-auto shrink-0", "data-slot": "aside", children: aside })) : null] }), description ? (_jsx("div", { className: "max-w-3xl text-sm text-[color:var(--ssui-text-muted)]", children: description })) : null] }), metadata ? _jsx("div", { className: "flex flex-wrap gap-2", children: metadata }) : null] }), actions ? _jsx("div", { className: "flex max-w-full shrink-0 flex-wrap gap-2", children: actions }) : null] }));
 }

package/dist/components/pill.d.ts

@@ -0,0 +1,20 @@
+import * as React from "react";
+/**
+ * The tones are roles, not colors: what the pill refers to. `reference` is a link to a record
+ * (a person's name), `tag` a label attached to one, `attribute` a field, `date` a point in
+ * time, `category` a grouping tag. Each reads its own `--ssui-pill-<tone>-bg` / `-text` pair.
+ */
+export type PillTone = "reference" | "tag" | "attribute" | "date" | "category";
+export interface PillProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /**
+     * Render the consumer's own element (a router link, a button) with the pill's presentation.
+     * The pill carries no `href` or `onClick` of its own: the consumer's element does.
+     */
+    asChild?: boolean;
+    tone?: PillTone;
+}
+/**
+ * An inline reference chip. Sized to sit in a line of text (`align-baseline`), which is where
+ * a reference lives; for a status, use `StatusPill`, whose capitalization and dot say "state".
+ */
+export declare const Pill: React.ForwardRefExoticComponent<PillProps & React.RefAttributes<HTMLSpanElement>>;

package/dist/components/pill.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Slot } from "@radix-ui/react-slot";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+const toneClasses = {
+    // A reference reaches the record it names, so it carries a hairline border: that, and the
+    // border strengthening under a pointer when the consumer has made it a link, is what
+    // separates it from a chip that is only a label.
+    reference: "border border-[color:var(--ssui-border)] bg-[color:var(--ssui-pill-reference-bg)] text-[color:var(--ssui-pill-reference-text)] [&:is(a,button)]:hover:border-[color:var(--ssui-border-strong)]",
+    tag: "bg-[color:var(--ssui-pill-tag-bg)] text-[color:var(--ssui-pill-tag-text)]",
+    attribute: "bg-[color:var(--ssui-pill-attribute-bg)] text-[color:var(--ssui-pill-attribute-text)]",
+    date: "bg-[color:var(--ssui-pill-date-bg)] text-[color:var(--ssui-pill-date-text)]",
+    category: "bg-[color:var(--ssui-pill-category-bg)] text-[color:var(--ssui-pill-category-text)]"
+};
+/**
+ * An inline reference chip. Sized to sit in a line of text (`align-baseline`), which is where
+ * a reference lives; for a status, use `StatusPill`, whose capitalization and dot say "state".
+ */
+export const Pill = React.forwardRef(({ asChild = false, className, tone = "reference", ...props }, ref) => {
+    const Comp = asChild ? Slot : "span";
+    return (_jsx(Comp, { ref: ref, className: cn("inline-flex items-center gap-1 whitespace-nowrap rounded-[var(--ssui-radius)] px-1.5 py-0.5 align-baseline text-xs font-medium leading-tight 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)]", toneClasses[tone], className), "data-tone": tone, ...props }));
+});
+Pill.displayName = "Pill";

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;
+}