@forwardreach/saas-ui 0.4.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## 0.7.0
+
+### Minor Changes
+
+- Add the settings shell and form primitive kit:
+
+  - `SettingsLayout` / `SettingsNav` — centered max-width settings shell with a
+    grouped, icon-capable sidebar nav (horizontal-scroll row on small screens).
+    Router-agnostic: active state comes from `activeHref` or an `isActive`
+    predicate and links render through an injectable `linkComponent`.
+  - `FormField` — label/description/control/error wrapper that generates and
+    threads `id`/`aria-describedby`/`aria-invalid` to package controls via
+    context; `Input`, `Textarea`, `Select`, `Switch`, and `Combobox` participate.
+  - `Select` — native select styled to match `Input`, with chevron.
+  - `Switch` — `role="switch"` toggle themed by new optional
+    `--ssui-switch-track` / `--ssui-switch-track-checked` / `--ssui-switch-thumb`
+    tokens (neutral fallbacks); optional form participation via `name`.
+  - `ChoiceCardGroup` / `ChoiceCard` — radio group rendered as selectable
+    bordered cards over native radios.
+  - `Combobox` — filterable single-select with WAI-ARIA combobox semantics,
+    wrap-around active-option keyboard navigation, and Enter-commit of the
+    highlighted option.
+  - `TimeZoneField` — auto/fixed time-zone composite (detected zone shown in
+    the auto card, zone combobox with offset-aware search in fixed mode) that
+    submits `timeZoneMode`/`timeZone`/`browserTimeZone` hidden inputs.
+  - Time-zone utilities (`timeZoneOptions`, `formatTimeZoneOffset`,
+    `detectBrowserTimeZone`, `COMMON_TIME_ZONES`) exported for server-side reuse.
+
+## 0.6.0
+
+### Minor Changes
+
+- Add `RailToggle` (icon-only rail collapse/expand toggle with tooltip + shortcut hint, presentational) and polish `WorkspaceSwitcher`/`AccountMenu` popup presentation: 10px side offset, panel min-width tied to the trigger width, and trigger chevrons that rotate while the menu is open.
+
+- Add `AccountMenu` and `WorkspaceSwitcher` — the shared app-shell menu pair.
+
+  `AccountMenu` is the bottom-left identity menu: a full-width account card
+  trigger (avatar, name, email, chevron-up; avatar-only with a name tooltip when
+  `collapsed`) opening a Radix menu with a fixed anatomy — identity header,
+  optional theme selector row, consumer-provided items (`AccountMenuItem`), then
+  a separated Sign out. The theme row is a segmented `menuitemradio` control
+  (Sun/Moon/Monitor) that supports both two-option (light/dark) and three-option
+  (light/dark/system) configurations and keeps the menu open on selection.
+
+  `WorkspaceSwitcher` is the top-left workspace context menu: a brand badge +
+  active workspace name + chevron-down trigger (badge-only with a tooltip when
+  `collapsed`) opening a list of workspaces with the active row checked and not
+  re-selectable, plus an optional separated "New workspace" action. Selection is
+  callback-based (`onSelect(id)`).
+
+  Both components support the collapsed icon-rail state (menus open to the
+  right) and wrap their tooltips in a local `TooltipProvider`, so consumers need
+  no extra setup.
+
+## 0.5.0
+
+### Minor Changes
+
+- 523e143: Add `OverflowMenu` — a "⋯" icon-button that opens a dropdown of low-frequency,
+  whole-object actions, composed from the existing Radix `DropdownMenu` primitives.
+  Panel contents are composed with the exported `OverflowMenuItem` and
+  `OverflowMenuSeparator` aliases.
+
+  Menu-item highlight (hover/keyboard) now uses the translucent
+  `--ssui-overlay-hover` token instead of `--ssui-surface-muted`, and also styles
+  Radix's `data-highlighted` state. Solid `surface-muted` was invisible on themes
+  where it matches `surface-elevated` (the panel background); a translucent
+  overlay reads on any surface.
+
+  `DropdownMenuContent` (and `OverflowMenu`) also accept a new `portal` prop.
+  It defaults to `true`, preserving today's portal-to-`document.body` behavior;
+  pass `false` to render the panel inline next to the trigger, which keeps it
+  inside the trigger's DOM subtree — needed when the menu lives in a surface that
+  tracks focus, such as a click-to-edit editor that persists on blur.
+
 ## 0.4.0
 
 ### Minor Changes

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

