@forwardreach/saas-ui 0.7.0 → 0.10.2

package/CHANGELOG.md

@@ -1,5 +1,126 @@
 # Changelog
 
+## 0.10.2
+
+### Patch Changes
+
+- `Combobox` keyboard scrolling brings a group's heading into view *alongside*
+  its first option rather than instead of it. `0.10.1` scrolled the heading and
+  not the option, which fixed entering a group from above and broke entering
+  one from below: `scrollIntoView({block: "nearest"})` on a heading below the
+  fold aligns its bottom edge with the scrollport's, leaving the newly
+  highlighted option out of view. Two `nearest` calls — heading first, then the
+  option — settle both directions, and losing the highlight is now impossible
+  in either.
+
+  Packed under a new number rather than re-packed under `0.10.1`, which is the
+  practice the `0.10.0` double-pack cost us.
+
+## 0.10.1
+
+### Patch Changes
+
+- `Combobox` grouping now reaches assistive technology. Each run of options
+  sharing a `group` is wrapped in a `role="group"` labelled by its heading (the
+  APG grouped-listbox shape), instead of the heading being a roleless sibling
+  of the options. A roleless element is not in the content model of
+  `role="listbox"`, so the previous markup conveyed the grouping to sighted
+  users only — a regression against the native `<select>` with `<optgroup
+  label>` that consumers replace with this. The options array stays flat and
+  every index the keyboard model uses is unchanged; only the DOM the rows are
+  emitted into differs.
+
+  A consequence, and the behavior the `group` doc comment already promised: an
+  option declaring no `group` after a grouped run now stands outside that
+  group rather than rendering under its heading, the way an `<option>` after an
+  `</optgroup>` does.
+
+- **Behavior change.** `Combobox` now consumes Enter whenever its popup is
+  open, committing the active option where there is one and swallowing the key
+  where there is none. Enter previously fell through to the surrounding form
+  when nothing was highlighted, which was harmless only while every consumer
+  had a submit button to absorb it — and `0.10.0` exists to let a consumer drop
+  theirs. A form whose only field is a `Combobox` is implicitly submitted by
+  Enter under HTML's rules, so an uncommitted query submitted an empty value. A
+  consumer that relied on Enter in a closed popup reaching its form is
+  unaffected; one that relied on it with the popup open must now press Escape
+  first.
+
+- Arrowing to the first option of a group scrolls that group's heading into
+  view rather than the option, so the heading is not left clipped above the
+  scrollport at the moment it is most needed.
+
+- `0.10.0` was packed twice under one number: the group heading's padding was
+  retuned after the tarball had already been handed to a consumer, so two
+  distinct `0.10.0` tarballs existed and the one that was verified is gone.
+  This release supersedes both. See `future.md` for the packing-provenance
+  remedy.
+
+## 0.10.0
+
+### Minor Changes
+
+- `Combobox` options may declare a `group` and a `description`, both optional
+  and both additive — every existing call site renders exactly as before, down
+  to the markup.
+
+  - `group` puts a run of consecutive options under a heading. The options prop
+    stays one flat ordered list, which is what keeps the keyboard model intact:
+    filtering, the active-option index, wrap-around, and scroll-into-view all
+    still work on that single list, and headings are siblings inside the
+    listbox rather than wrappers around the options. A heading is presentation,
+    not a choice — it carries no `role="option"`, arrow keys pass over it, and
+    a heading whose options are all filtered away is not rendered. The
+    component does not reorder, so interleaved groups repeat their heading, as
+    `<optgroup>` does; sort before passing if that is not wanted. A heading is
+    spaced asymmetrically — much more room above it than below — so that each
+    run reads as one block instead of the heading floating equidistant between
+    the group above and the group it names.
+  - `description` is secondary text beside the label, for the kind of
+    qualifier that has to read next to a name — a record's type, say. It is
+    distinct from `trailing`, which is right-aligned and monospaced because it
+    was built for GMT offsets, and an option may carry both.
+
+  Between `0.8.0` and this release, a `0.9.1` tarball circulated to a consumer
+  without a release note or a published version behind it. This version is
+  numbered past it so no consumer moves backwards.
+
+## 0.8.0
+
+### Minor Changes
+
+- `Switch` themes its thumb per state via a new optional
+  `--ssui-switch-thumb-checked` token (defaulting to `--ssui-switch-thumb`, so
+  existing consumers are unchanged). A single thumb color only works when the
+  checked track and the unchecked track sit on the same side of the lightness
+  scale; a product whose primary is near-white got a white thumb on a near-white
+  checked track, leaving the control unable to show on versus off.
+
+- Add the multi-select and disclosure primitives the settings kit was missing:
+
+  - `FieldGroup` — the group analogue of `FormField`: a `fieldset`/`legend`
+    wrapper with the same label/description/error typography and
+    `aria-describedby`/`aria-invalid` wiring. `FormField` can only label a single
+    control through `htmlFor`, so a set of controls answering one question (a
+    checkbox group, a radio group, a composite input) previously had no correct
+    labelling primitive.
+  - `Checkbox` — styled native checkbox that participates in `FormField` wiring
+    like the other controls.
+  - `CheckboxGroup` / `CheckboxGroupItem` — multi-select group whose options share
+    one form field name, so the submission arrives as repeated entries under that
+    name. The mirror image of `ChoiceCardGroup`, with the same bordered-target
+    presentation and support for controlled or uncontrolled selection.
+  - `Collapsible` / `CollapsibleTrigger` / `CollapsibleContent` — disclosure region
+    for keeping secondary detail (an edit form, an advanced section) out of the way
+    until it is asked for. The trigger carries `aria-expanded`/`aria-controls` and
+    supports `asChild` so a `Button` can be the trigger; the region stays mounted
+    and hidden with the `hidden` attribute, so `aria-controls` always resolves and
+    an open form's in-progress state survives a collapse.
+
+  The component gallery gains a "Form Fields And Groups" section covering these
+  alongside the existing `FormField`/`Select`/`Switch`/`ChoiceCardGroup` kit, plus
+  a "Collapsible" section.
+
 ## 0.7.0
 
 ### Minor Changes

