@forwardreach/saas-ui 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 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/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.8.0",
   "description": "Brand-neutral React UI primitives and SaaS app patterns for ForwardReach-owned business applications.",
   "type": "module",
   "private": false,