@@ -0,0 +1,42 @@
+import * as React from "react";
+export type AccountMenuThemeValue = "light" | "dark" | "system";
+export interface AccountMenuTheme {
+    /** Currently active theme. */
+    value: AccountMenuThemeValue;
+    /** Which options to offer. Defaults to all three (light/dark/system). */
+    options?: ReadonlyArray<AccountMenuThemeValue>;
+    onChange: (value: AccountMenuThemeValue) => void;
+}
+export interface AccountMenuProps {
+    name: string;
+    email?: string;
+    /** Avatar image URL; initials fall back from `name`. */
+    image?: string | null;
+    /** Icon-only rail state: avatar-only trigger with a name tooltip, menu opens right. */
+    collapsed?: boolean;
+    /** Omit to hide the theme row entirely. */
+    theme?: AccountMenuTheme;
+    /** Label for the theme row. Defaults to "Theme". */
+    themeLabel?: string;
+    /**
+     * Consumer menu entries (e.g. a Settings link), rendered between the theme
+     * row and the separated Sign out item. Use `AccountMenuItem`s.
+     */
+    children?: React.ReactNode;
+    onSignOut: () => void | Promise<void>;
+    /** Defaults to "Sign out". */
+    signOutLabel?: string;
+    /** Open the menu by default (uncontrolled). Mainly useful in tests. */
+    defaultOpen?: boolean;
+    /** Extra classes for the trigger card. */
+    className?: string;
+}
+/**
+ * Bottom-left identity menu for the app shell: a full-width account card
+ * (avatar, name, email, chevron-up) opening a menu with a fixed anatomy —
+ * identity header, optional theme selector row, consumer items, then a
+ * separated Sign out. Workspace switching deliberately does not belong here;
+ * that's the top-left `WorkspaceSwitcher`.
+ */
+export declare function AccountMenu({ name, email, image, collapsed, theme, themeLabel, children, onSignOut, signOutLabel, defaultOpen, className, }: AccountMenuProps): import("react/jsx-runtime").JSX.Element;
+export { DropdownMenuItem as AccountMenuItem, DropdownMenuSeparator as AccountMenuSeparator, } from "./dropdown-menu.js";

package/dist/components/account-menu.js