package/dist/components/checkbox.d.ts

@@ -0,0 +1,51 @@
+import * as React from "react";
+export interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "type"> {
+}
+/**
+ * Styled native checkbox. Native on purpose: form participation, indeterminate
+ * support and platform semantics come from the browser, and only the box itself
+ * needs theming. Participates in `FormField` wiring like the other controls.
+ */
+export declare const Checkbox: React.ForwardRefExoticComponent<CheckboxProps & React.RefAttributes<HTMLInputElement>>;
+export interface CheckboxGroupProps extends Omit<React.FieldsetHTMLAttributes<HTMLFieldSetElement>, "onChange" | "defaultValue" | "children"> {
+    /** Group label, rendered as the fieldset's legend. */
+    legend: React.ReactNode;
+    /** Optional supporting copy shown under the legend. */
+    description?: React.ReactNode;
+    /** Error message; when set the group is marked invalid. */
+    error?: React.ReactNode;
+    /** Form field name shared by every option in the group. */
+    name?: string;
+    /** Controlled selection. */
+    value?: readonly string[];
+    /** Uncontrolled initial selection. */
+    defaultValue?: readonly string[];
+    onValueChange?: (value: string[]) => void;
+    /** Disables every option in the group. */
+    disabled?: boolean;
+    /** `CheckboxGroupItem`s. */
+    children: React.ReactNode;
+}
+/**
+ * Multi-select group: a `FieldGroup` whose options share one form field name, so
+ * the submission arrives as repeated entries under that name. The mirror image of
+ * `ChoiceCardGroup`, which is the single-select form of the same pattern.
+ *
+ * Selection is tracked in context rather than left to the DOM so the group can be
+ * driven as a controlled component, but the underlying inputs stay native — an
+ * uncontrolled group still submits correctly with no JavaScript involvement.
+ */
+export declare function CheckboxGroup({ legend, description, error, name, value, defaultValue, onValueChange, disabled, className, children, ...props }: CheckboxGroupProps): import("react/jsx-runtime").JSX.Element;
+export interface CheckboxGroupItemProps extends Omit<React.LabelHTMLAttributes<HTMLLabelElement>, "title"> {
+    /** Value submitted when this option is checked. */
+    value: string;
+    /** Option label. */
+    label: React.ReactNode;
+    disabled?: boolean;
+}
+/**
+ * One option inside a `CheckboxGroup`: a bordered label wrapping a native
+ * checkbox. Bordered rather than bare so a row of options reads as a set of
+ * targets, and so the whole chip is clickable rather than just the box.
+ */
+export declare function CheckboxGroupItem({ value, label, disabled, className, ...props }: CheckboxGroupItemProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/checkbox.js

@@ -0,0 +1,61 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+import { FieldGroup } from "./field-group.js";
+import { useFormFieldProps } from "./form-field.js";
+/**
+ * Styled native checkbox. Native on purpose: form participation, indeterminate
+ * support and platform semantics come from the browser, and only the box itself
+ * needs theming. Participates in `FormField` wiring like the other controls.
+ */
+export const Checkbox = React.forwardRef(({ className, ...props }, ref) => (_jsx("input", { ref: ref, type: "checkbox", className: cn("size-4 shrink-0 cursor-pointer rounded-[calc(var(--ssui-radius)/2)] border border-[color:var(--ssui-border)] accent-[color:var(--ssui-primary)] transition-shadow 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:opacity-50", className), ...useFormFieldProps(props) })));
+Checkbox.displayName = "Checkbox";
+const CheckboxGroupContext = React.createContext(null);
+/**
+ * Multi-select group: a `FieldGroup` whose options share one form field name, so
+ * the submission arrives as repeated entries under that name. The mirror image of
+ * `ChoiceCardGroup`, which is the single-select form of the same pattern.
+ *
+ * Selection is tracked in context rather than left to the DOM so the group can be
+ * driven as a controlled component, but the underlying inputs stay native — an
+ * uncontrolled group still submits correctly with no JavaScript involvement.
+ */
+export function CheckboxGroup({ legend, description, error, name, value, defaultValue, onValueChange, disabled, className, children, ...props }) {
+    const generatedName = React.useId();
+    const [uncontrolledValue, setUncontrolledValue] = React.useState(defaultValue ?? []);
+    const selected = value ?? uncontrolledValue;
+    const contextValue = React.useMemo(() => {
+        const selectedSet = new Set(selected);
+        return {
+            name: name ?? generatedName,
+            disabled,
+            isSelected: (option) => selectedSet.has(option),
+            toggle: (option) => {
+                const next = selectedSet.has(option)
+                    ? selected.filter((entry) => entry !== option)
+                    : [...selected, option];
+                if (value === undefined)
+                    setUncontrolledValue(next);
+                onValueChange?.(next);
+            },
+        };
+    }, [disabled, generatedName, name, onValueChange, selected, value]);
+    return (_jsx(FieldGroup, { description: description, error: error, legend: legend, className: className, ...props, children: _jsx("div", { className: "flex flex-wrap gap-2 pt-0.5", children: _jsx(CheckboxGroupContext.Provider, { value: contextValue, children: children }) }) }));
+}
+/**
+ * One option inside a `CheckboxGroup`: a bordered label wrapping a native
+ * checkbox. Bordered rather than bare so a row of options reads as a set of
+ * targets, and so the whole chip is clickable rather than just the box.
+ */
+export function CheckboxGroupItem({ value, label, disabled, className, ...props }) {
+    const group = React.useContext(CheckboxGroupContext);
+    if (!group) {
+        throw new Error("CheckboxGroupItem must be rendered inside a CheckboxGroup");
+    }
+    const checked = group.isSelected(value);
+    const isDisabled = disabled ?? group.disabled;
+    return (_jsxs("label", { className: cn("inline-flex cursor-pointer items-center gap-2 rounded-[var(--ssui-radius)] border px-2.5 py-1.5 text-sm transition-colors has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-[color:var(--ssui-focus-ring)]", checked
+            ? "border-[color:var(--ssui-border-strong)] bg-[color:var(--ssui-surface-muted)] text-[color:var(--ssui-text)]"
+            : "border-[color:var(--ssui-border)] text-[color:var(--ssui-text-muted)] hover:bg-[color:var(--ssui-overlay-hover)]", isDisabled && "cursor-not-allowed opacity-50", className), ...props, children: [_jsx(Checkbox, { checked: checked, disabled: isDisabled, name: group.name, onChange: () => group.toggle(value), value: value }), label] }));
+}

package/dist/components/collapsible.d.ts

@@ -0,0 +1,37 @@
+import * as React from "react";
+export interface CollapsibleProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onToggle"> {
+    /** Controlled open state. */
+    open?: boolean;
+    /** Uncontrolled initial open state. */
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Prevents the trigger from toggling the region. */
+    disabled?: boolean;
+}
+/**
+ * Disclosure region: a trigger that shows and hides a block of content, used to
+ * keep secondary detail — an edit form, an advanced section — out of the way
+ * until it is asked for.
+ *
+ * The content stays mounted and is hidden with the `hidden` attribute rather than
+ * unmounted, so `aria-controls` always resolves to a real element and an open
+ * form's in-progress state survives a collapse.
+ */
+export declare function Collapsible({ open, defaultOpen, onOpenChange, disabled, className, children, ...props }: CollapsibleProps): import("react/jsx-runtime").JSX.Element;
+export interface CollapsibleTriggerProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Render the consumer's own element (e.g. a `Button`) as the trigger. */
+    asChild?: boolean;
+    /** Children rendered while the region is open, if it differs from the closed label. */
+    openChildren?: React.ReactNode;
+}
+/**
+ * Toggles the enclosing `Collapsible`. Always a real `button` (or the consumer's
+ * element via `asChild`) carrying `aria-expanded`/`aria-controls`, so the
+ * relationship between control and region is announced rather than implied by
+ * position.
+ */
+export declare const CollapsibleTrigger: React.ForwardRefExoticComponent<CollapsibleTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+export interface CollapsibleContentProps extends React.HTMLAttributes<HTMLDivElement> {
+}
+/** The region shown and hidden by `CollapsibleTrigger`. */
+export declare function CollapsibleContent({ className, children, ...props }: CollapsibleContentProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/collapsible.js

@@ -0,0 +1,60 @@
+"use client";
+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 CollapsibleContext = React.createContext(null);
+function useCollapsibleContext(component) {
+    const context = React.useContext(CollapsibleContext);
+    if (!context) {
+        throw new Error(`${component} must be rendered inside a Collapsible`);
+    }
+    return context;
+}
+/**
+ * Disclosure region: a trigger that shows and hides a block of content, used to
+ * keep secondary detail — an edit form, an advanced section — out of the way
+ * until it is asked for.
+ *
+ * The content stays mounted and is hidden with the `hidden` attribute rather than
+ * unmounted, so `aria-controls` always resolves to a real element and an open
+ * form's in-progress state survives a collapse.
+ */
+export function Collapsible({ open, defaultOpen = false, onOpenChange, disabled, className, children, ...props }) {
+    const contentId = React.useId();
+    const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen);
+    const isOpen = open ?? uncontrolledOpen;
+    const contextValue = React.useMemo(() => ({
+        open: isOpen,
+        contentId,
+        disabled,
+        setOpen: (next) => {
+            if (open === undefined)
+                setUncontrolledOpen(next);
+            onOpenChange?.(next);
+        },
+    }), [contentId, disabled, isOpen, onOpenChange, open]);
+    return (_jsx("div", { className: cn(className), "data-state": isOpen ? "open" : "closed", ...props, children: _jsx(CollapsibleContext.Provider, { value: contextValue, children: children }) }));
+}
+/**
+ * Toggles the enclosing `Collapsible`. Always a real `button` (or the consumer's
+ * element via `asChild`) carrying `aria-expanded`/`aria-controls`, so the
+ * relationship between control and region is announced rather than implied by
+ * position.
+ */
+export const CollapsibleTrigger = React.forwardRef(({ asChild = false, children, openChildren, onClick, ...props }, ref) => {
+    const { open, setOpen, contentId, disabled } = useCollapsibleContext("CollapsibleTrigger");
+    const Comp = asChild ? Slot : "button";
+    return (_jsx(Comp, { ref: ref, "aria-controls": contentId, "aria-expanded": open, "data-state": open ? "open" : "closed", disabled: disabled, onClick: (event) => {
+            onClick?.(event);
+            if (event.defaultPrevented || disabled)
+                return;
+            setOpen(!open);
+        }, type: asChild ? undefined : "button", ...props, children: open && openChildren !== undefined ? openChildren : children }));
+});
+CollapsibleTrigger.displayName = "CollapsibleTrigger";
+/** The region shown and hidden by `CollapsibleTrigger`. */
+export function CollapsibleContent({ className, children, ...props }) {
+    const { open, contentId } = useCollapsibleContext("CollapsibleContent");
+    return (_jsx("div", { className: cn(className), "data-state": open ? "open" : "closed", hidden: !open, id: contentId, ...props, children: children }));
+}

