@forwardreach/saas-ui 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,128 @@
 # Changelog
 
+## 0.13.0
+
+### Minor Changes
+
+- **The chrome a host draws its own main pages with, so a page built only from shared
+  parts is indistinguishable from one the host draws by hand.** Reviewing ReachMe's
+  PeopleThread extension beside PeopleThread's Timeline found three gaps in this
+  package — no reference pill, no shared page column, and a `PageHeader` whose default
+  was not the host's heading shape — and each was being filled locally, in the wrong
+  place. This release fills them here.
+
+  - **Pill tokens.** `--ssui-pill-<tone>-bg` / `-text` for five tones: `reference` (a
+    link to a record), `tag`, `attribute` (a field), `date`, `category` (a grouping
+    tag). Every default is a _derivation_ of the status and accent ramps, never a
+    literal, so a consumer that has mapped the base contract sees a coherent pair in
+    both themes before it maps a pill token. That is now the rule for any token added
+    for a role a consumer may already color, and a test enforces it. A second test
+    holds the documented token list equal to the shipped declarations, so a consumer
+    can check its mapping for completeness against the docs.
+  - **`PageContainer`.** The centered page column: `width="narrow"` (a reading
+    column, 48rem), `"wide"` (a working column, 64rem), or `"full"` (a workspace, no
+    gutters). A page opts in; a host never wraps another product's page in it.
+  - **`Card`.** The bordered surface — `--ssui-surface` on `--ssui-border` at
+    `--ssui-radius-lg` — with `elevated`, an `interactive` border-hover for a card
+    whose parts are clickable, and `asChild`. Padding is the consumer's. `ListShell`
+    is a different thing and stays.
+  - **`Pill`.** An inline reference chip in the five tones, `align-baseline` so it
+    sits in a line of text, with `asChild` so the consumer's own link carries the
+    presentation. The `reference` tone carries a hairline border, which is what
+    separates a chip that reaches its record from one that is only a label. **The
+    previous `Pill` export was an alias of `Badge`**; the gallery was its only
+    consumer and is updated here, no product consumed it, and the name now means this
+    component. A badge-shaped pill is `Badge variant="outline"`.
+  - **`PageHeader` takes the host's heading shape.** The title ramp is now
+    `text-xl sm:text-2xl` (was `text-2xl`); the bottom rule is an opt-in `divider`
+    prop (was always drawn); a new `aside` slot renders on the title's baseline at
+    the right edge of the title row, for context that is not an action — a date, a
+    count — while `actions` keeps its own slot, so the two never share a line at
+    narrow widths. From `sm` up the header row now wraps: actions too wide to sit
+    beside the full title move to a row beneath it instead of shrinking the title
+    to nothing. **This is a visual change for every consumer that relied on the
+    rule and the larger title.** Pass `divider` where the rule is wanted; both known
+    consumers do so in the commit that takes this version.
+
+## 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 +187,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 +208,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 +239,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 +286,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/badge.d.ts

@@ -6,4 +6,3 @@ export declare const badgeVariants: (props?: ({
 export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement>, VariantProps<typeof badgeVariants> {
 }
 export declare const Badge: React.ForwardRefExoticComponent<BadgeProps & React.RefAttributes<HTMLSpanElement>>;
-export declare const Pill: React.ForwardRefExoticComponent<BadgeProps & React.RefAttributes<HTMLSpanElement>>;

package/dist/components/badge.js

@@ -20,4 +20,3 @@ export const badgeVariants = cva("inline-flex items-center gap-1 rounded-full bo
 });
 export const Badge = React.forwardRef(({ className, variant, ...props }, ref) => (_jsx("span", { ref: ref, className: cn(badgeVariants({ variant, className })), ...props })));
 Badge.displayName = "Badge";
-export const Pill = Badge;

package/dist/components/card.d.ts

@@ -0,0 +1,15 @@
+import * as React from "react";
+export interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
+    asChild?: boolean;
+    /** Sit on `--ssui-surface-elevated` instead of `--ssui-surface`. */
+    elevated?: boolean;
+    /** Strengthen the border on hover, for a card whose parts are clickable. Nothing else changes. */
+    interactive?: boolean;
+}
+/**
+ * The bordered surface: `--ssui-surface` on `--ssui-border` at `--ssui-radius-lg`. Padding is
+ * the consumer's (`className`), because a card holding a row and a card holding a form pad
+ * differently and a default would be overridden everywhere. `ListShell` is a different thing —
+ * the divided list container with header, toolbar, footer, and empty slots — and both stay.
+ */
+export declare const Card: React.ForwardRefExoticComponent<CardProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/card.js

@@ -0,0 +1,17 @@
+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 bordered surface: `--ssui-surface` on `--ssui-border` at `--ssui-radius-lg`. Padding is
+ * the consumer's (`className`), because a card holding a row and a card holding a form pad
+ * differently and a default would be overridden everywhere. `ListShell` is a different thing —
+ * the divided list container with header, toolbar, footer, and empty slots — and both stay.
+ */
+export const Card = React.forwardRef(({ asChild = false, className, elevated = false, interactive = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : "div";
+    return (_jsx(Comp, { ref: ref, className: cn("rounded-[var(--ssui-radius-lg)] border border-[color:var(--ssui-border)] text-[color:var(--ssui-text)]", elevated
+            ? "bg-[color:var(--ssui-surface-elevated)]"
+            : "bg-[color:var(--ssui-surface)]", interactive && "transition-colors hover:border-[color:var(--ssui-border-strong)]", className), ...props }));
+});
+Card.displayName = "Card";

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

@@ -4,6 +4,7 @@ export * from "./avatar.js";
 export * from "./badge.js";
 export * from "./brand-icons.js";
 export * from "./button.js";
+export * from "./card.js";
 export * from "./checkbox.js";
 export * from "./choice-card.js";
 export * from "./collapsible.js";
@@ -23,12 +24,16 @@ export * from "./input.js";
 export * from "./list-shell.js";
 export * from "./login.js";
 export * from "./overflow-menu.js";
+export * from "./page-container.js";
 export * from "./page-header.js";
+export * from "./pill.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

@@ -4,6 +4,7 @@ export * from "./avatar.js";
 export * from "./badge.js";
 export * from "./brand-icons.js";
 export * from "./button.js";
+export * from "./card.js";
 export * from "./checkbox.js";
 export * from "./choice-card.js";
 export * from "./collapsible.js";
@@ -23,12 +24,16 @@ export * from "./input.js";
 export * from "./list-shell.js";
 export * from "./login.js";
 export * from "./overflow-menu.js";
+export * from "./page-container.js";
 export * from "./page-header.js";
+export * from "./pill.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>>;