@@ -0,0 +1,41 @@
+"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 { ChevronUp, LogOut, Monitor, Moon, Sun } from "lucide-react";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+import { Avatar } from "./avatar.js";
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuSeparator, DropdownMenuTrigger, } from "./dropdown-menu.js";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./tooltip.js";
+const THEME_OPTION_META = {
+    light: { icon: Sun, label: "Light" },
+    dark: { icon: Moon, label: "Dark" },
+    system: { icon: Monitor, label: "System" },
+};
+const ALL_THEME_OPTIONS = ["light", "dark", "system"];
+/**
+ * Bottom-left identity menu for the app shell: a full-width account card
+ * (avatar, name, email, chevron-up) opening a menu with a fixed anatomy —
+ * identity header, optional theme selector row, consumer items, then a
+ * separated Sign out. Workspace switching deliberately does not belong here;
+ * that's the top-left `WorkspaceSwitcher`.
+ */
+export function AccountMenu({ name, email, image, collapsed = false, theme, themeLabel = "Theme", children, onSignOut, signOutLabel = "Sign out", defaultOpen, className, }) {
+    const themeOptions = theme?.options ?? ALL_THEME_OPTIONS;
+    // Mirror open state for the chevron cue: the trigger's data-state is
+    // unreliable here because TooltipTrigger's own data-state wins the
+    // asChild prop merge over DropdownMenuTrigger's.
+    const [open, setOpen] = React.useState(defaultOpen ?? false);
+    return (_jsxs(DropdownMenu, { open: open, onOpenChange: setOpen, children: [_jsx(TooltipProvider, { delayDuration: 300, children: _jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx(DropdownMenuTrigger, { asChild: true, children: _jsxs("button", { type: "button", "aria-label": collapsed ? name : "Account", className: cn("flex h-10 w-full items-center gap-2 rounded-[var(--ssui-radius)] px-1.5 text-left outline-none transition-colors hover:bg-[color:var(--ssui-overlay-hover)] focus-visible:ring-2 focus-visible:ring-[color:var(--ssui-focus-ring)]", collapsed
+                                        ? // Collapsed = avatar-only: the text column/chevron are omitted
+                                            // from the layout entirely (not just faded) so the trigger
+                                            // truly fits an icon rail instead of relying on clipping.
+                                            "justify-center px-0"
+                                        : "border border-[color:var(--ssui-border)] bg-[color:var(--ssui-surface)]", className), children: [_jsx(Avatar, { className: "shrink-0", name: name, size: 28, src: image }), !collapsed && (_jsxs(_Fragment, { children: [_jsxs("span", { className: "flex min-w-0 flex-1 flex-col", children: [_jsx("span", { className: "truncate text-[13px] font-medium leading-tight text-[color:var(--ssui-text)]", children: name }), email ? (_jsx("span", { className: "truncate text-[11px] leading-tight text-[color:var(--ssui-text-muted)]", children: email })) : null] }), _jsx(ChevronUp, { className: cn("size-4 shrink-0 text-[color:var(--ssui-text-subtle)] transition-transform duration-150", open && "rotate-180") })] }))] }) }) }), collapsed ? _jsx(TooltipContent, { side: "right", children: name }) : null] }) }), _jsxs(DropdownMenuContent, { align: collapsed ? "end" : "start", className: "w-60 min-w-[var(--radix-dropdown-menu-trigger-width)]", side: collapsed ? "right" : "top", sideOffset: 10, children: [_jsx(DropdownMenuLabel, { children: _jsxs("span", { className: "flex min-w-0 flex-col gap-0.5", children: [_jsx("span", { className: "truncate text-sm font-medium text-[color:var(--ssui-text)]", children: name }), email ? (_jsx("span", { className: "truncate text-xs font-normal text-[color:var(--ssui-text-muted)]", children: email })) : null] }) }), _jsx(DropdownMenuSeparator, {}), theme ? (_jsx(DropdownMenuRadioGroup, { value: theme.value, onValueChange: (value) => theme.onChange(value), children: _jsxs("div", { className: "flex items-center justify-between gap-2 px-2 py-1.5", children: [_jsx("span", { className: "text-xs text-[color:var(--ssui-text-muted)]", children: themeLabel }), _jsx("div", { className: "flex gap-0.5 rounded-[var(--ssui-radius-sm)] border border-[color:var(--ssui-border)] p-0.5", children: themeOptions.map((option) => {
+                                        const { icon: Icon, label } = THEME_OPTION_META[option];
+                                        return (_jsx(DropdownMenuPrimitive.RadioItem, { "aria-label": label, className: "flex size-7 cursor-default select-none items-center justify-center rounded-[calc(var(--ssui-radius-sm)-1px)] text-[color:var(--ssui-text-muted)] outline-none transition-colors focus:bg-[color:var(--ssui-overlay-hover)] data-[highlighted]:bg-[color:var(--ssui-overlay-hover)] data-[state=checked]:bg-[color:var(--ssui-overlay-hover)] data-[state=checked]:text-[color:var(--ssui-text)]", 
+                                            // Keep the menu open: theme picking is a tweak-and-compare loop.
+                                            onSelect: (event) => event.preventDefault(), title: label, value: option, children: _jsx(Icon, { className: "size-4" }) }, option));
+                                    }) })] }) })) : null, children, theme || children ? _jsx(DropdownMenuSeparator, {}) : null, _jsxs(DropdownMenuItem, { onSelect: () => void onSignOut(), children: [_jsx(LogOut, { className: "size-4 text-[color:var(--ssui-text-muted)]" }), signOutLabel] })] })] }));
+}
+export { DropdownMenuItem as AccountMenuItem, DropdownMenuSeparator as AccountMenuSeparator, } from "./dropdown-menu.js";

package/dist/components/button.d.ts