package/dist/components/combobox.d.ts

@@ -4,6 +4,23 @@ export interface ComboboxOption {
     label: string;
     /** Optional trailing content (e.g. a GMT offset) shown right-aligned. */
     trailing?: React.ReactNode;
+    /**
+     * Optional secondary text shown next to the label, in the reading order a
+     * subtitle would take. Distinct from `trailing`, which is right-aligned and
+     * monospaced; an option may carry both.
+     */
+    description?: React.ReactNode;
+    /**
+     * Optional heading this option sits under. Consecutive options declaring the
+     * same group collapse into one heading, exactly as `<optgroup>` does — the
+     * component never reorders, so interleaved groups (`A, B, A`) render three
+     * headings, not two. Sort the list before passing it if that is not wanted.
+     *
+     * Grouped and ungrouped options may be mixed: an option declaring no group
+     * ends the run above it and renders outside every group, the way an
+     * `<option>` following an `</optgroup>` sits outside that group.
+     */
+    group?: string;
 }
 export interface ComboboxProps {
     /** Full option list; the component filters it against the typed query. */

package/dist/components/combobox.js

@@ -55,9 +55,26 @@ export const Combobox = React.forwardRef(({ options, value, onValueChange, filte
                 : filtered.length - 1
             : (activeIndex + delta + filtered.length) % filtered.length;
         setActiveIndex(next);
-        listRef.current
-            ?.querySelector(`[data-index="${next}"]`)
-            ?.scrollIntoView({ block: "nearest" });
+        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" });
     }
     function handleKeyDown(event) {
         if (event.key === "ArrowDown" || event.key === "ArrowUp") {
@@ -70,10 +87,18 @@ export const Combobox = React.forwardRef(({ options, value, onValueChange, filte
             return;
         }
         if (event.key === "Enter") {
-            if (open && activeOption) {
-                event.preventDefault();
+            // An open popup owns Enter, whether or not anything is highlighted.
+            // Committing when there is an active option is the obvious half; the
+            // other half is swallowing the key when there is not, so that Enter on
+            // an uncommitted query cannot reach the form behind the control. A
+            // consumer whose only field is this combobox has no submit button to
+            // absorb it, and HTML would otherwise implicitly submit the form with
+            // whatever the hidden input last held.
+            if (!open)
+                return;
+            event.preventDefault();
+            if (activeOption)
                 commit(activeOption);
-            }
             return;
         }
         if (event.key === "Escape") {
@@ -83,6 +108,24 @@ 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));
+    }
     return (_jsxs("div", { className: cn("relative", className), onBlur: (event) => {
             if (!event.currentTarget.contains(event.relatedTarget)) {
                 close();
@@ -95,9 +138,15 @@ export const Combobox = React.forwardRef(({ options, value, onValueChange, filte
                     setQuery(null);
                     openList();
                     document.getElementById(id)?.focus();
-                }, tabIndex: -1, type: "button", children: _jsx(ChevronDown, { "aria-hidden": "true", className: "size-4" }) }), name ? _jsx("input", { name: name, type: "hidden", value: value ?? "" }) : null, open ? (_jsx("div", { className: "absolute z-50 mt-1 max-h-64 w-full overflow-y-auto rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border)] bg-[color:var(--ssui-surface-elevated)] p-1 shadow-[var(--ssui-shadow-md)]", id: listboxId, ref: listRef, role: "listbox", children: filtered.length > 0 ? (filtered.map((option, index) => (_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: [_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)))) : (_jsx("div", { className: "px-2 py-1.5 text-sm text-[color:var(--ssui-text-subtle)]", children: emptyMessage })) })) : null] }));
+                }, tabIndex: -1, type: "button", children: _jsx(ChevronDown, { "aria-hidden": "true", className: "size-4" }) }), name ? _jsx("input", { name: name, type: "hidden", value: value ?? "" }) : null, open ? (_jsx("div", { className: "absolute z-50 mt-1 max-h-64 w-full overflow-y-auto rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border)] bg-[color:var(--ssui-surface-elevated)] p-1 shadow-[var(--ssui-shadow-md)]", id: listboxId, ref: listRef, role: "listbox", children: rows.length > 0 ? (rows.map((row, rowIndex) => row.kind === "option" ? (renderOption(row.entry)) : (
+                // A run is wrapped in `role="group"` labelled by its heading —
+                // the APG grouped-listbox shape. Without it the grouping is
+                // conveyed to sighted users only: a roleless heading is not in
+                // the listbox's content model, so a screen-reader user hears a
+                // flat list of options and never learns which kind each is.
+                // The heading takes `role="presentation"` so it stays out of
+                // that content model while `aria-labelledby` still names the
+                // group from its text.
+                _jsxs("div", { "aria-labelledby": `${id}-group-${rowIndex}`, role: "group", children: [_jsx("div", { className: cn("px-2 pb-0.5 pt-4 text-xs font-medium uppercase tracking-wide text-[color:var(--ssui-text-subtle)]", rowIndex === 0 && "pt-1"), id: `${id}-group-${rowIndex}`, role: "presentation", children: row.group }), row.entries.map(renderOption)] }, `group-${rowIndex}`)))) : (_jsx("div", { className: "px-2 py-1.5 text-sm text-[color:var(--ssui-text-subtle)]", children: emptyMessage })) })) : null] }));
 });
 Combobox.displayName = "Combobox";