@@ -2,7 +2,7 @@ import { type VariantProps } from "class-variance-authority";
 import * as React from "react";
 export declare const buttonVariants: (props?: ({
     variant?: "link" | "primary" | "outline" | "secondary" | "ghost" | "ghost-accent" | "destructive" | null | undefined;
-    size?: "icon" | "sm" | "md" | "lg" | "icon-sm" | "icon-lg" | null | undefined;
+    size?: "sm" | "md" | "lg" | "icon" | "icon-sm" | "icon-lg" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
     asChild?: boolean;

package/dist/components/choice-card.d.ts

@@ -0,0 +1,33 @@
+import * as React from "react";
+export interface ChoiceCardGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
+    /** Form field name shared by the underlying radios. */
+    name?: string;
+    /** Controlled selected value. */
+    value?: string;
+    /** Uncontrolled initial value. */
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    /** Accessible label for the radio group. */
+    "aria-label"?: string;
+}
+/**
+ * Radio group rendered as selectable bordered cards. Uses native radio
+ * inputs, so form participation and arrow-key navigation between cards come
+ * from the browser. Children are `ChoiceCard`s.
+ */
+export declare function ChoiceCardGroup({ name, value, defaultValue, onValueChange, className, children, ...props }: ChoiceCardGroupProps): import("react/jsx-runtime").JSX.Element;
+export interface ChoiceCardProps extends Omit<React.LabelHTMLAttributes<HTMLLabelElement>, "title"> {
+    /** Value submitted when this card is selected. */
+    value: string;
+    /** Card title. */
+    title: React.ReactNode;
+    /** Optional supporting copy under the title. */
+    description?: React.ReactNode;
+    disabled?: boolean;
+}
+/**
+ * One selectable card inside a `ChoiceCardGroup`: a bordered label wrapping a
+ * native radio plus title and supporting text. The selected card gets the
+ * emphasized border and muted fill.
+ */
+export declare function ChoiceCard({ value, title, description, disabled, className, children, ...props }: ChoiceCardProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/choice-card.js

@@ -0,0 +1,40 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+const ChoiceCardGroupContext = React.createContext(null);
+/**
+ * Radio group rendered as selectable bordered cards. Uses native radio
+ * inputs, so form participation and arrow-key navigation between cards come
+ * from the browser. Children are `ChoiceCard`s.
+ */
+export function ChoiceCardGroup({ name, value, defaultValue, onValueChange, className, children, ...props }) {
+    const generatedName = React.useId();
+    const [uncontrolledValue, setUncontrolledValue] = React.useState(defaultValue);
+    const selected = value ?? uncontrolledValue;
+    const contextValue = React.useMemo(() => ({
+        name: name ?? generatedName,
+        value: selected,
+        setValue: (next) => {
+            if (value === undefined)
+                setUncontrolledValue(next);
+            onValueChange?.(next);
+        },
+    }), [name, generatedName, selected, value, onValueChange]);
+    return (_jsx("div", { role: "radiogroup", className: cn("grid gap-2 md:grid-cols-2", className), ...props, children: _jsx(ChoiceCardGroupContext.Provider, { value: contextValue, children: children }) }));
+}
+/**
+ * One selectable card inside a `ChoiceCardGroup`: a bordered label wrapping a
+ * native radio plus title and supporting text. The selected card gets the
+ * emphasized border and muted fill.
+ */
+export function ChoiceCard({ value, title, description, disabled, className, children, ...props }) {
+    const group = React.useContext(ChoiceCardGroupContext);
+    if (!group) {
+        throw new Error("ChoiceCard must be rendered inside a ChoiceCardGroup");
+    }
+    const selected = group.value === value;
+    return (_jsxs("label", { className: cn("flex cursor-pointer gap-2 rounded-[var(--ssui-radius)] border px-3 py-2 transition-colors has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-[color:var(--ssui-focus-ring)]", selected
+            ? "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)]", disabled && "cursor-not-allowed opacity-50", className), ...props, children: [_jsx("input", { checked: selected, className: "mt-0.5 size-4 shrink-0 accent-current focus-visible:outline-none", disabled: disabled, name: group.name, onChange: () => group.setValue(value), type: "radio", value: value }), _jsxs("span", { className: "min-w-0", children: [_jsx("span", { className: "block text-sm font-medium", children: title }), description ? (_jsx("span", { className: "block text-xs text-[color:var(--ssui-text-subtle)]", children: description })) : null, children] })] }));
+}

package/dist/components/combobox.d.ts

@@ -0,0 +1,37 @@
+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;
+}
+export interface ComboboxProps {
+    /** Full option list; the component filters it against the typed query. */
+    options: ComboboxOption[];
+    /** Selected option value. */
+    value?: string;
+    onValueChange?: (value: string) => void;
+    /**
+     * Filter predicate; defaults to case-insensitive substring match on the
+     * option label and value with spaces treated as underscores.
+     */
+    filter?: (option: ComboboxOption, query: string) => boolean;
+    placeholder?: string;
+    disabled?: boolean;
+    /** Message shown when no option matches. Defaults to "No matches". */
+    emptyMessage?: React.ReactNode;
+    id?: string;
+    name?: string;
+    "aria-label"?: string;
+    "aria-describedby"?: string;
+    "aria-invalid"?: React.AriaAttributes["aria-invalid"];
+    className?: string;
+}
+/**
+ * Filterable single-select following the WAI-ARIA combobox pattern: a text
+ * input filtering a listbox popup. ArrowUp/ArrowDown move the active-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.
+ */
+export declare const Combobox: React.ForwardRefExoticComponent<ComboboxProps & React.RefAttributes<HTMLInputElement>>;

package/dist/components/combobox.js

@@ -0,0 +1,103 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronDown } from "lucide-react";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+import { useFormFieldProps } from "./form-field.js";
+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));
+}
+/**
+ * Filterable single-select following the WAI-ARIA combobox pattern: a text
+ * input filtering a listbox popup. ArrowUp/ArrowDown move the active-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.
+ */
+export const Combobox = React.forwardRef(({ options, value, onValueChange, filter = defaultFilter, placeholder, disabled, emptyMessage = "No matches", className, name, ...ariaProps }, ref) => {
+    const fieldProps = useFormFieldProps(ariaProps);
+    const generatedId = React.useId();
+    const id = fieldProps.id ?? generatedId;
+    const listboxId = `${id}-listbox`;
+    const [open, setOpen] = React.useState(false);
+    const [query, setQuery] = React.useState(null);
+    const [activeIndex, setActiveIndex] = React.useState(-1);
+    const listRef = React.useRef(null);
+    const selectedOption = options.find((option) => option.value === value);
+    const filtered = query === null
+        ? options
+        : options.filter((option) => filter(option, query));
+    const inputValue = query ?? selectedOption?.label ?? "";
+    const activeOption = activeIndex >= 0 ? filtered[activeIndex] : undefined;
+    function openList() {
+        setOpen(true);
+        setActiveIndex(-1);
+    }
+    function close() {
+        setOpen(false);
+        setQuery(null);
+        setActiveIndex(-1);
+    }
+    function commit(option) {
+        onValueChange?.(option.value);
+        close();
+    }
+    function moveActive(delta) {
+        if (filtered.length === 0)
+            return;
+        const next = activeIndex < 0
+            ? delta === 1
+                ? 0
+                : filtered.length - 1
+            : (activeIndex + delta + filtered.length) % filtered.length;
+        setActiveIndex(next);
+        listRef.current
+            ?.querySelector(`[data-index="${next}"]`)
+            ?.scrollIntoView({ block: "nearest" });
+    }
+    function handleKeyDown(event) {
+        if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+            event.preventDefault();
+            if (!open) {
+                openList();
+                return;
+            }
+            moveActive(event.key === "ArrowDown" ? 1 : -1);
+            return;
+        }
+        if (event.key === "Enter") {
+            if (open && activeOption) {
+                event.preventDefault();
+                commit(activeOption);
+            }
+            return;
+        }
+        if (event.key === "Escape") {
+            if (open) {
+                event.stopPropagation();
+                close();
+            }
+        }
+    }
+    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, autoComplete: "off", className: "flex h-10 w-full rounded-[var(--ssui-radius)] border border-[color: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", disabled: disabled, onChange: (event) => {
+                    setQuery(event.target.value);
+                    setOpen(true);
+                    setActiveIndex(-1);
+                }, onFocus: openList, onKeyDown: handleKeyDown, placeholder: 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: () => {
+                    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] }));
+});
+Combobox.displayName = "Combobox";

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