package/dist/components/field-group.d.ts

@@ -0,0 +1,22 @@
+import * as React from "react";
+export interface FieldGroupProps extends Omit<React.FieldsetHTMLAttributes<HTMLFieldSetElement>, "children"> {
+    /** Group label, rendered as the fieldset's legend. */
+    legend: React.ReactNode;
+    /** Optional supporting copy shown under the legend. */
+    description?: React.ReactNode;
+    /** Error message; when set the group is marked invalid. */
+    error?: React.ReactNode;
+    /** The controls belonging to this group. */
+    children: React.ReactNode;
+}
+/**
+ * The group analogue of `FormField`: a `fieldset`/`legend` wrapper with the same
+ * label/description/error typography, for a set of controls that answer one
+ * question together (checkbox groups, radio groups, composite inputs).
+ *
+ * `FormField` is wrong for these — its `label`/`htmlFor` pair can only point at a
+ * single control, so with several controls the label either names just one of them
+ * or names nothing. `legend` labels the whole set, which is what a screen reader
+ * needs to announce before reading the options.
+ */
+export declare function FieldGroup({ legend, description, error, className, children, ...props }: FieldGroupProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/field-group.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+/**
+ * The group analogue of `FormField`: a `fieldset`/`legend` wrapper with the same
+ * label/description/error typography, for a set of controls that answer one
+ * question together (checkbox groups, radio groups, composite inputs).
+ *
+ * `FormField` is wrong for these — its `label`/`htmlFor` pair can only point at a
+ * single control, so with several controls the label either names just one of them
+ * or names nothing. `legend` labels the whole set, which is what a screen reader
+ * needs to announce before reading the options.
+ */
+export function FieldGroup({ legend, description, error, className, children, ...props }) {
+    const id = React.useId();
+    const descriptionId = `${id}-description`;
+    const errorId = `${id}-error`;
+    const describedBy = [description ? descriptionId : null, error ? errorId : null]
+        .filter(Boolean)
+        .join(" ") || undefined;
+    return (_jsxs("fieldset", { "aria-describedby": describedBy, "aria-invalid": error ? true : undefined, className: cn("min-w-0 space-y-1.5", className), ...props, children: [_jsx("legend", { className: "text-sm font-medium text-[color:var(--ssui-text)]", children: legend }), description ? (_jsx("p", { className: "text-xs text-[color:var(--ssui-text-muted)]", id: descriptionId, children: description })) : null, children, error ? (_jsx("p", { className: "text-xs text-[color:var(--ssui-destructive)]", id: errorId, children: error })) : null] }));
+}

package/dist/components/index.d.ts

@@ -4,9 +4,12 @@ export * from "./avatar.js";
 export * from "./badge.js";
 export * from "./brand-icons.js";
 export * from "./button.js";
+export * from "./checkbox.js";
 export * from "./choice-card.js";
+export * from "./collapsible.js";
 export * from "./combobox.js";
 export * from "./confirm-dialog.js";
+export * from "./field-group.js";
 export * from "./form-field.js";
 export * from "./copy-field.js";
 export * from "./dialog.js";
@@ -23,6 +26,7 @@ export * from "./overflow-menu.js";
 export * from "./page-header.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.js";

package/dist/components/index.js

@@ -4,9 +4,12 @@ export * from "./avatar.js";
 export * from "./badge.js";
 export * from "./brand-icons.js";
 export * from "./button.js";
+export * from "./checkbox.js";
 export * from "./choice-card.js";
+export * from "./collapsible.js";
 export * from "./combobox.js";
 export * from "./confirm-dialog.js";
+export * from "./field-group.js";
 export * from "./form-field.js";
 export * from "./copy-field.js";
 export * from "./dialog.js";
@@ -23,6 +26,7 @@ export * from "./overflow-menu.js";
 export * from "./page-header.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.js";

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

@@ -0,0 +1,95 @@
+import * as React from "react";
+export interface RoleMenuOption {
+    value: string;
+    label: string;
+    /** One line on what the role grants. Shown in the popup, never on the trigger. */
+    description: string;
+    /** Optional leading icon, sized by the caller (16px reads correctly here). */
+    icon?: React.ReactNode;
+    /**
+     * Withholds this one option while leaving the rest selectable, and says why —
+     * a workspace's last admin, a plan the account cannot downgrade to. The reason
+     * is shown in place of the description.
+     *
+     * Presence is what withholds: there is no separate `disabled` flag, because an
+     * option withheld without an explanation is a dead row that answers none of
+     * the question the reader now has. Pass `undefined` to leave it selectable, so
+     * a computed case stays one expression:
+     * `unavailableReason: isLastAdmin ? "…" : undefined`.
+     */
+    unavailableReason?: string;
+}
+export interface RoleMenuDestructiveItem {
+    label: string;
+    onSelect: () => void | Promise<void>;
+    icon?: React.ReactNode;
+    disabled?: boolean;
+}
+export interface RoleMenuProps {
+    options: ReadonlyArray<RoleMenuOption>;
+    /** 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>;
+    /** Heading above the options, e.g. "Select role". Omitted when absent. */
+    heading?: React.ReactNode;
+    /** Rendered below the options, separated — typically a documentation link. */
+    footer?: React.ReactNode;
+    /** Rendered last, separated, styled as destructive. Typically "Remove from workspace". */
+    destructiveItem?: RoleMenuDestructiveItem;
+    /**
+     * Submits the selected value with the surrounding form through a hidden input.
+     * Omit it in a list that applies on selection: a Radix menu is not a form
+     * control, and an unconditional hidden input would litter every such row.
+     */
+    name?: string;
+    /** Disables the whole control. To withhold one option, use its `unavailableReason`. */
+    disabled?: boolean;
+    /**
+     * Which edge of the trigger the popup aligns to. Defaults to `"start"`; a
+     * right-aligned trigger (a table's last column) wants `"end"` so the popup
+     * opens inward rather than relying on collision detection to rescue it.
+     */
+    align?: "start" | "center" | "end";
+    /** Trigger id. Supplied by an enclosing `FormField` when there is one. */
+    id?: string;
+    /**
+     * Names the trigger's purpose, e.g. `"Role for Ada Lovelace"` in a member
+     * list. The selected label is appended to whatever is passed — the accessible
+     * name has to contain the trigger's visible text for voice control (WCAG
+     * 2.5.3), and a row's own name has to say which row it belongs to. Defaults to
+     * `"Change role (current: …)"`, and is dropped entirely inside a `FormField`,
+     * whose label already names the control.
+     */
+    "aria-label"?: string;
+    "aria-describedby"?: string;
+    "aria-invalid"?: React.AriaAttributes["aria-invalid"];
+    /** Open the menu by default (uncontrolled). Useful for tests and controlled-open consumers. */
+    defaultOpen?: boolean;
+    /** Extra classes for the trigger. */
+    className?: string;
+}
+/**
+ * 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.
+ *
+ * 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
+ * the checkmark as a purely visual cue. The check is drawn here rather than by
+ * Radix's `ItemIndicator` because it sits opposite a two-line label, where the
+ * indicator's leading placement fights the description.
+ *
+ * The component owns no invariant. Which option is unavailable and why is the
+ * consumer's to say, and a consumer that renders a stale `unavailableReason` has
+ * a display bug rather than a hole — the server it submits to is expected to
+ * refuse the change on its own.
+ */
+export declare function RoleMenu({ options, value, onValueChange, heading, footer, destructiveItem, name, disabled, align, defaultOpen, className, ...ariaProps }: RoleMenuProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace RoleMenu {
+    var displayName: string;
+}

package/dist/components/role-menu.js

@@ -0,0 +1,52 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
+import { Check, ChevronDown } from "lucide-react";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuSeparator, DropdownMenuTrigger, } from "./dropdown-menu.js";
+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.
+ *
+ * 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
+ * the checkmark as a purely visual cue. The check is drawn here rather than by
+ * Radix's `ItemIndicator` because it sits opposite a two-line label, where the
+ * indicator's leading placement fights the description.
+ *
+ * The component owns no invariant. Which option is unavailable and why is the
+ * consumer's to say, and a consumer that renders a stale `unavailableReason` has
+ * a display bug rather than a hole — the server it submits to is expected to
+ * refuse the change on its own.
+ */
+export function RoleMenu({ options, value, onValueChange, heading, footer, destructiveItem, name, disabled, align = "start", defaultOpen, className, ...ariaProps }) {
+    const selected = options.find((option) => option.value === value);
+    const selectedLabel = selected?.label ?? value;
+    const headingId = React.useId();
+    // An enclosing `FormField` owns the trigger's id and error wiring, the same
+    // way it owns `Input`'s and `Combobox`'s — without this the field's label
+    // points at an id no element carries and its error is never announced.
+    const field = useFormField();
+    const { "aria-label": ariaLabel, ...fieldProps } = useFormFieldProps(ariaProps);
+    // A row of ten triggers all named "Member" says nothing about what they do or
+    // whose role they change, so the name carries purpose and current value —
+    // `WorkspaceSwitcher`'s reasoning. A `FormField`'s visible label does that job
+    // better, and an `aria-label` would override it, so inside one there is none.
+    const triggerLabel = ariaLabel
+        ? `${ariaLabel} (current: ${selectedLabel})`
+        : field
+            ? undefined
+            : `Change role (current: ${selectedLabel})`;
+    return (_jsxs(_Fragment, { children: [name ? _jsx("input", { disabled: disabled, name: name, type: "hidden", value: value }) : null, _jsxs(DropdownMenu, { defaultOpen: defaultOpen, children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsxs("button", { ...fieldProps, "aria-label": triggerLabel, className: cn("inline-flex h-8 items-center gap-1.5 rounded-[var(--ssui-radius-sm)] px-2 text-sm text-[color:var(--ssui-text)] transition-colors", "hover:bg-[color:var(--ssui-overlay-hover)] 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:pointer-events-none disabled:opacity-70", className), disabled: disabled, type: "button", children: [selectedLabel, _jsx(ChevronDown, { "aria-hidden": "true", className: "size-4 text-[color:var(--ssui-text-subtle)]" })] }) }), _jsxs(DropdownMenuContent, { align: align, className: "w-72 p-1.5", collisionPadding: 8, children: [heading ? (_jsx(DropdownMenuLabel, { className: "px-2 py-1", id: headingId, children: heading })) : null, _jsx(DropdownMenuRadioGroup, { "aria-labelledby": heading ? headingId : undefined, onValueChange: (next) => {
+                                    if (next !== value)
+                                        void onValueChange(next);
+                                }, value: value, children: options.map((option) => (_jsxs(DropdownMenuPrimitive.RadioItem, { className: cn("relative flex cursor-default select-none items-start gap-2.5 rounded-[var(--ssui-radius-sm)] px-2 py-2 text-sm outline-none transition-colors", "focus:bg-[color:var(--ssui-overlay-hover)] data-[highlighted]:bg-[color:var(--ssui-overlay-hover)]", "data-[disabled]:pointer-events-none data-[disabled]:opacity-50"), disabled: option.unavailableReason !== undefined, value: option.value, children: [option.icon ? (_jsx("span", { "aria-hidden": "true", className: "mt-0.5 shrink-0 text-[color:var(--ssui-text-subtle)]", children: option.icon })) : null, _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block font-medium", children: option.label }), _jsx("span", { className: "mt-0.5 block text-xs leading-snug text-[color:var(--ssui-text-muted)]", children: option.unavailableReason ?? option.description })] }), option.value === value ? (_jsx(Check, { "aria-hidden": "true", className: "mt-0.5 size-4 shrink-0 text-[color:var(--ssui-text)]" })) : null] }, option.value))) }), destructiveItem ? (_jsxs(_Fragment, { children: [_jsx(DropdownMenuSeparator, {}), _jsxs(DropdownMenuItem, { className: "gap-2.5 px-2 py-2 text-[color:var(--ssui-destructive)] focus:text-[color:var(--ssui-destructive)] data-[highlighted]:text-[color:var(--ssui-destructive)]", disabled: destructiveItem.disabled, onSelect: () => void destructiveItem.onSelect(), children: [destructiveItem.icon ? (_jsx("span", { "aria-hidden": "true", className: "shrink-0", children: destructiveItem.icon })) : null, destructiveItem.label] })] })) : null, footer ? (_jsxs(_Fragment, { children: [_jsx(DropdownMenuSeparator, {}), _jsx("div", { className: "px-2 py-1.5 text-xs text-[color:var(--ssui-text-muted)]", children: footer })] })) : null] })] })] }));
+}
+RoleMenu.displayName = "RoleMenu";

package/dist/components/switch.js

@@ -23,6 +23,13 @@ export const Switch = React.forwardRef(({ checked, defaultChecked = false, onChe
     }
     return (_jsxs(_Fragment, { children: [_jsx("button", { ref: ref, type: "button", role: "switch", "aria-checked": isChecked, "data-state": isChecked ? "checked" : "unchecked", disabled: disabled, onClick: handleClick, className: cn("inline-flex h-6 w-10 shrink-0 items-center rounded-full border border-transparent p-0.5 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ssui-focus-ring)] focus-visible:ring-offset-2 focus-visible:ring-offset-[color:var(--ssui-bg)] disabled:cursor-not-allowed disabled:opacity-50", isChecked
                     ? "bg-[color:var(--ssui-switch-track-checked,var(--ssui-primary))]"
-                    : "bg-[color:var(--ssui-switch-track,var(--ssui-border))]", className), ...useFormFieldProps(props), children: _jsx("span", { "aria-hidden": "true", className: cn("block size-5 rounded-full bg-[color:var(--ssui-switch-thumb,#ffffff)] shadow-sm transition-transform", isChecked ? "translate-x-4" : "translate-x-0") }) }), name ? (_jsx("input", { type: "checkbox", "aria-hidden": "true", tabIndex: -1, className: "sr-only", checked: isChecked, disabled: disabled, name: name, value: value, readOnly: true })) : null] }));
+                    : "bg-[color:var(--ssui-switch-track,var(--ssui-border))]", className), ...useFormFieldProps(props), children: _jsx("span", { "aria-hidden": "true", className: cn("block size-5 rounded-full shadow-sm transition-transform", 
+                    // The thumb is themed per state. A single thumb color only works when the
+                    // checked track (the primary) and the unchecked track sit on the same side
+                    // of the lightness scale; a product whose primary is near-white gets a white
+                    // thumb on a near-white track and the control stops reading as on or off.
+                    isChecked
+                        ? "bg-[color:var(--ssui-switch-thumb-checked,var(--ssui-switch-thumb,#ffffff))] translate-x-4"
+                        : "bg-[color:var(--ssui-switch-thumb,#ffffff)] translate-x-0") }) }), name ? (_jsx("input", { type: "checkbox", "aria-hidden": "true", tabIndex: -1, className: "sr-only", checked: isChecked, disabled: disabled, name: name, value: value, readOnly: true })) : null] }));
 });
 Switch.displayName = "Switch";

package/dist/styles/index.css

@@ -23,6 +23,9 @@
   --ssui-switch-track: var(--ssui-border);
   --ssui-switch-track-checked: var(--ssui-primary);
   --ssui-switch-thumb: #ffffff;
+  /* Thumb color while checked. Defaults to the unchecked thumb; override when the
+     checked track (--ssui-switch-track-checked) is too light for a white thumb. */
+  --ssui-switch-thumb-checked: #ffffff;
   --ssui-radius-sm: 0.25rem;
   --ssui-radius: 0.375rem;
   --ssui-radius-lg: 0.5rem;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardreach/saas-ui",
-  "version": "0.7.0",
+  "version": "0.10.2",
   "description": "Brand-neutral React UI primitives and SaaS app patterns for ForwardReach-owned business applications.",
   "type": "module",
   "private": false,