@@ -10,7 +10,15 @@ export declare const DropdownMenuSubTrigger: React.ForwardRefExoticComponent<Omi
     inset?: boolean;
 } & React.RefAttributes<HTMLDivElement>>;
 export declare const DropdownMenuSubContent: React.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuSubContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export declare const DropdownMenuContent: React.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const DropdownMenuContent: React.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
+    /**
+     * Render the panel through a portal to `document.body` (the default). Pass
+     * `false` to render it inline, next to the trigger — useful when the menu
+     * lives inside a subtree that tracks focus (e.g. a click-to-edit editor that
+     * persists on blur) and must keep the open panel within its own DOM.
+     */
+    portal?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
 export declare const DropdownMenuItem: React.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuItemProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
     inset?: boolean;
 } & React.RefAttributes<HTMLDivElement>>;

package/dist/components/dropdown-menu.js

@@ -9,17 +9,20 @@ export const DropdownMenuGroup = DropdownMenuPrimitive.Group;
 export const DropdownMenuPortal = DropdownMenuPrimitive.Portal;
 export const DropdownMenuSub = DropdownMenuPrimitive.Sub;
 export const DropdownMenuRadioGroup = DropdownMenuPrimitive.RadioGroup;
-export const DropdownMenuSubTrigger = React.forwardRef(({ children, className, inset, ...props }, ref) => (_jsxs(DropdownMenuPrimitive.SubTrigger, { ref: ref, className: cn("flex cursor-default select-none items-center rounded-[var(--ssui-radius-sm)] px-2 py-1.5 text-sm text-[color:var(--ssui-text)] outline-none focus:bg-[color:var(--ssui-surface-muted)] data-[state=open]:bg-[color:var(--ssui-surface-muted)]", inset && "pl-8", className), ...props, children: [children, _jsx(ChevronRight, { className: "ml-auto size-4" })] })));
+export const DropdownMenuSubTrigger = React.forwardRef(({ children, className, inset, ...props }, ref) => (_jsxs(DropdownMenuPrimitive.SubTrigger, { ref: ref, className: cn("flex cursor-default select-none items-center rounded-[var(--ssui-radius-sm)] px-2 py-1.5 text-sm text-[color:var(--ssui-text)] outline-none focus:bg-[color:var(--ssui-overlay-hover)] data-[highlighted]:bg-[color:var(--ssui-overlay-hover)] data-[state=open]:bg-[color:var(--ssui-overlay-hover)]", inset && "pl-8", className), ...props, children: [children, _jsx(ChevronRight, { className: "ml-auto size-4" })] })));
 DropdownMenuSubTrigger.displayName = DropdownMenuPrimitive.SubTrigger.displayName;
 export const DropdownMenuSubContent = React.forwardRef(({ className, ...props }, ref) => (_jsx(DropdownMenuPrimitive.SubContent, { ref: ref, className: cn("z-50 min-w-40 overflow-hidden rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border)] bg-[color:var(--ssui-surface-elevated)] p-1 text-[color:var(--ssui-text)] shadow-[var(--ssui-shadow-md)]", className), ...props })));
 DropdownMenuSubContent.displayName = DropdownMenuPrimitive.SubContent.displayName;
-export const DropdownMenuContent = React.forwardRef(({ className, sideOffset = 6, ...props }, ref) => (_jsx(DropdownMenuPrimitive.Portal, { children: _jsx(DropdownMenuPrimitive.Content, { ref: ref, sideOffset: sideOffset, className: cn("z-50 min-w-44 overflow-hidden rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border)] bg-[color:var(--ssui-surface-elevated)] p-1 text-[color:var(--ssui-text)] shadow-[var(--ssui-shadow-md)]", className), ...props }) })));
+export const DropdownMenuContent = React.forwardRef(({ className, portal = true, sideOffset = 6, ...props }, ref) => {
+    const content = (_jsx(DropdownMenuPrimitive.Content, { ref: ref, sideOffset: sideOffset, className: cn("z-50 min-w-44 overflow-hidden rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border)] bg-[color:var(--ssui-surface-elevated)] p-1 text-[color:var(--ssui-text)] shadow-[var(--ssui-shadow-md)]", className), ...props }));
+    return portal ? _jsx(DropdownMenuPrimitive.Portal, { children: content }) : content;
+});
 DropdownMenuContent.displayName = DropdownMenuPrimitive.Content.displayName;
-export const DropdownMenuItem = React.forwardRef(({ className, inset, ...props }, ref) => (_jsx(DropdownMenuPrimitive.Item, { ref: ref, className: cn("relative flex cursor-default select-none items-center gap-2 rounded-[var(--ssui-radius-sm)] px-2 py-1.5 text-sm outline-none transition-colors focus:bg-[color:var(--ssui-surface-muted)] data-[disabled]:pointer-events-none data-[disabled]:opacity-50", inset && "pl-8", className), ...props })));
+export const DropdownMenuItem = React.forwardRef(({ className, inset, ...props }, ref) => (_jsx(DropdownMenuPrimitive.Item, { ref: ref, className: cn("relative flex cursor-default select-none items-center gap-2 rounded-[var(--ssui-radius-sm)] px-2 py-1.5 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", inset && "pl-8", className), ...props })));
 DropdownMenuItem.displayName = DropdownMenuPrimitive.Item.displayName;
-export const DropdownMenuCheckboxItem = React.forwardRef(({ children, className, checked, ...props }, ref) => (_jsxs(DropdownMenuPrimitive.CheckboxItem, { ref: ref, checked: checked, className: cn("relative flex cursor-default select-none items-center rounded-[var(--ssui-radius-sm)] py-1.5 pl-8 pr-2 text-sm outline-none transition-colors focus:bg-[color:var(--ssui-surface-muted)] data-[disabled]:pointer-events-none data-[disabled]:opacity-50", className), ...props, children: [_jsx("span", { className: "absolute left-2 flex size-3.5 items-center justify-center", children: _jsx(DropdownMenuPrimitive.ItemIndicator, { children: _jsx(Check, { className: "size-4" }) }) }), children] })));
+export const DropdownMenuCheckboxItem = React.forwardRef(({ children, className, checked, ...props }, ref) => (_jsxs(DropdownMenuPrimitive.CheckboxItem, { ref: ref, checked: checked, className: cn("relative flex cursor-default select-none items-center rounded-[var(--ssui-radius-sm)] py-1.5 pl-8 pr-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", className), ...props, children: [_jsx("span", { className: "absolute left-2 flex size-3.5 items-center justify-center", children: _jsx(DropdownMenuPrimitive.ItemIndicator, { children: _jsx(Check, { className: "size-4" }) }) }), children] })));
 DropdownMenuCheckboxItem.displayName = DropdownMenuPrimitive.CheckboxItem.displayName;
-export const DropdownMenuRadioItem = React.forwardRef(({ children, className, ...props }, ref) => (_jsxs(DropdownMenuPrimitive.RadioItem, { ref: ref, className: cn("relative flex cursor-default select-none items-center rounded-[var(--ssui-radius-sm)] py-1.5 pl-8 pr-2 text-sm outline-none transition-colors focus:bg-[color:var(--ssui-surface-muted)] data-[disabled]:pointer-events-none data-[disabled]:opacity-50", className), ...props, children: [_jsx("span", { className: "absolute left-2 flex size-3.5 items-center justify-center", children: _jsx(DropdownMenuPrimitive.ItemIndicator, { children: _jsx(Circle, { className: "size-2 fill-current" }) }) }), children] })));
+export const DropdownMenuRadioItem = React.forwardRef(({ children, className, ...props }, ref) => (_jsxs(DropdownMenuPrimitive.RadioItem, { ref: ref, className: cn("relative flex cursor-default select-none items-center rounded-[var(--ssui-radius-sm)] py-1.5 pl-8 pr-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", className), ...props, children: [_jsx("span", { className: "absolute left-2 flex size-3.5 items-center justify-center", children: _jsx(DropdownMenuPrimitive.ItemIndicator, { children: _jsx(Circle, { className: "size-2 fill-current" }) }) }), children] })));
 DropdownMenuRadioItem.displayName = DropdownMenuPrimitive.RadioItem.displayName;
 export const DropdownMenuLabel = React.forwardRef(({ className, inset, ...props }, ref) => (_jsx(DropdownMenuPrimitive.Label, { ref: ref, className: cn("px-2 py-1.5 text-xs font-medium text-[color:var(--ssui-text-muted)]", inset && "pl-8", className), ...props })));
 DropdownMenuLabel.displayName = DropdownMenuPrimitive.Label.displayName;

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

@@ -0,0 +1,48 @@
+import * as React from "react";
+export interface FormFieldContextValue {
+    /** Id the participating control should adopt. */
+    id: string;
+    /** Space-separated ids of the description/error elements, if any. */
+    describedBy?: string;
+    /** True when the field is in an error state. */
+    invalid: boolean;
+}
+/**
+ * Read the enclosing `FormField` context, if any. Package controls use this
+ * to adopt the generated `id`/`aria-describedby`/`aria-invalid` wiring;
+ * standalone controls (no enclosing field) get `null` and render unchanged.
+ */
+export declare function useFormField(): FormFieldContextValue | null;
+/**
+ * Merge `FormField` context wiring into a control's own props. The field owns
+ * the control's `id` so the label and control stay associated (customize it via
+ * `FormField`'s `htmlFor`, not the control). An explicit `aria-describedby` on
+ * the control is concatenated with — not replaced by — the field's
+ * description/error ids so error announcement is never dropped. An explicit
+ * `aria-invalid` still wins.
+ */
+export declare function useFormFieldProps<T extends {
+    id?: string;
+    "aria-describedby"?: string;
+    "aria-invalid"?: React.AriaAttributes["aria-invalid"];
+}>(props: T): T;
+export interface FormFieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+    /** Field label. */
+    label: React.ReactNode;
+    /** Optional supporting copy shown under the label. */
+    description?: React.ReactNode;
+    /** Error message; when set the field is marked invalid. */
+    error?: React.ReactNode;
+    /** Explicit control id; defaults to a generated id. */
+    htmlFor?: string;
+    /** The control. Package controls pick up the field wiring automatically. */
+    children: React.ReactNode;
+}
+/**
+ * Label + description + control + error wrapper with standardized typography
+ * and accessibility wiring. Generates an id shared between the label's
+ * `htmlFor` and the control, and threads `aria-describedby`/`aria-invalid`
+ * to package controls (`Input`, `Textarea`, `Select`, `Combobox`) via
+ * context. Non-package controls can adopt the same id manually via `htmlFor`.
+ */
+export declare function FormField({ label, description, error, htmlFor, className, children, ...props }: FormFieldProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/form-field.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+const FormFieldContext = React.createContext(null);
+/**
+ * Read the enclosing `FormField` context, if any. Package controls use this
+ * to adopt the generated `id`/`aria-describedby`/`aria-invalid` wiring;
+ * standalone controls (no enclosing field) get `null` and render unchanged.
+ */
+export function useFormField() {
+    return React.useContext(FormFieldContext);
+}
+/**
+ * Merge `FormField` context wiring into a control's own props. The field owns
+ * the control's `id` so the label and control stay associated (customize it via
+ * `FormField`'s `htmlFor`, not the control). An explicit `aria-describedby` on
+ * the control is concatenated with — not replaced by — the field's
+ * description/error ids so error announcement is never dropped. An explicit
+ * `aria-invalid` still wins.
+ */
+export function useFormFieldProps(props) {
+    const field = useFormField();
+    if (!field)
+        return props;
+    const describedBy = [props["aria-describedby"], field.describedBy].filter(Boolean).join(" ") ||
+        undefined;
+    return {
+        ...props,
+        id: field.id,
+        "aria-describedby": describedBy,
+        "aria-invalid": props["aria-invalid"] ?? (field.invalid || undefined),
+    };
+}
+/**
+ * Label + description + control + error wrapper with standardized typography
+ * and accessibility wiring. Generates an id shared between the label's
+ * `htmlFor` and the control, and threads `aria-describedby`/`aria-invalid`
+ * to package controls (`Input`, `Textarea`, `Select`, `Combobox`) via
+ * context. Non-package controls can adopt the same id manually via `htmlFor`.
+ */
+export function FormField({ label, description, error, htmlFor, className, children, ...props }) {
+    const generatedId = React.useId();
+    const id = htmlFor ?? generatedId;
+    const descriptionId = `${id}-description`;
+    const errorId = `${id}-error`;
+    const describedBy = [description ? descriptionId : null, error ? errorId : null]
+        .filter(Boolean)
+        .join(" ") || undefined;
+    const contextValue = React.useMemo(() => ({ id, describedBy, invalid: Boolean(error) }), [id, describedBy, error]);
+    return (_jsxs("div", { className: cn("space-y-1.5", className), ...props, children: [_jsx("label", { className: "block text-sm font-medium text-[color:var(--ssui-text)]", htmlFor: id, children: label }), description ? (_jsx("p", { className: "text-xs text-[color:var(--ssui-text-muted)]", id: descriptionId, children: description })) : null, _jsx(FormFieldContext.Provider, { value: contextValue, children: children }), error ? (_jsx("p", { className: "text-xs text-[color:var(--ssui-destructive)]", id: errorId, children: error })) : null] }));
+}

package/dist/components/index.d.ts

@@ -1,9 +1,13 @@
+export * from "./account-menu.js";
 export * from "./audit-log.js";
 export * from "./avatar.js";
 export * from "./badge.js";
 export * from "./brand-icons.js";
 export * from "./button.js";
+export * from "./choice-card.js";
+export * from "./combobox.js";
 export * from "./confirm-dialog.js";
+export * from "./form-field.js";
 export * from "./copy-field.js";
 export * from "./dialog.js";
 export * from "./dropdown-menu.js";
@@ -15,15 +19,23 @@ export * from "./inline-rename-input.js";
 export * from "./input.js";
 export * from "./list-shell.js";
 export * from "./login.js";
+export * from "./overflow-menu.js";
 export * from "./page-header.js";
+export * from "./rail-toggle.js";
 export * from "./request-access.js";
 export * from "./scroll-area.js";
 export * from "./search-input.js";
+export * from "./select.js";
 export * from "./separator.js";
+export * from "./settings-layout.js";
+export * from "./settings-nav.js";
 export * from "./settings-section.js";
 export * from "./skeleton.js";
 export * from "./status-pill.js";
+export * from "./switch.js";
 export * from "./tabs.js";
 export * from "./textarea.js";
+export * from "./time-zone-field.js";
 export * from "./toolbar.js";
 export * from "./tooltip.js";
+export * from "./workspace-switcher.js";

package/dist/components/index.js

@@ -1,9 +1,13 @@
+export * from "./account-menu.js";
 export * from "./audit-log.js";
 export * from "./avatar.js";
 export * from "./badge.js";
 export * from "./brand-icons.js";
 export * from "./button.js";
+export * from "./choice-card.js";
+export * from "./combobox.js";
 export * from "./confirm-dialog.js";
+export * from "./form-field.js";
 export * from "./copy-field.js";
 export * from "./dialog.js";
 export * from "./dropdown-menu.js";
@@ -15,15 +19,23 @@ export * from "./inline-rename-input.js";
 export * from "./input.js";
 export * from "./list-shell.js";
 export * from "./login.js";
+export * from "./overflow-menu.js";
 export * from "./page-header.js";
+export * from "./rail-toggle.js";
 export * from "./request-access.js";
 export * from "./scroll-area.js";
 export * from "./search-input.js";
+export * from "./select.js";
 export * from "./separator.js";
+export * from "./settings-layout.js";
+export * from "./settings-nav.js";
 export * from "./settings-section.js";
 export * from "./skeleton.js";
 export * from "./status-pill.js";
+export * from "./switch.js";
 export * from "./tabs.js";
 export * from "./textarea.js";
+export * from "./time-zone-field.js";
 export * from "./toolbar.js";
 export * from "./tooltip.js";
+export * from "./workspace-switcher.js";