@nadicodeai/ui 12.1.95 → 12.1.97

package/dist/components/resizable.js

@@ -2,6 +2,16 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import * as ResizablePrimitive from "react-resizable-panels";
 import { cn } from "../lib/utils.js";
+/**
+ * Panels a person resizes by dragging the handle between them.
+ *
+ * @family Other
+ * @when Side-by-side panes whose balance a person sets: a conversation and its side panel.
+ * @instead The product frame's sidebar resizes through `DashboardShell` or `DesktopAppShell`.
+ * @behaviour The handle moves on drag and on arrow keys; each panel keeps its minimum and maximum.
+ * @words None of its own.
+ * @access The handle is the resizable library's focusable separator.
+ */
 function ResizablePanelGroup({ className, ...props }) {
     return (_jsx(ResizablePrimitive.Group, { "data-slot": "resizable-panel-group", className: cn("flex h-full w-full aria-[orientation=vertical]:flex-col", className), ...props }));
 }

package/dist/components/row-edit-form.d.ts

@@ -12,11 +12,14 @@ export type RowEditFormProps = Omit<ComponentProps<"form">, "children" | "classN
     children: ReactNode;
 };
 /**
- * A record's form opened inside its own row (DESIGN.md "Menus and commands"),
- * a `DataTable`'s `rowEditor`: the fields under the record's line, then a
- * footer one tone below with an optional hint at its leading edge, then Cancel
- * and the save rightmost. Cancel holds while
- * the save runs.
+ * A record's form opened inside its own row, the rows above and below staying where they are.
+ *
+ * @family Compositions
+ * @when A person changes a record they see in a list: edit a mailbox, a task, an MCP server, a channel. It is a `RecordList`'s `editor` or a `DataTable`'s `rowEditor`.
+ * @instead A new record from a few fields is a `FormDialog`; a fact on the record's own page changes in place in its section; a choice from a catalogue is a `CatalogDrawer`.
+ * @behaviour The fields open under the record's line; a refusal or a failed save sits above the footer. The footer, one tone below, holds an optional hint at its leading edge, then Cancel and the save rightmost. Save stays off until a field changes: the caller sets `submit.disabled` from its own fields. Cancel holds while the save runs, and the waiting line runs under them.
+ * @words The save says what it does, "Save"; Cancel is "Cancel". The hint is a way on, such as where to find a token, never a restatement of a field's label.
+ * @access A form in the row's place, which the caller moves focus into. The running save is marked busy, and the line saying why the save cannot run yet is its description (`submit.describedBy`).
  */
 export declare function RowEditForm({ cancelLabel, onCancel, submit, notice, hint, children, ...form }: RowEditFormProps): import("react").JSX.Element;
 //# sourceMappingURL=row-edit-form.d.ts.map

package/dist/components/row-edit-form.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"row-edit-form.d.ts","sourceRoot":"","sources":["../../src/components/row-edit-form.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvD,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,wBAAwB,CAAC;AAE3E,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC,GAAG;IACtF,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC;IACnB,iFAAiF;IACjF,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,gGAAgG;IAChG,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,SAAS,CAAC;CACrB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,EAC1B,WAAW,EACX,QAAQ,EACR,MAAM,EACN,MAAM,EACN,IAAI,EACJ,QAAQ,EACR,GAAG,IAAI,EACR,EAAE,gBAAgB,+BAqBlB"}
+{"version":3,"file":"row-edit-form.d.ts","sourceRoot":"","sources":["../../src/components/row-edit-form.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvD,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,wBAAwB,CAAC;AAE3E,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC,GAAG;IACtF,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC;IACnB,iFAAiF;IACjF,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,gGAAgG;IAChG,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,SAAS,CAAC;CACrB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,EAC1B,WAAW,EACX,QAAQ,EACR,MAAM,EACN,MAAM,EACN,IAAI,EACJ,QAAQ,EACR,GAAG,IAAI,EACR,EAAE,gBAAgB,+BAqBlB"}

package/dist/components/row-edit-form.js

@@ -4,11 +4,14 @@ import { Button } from "./button.js";
 import { WaitingLine } from "./waiting-line.js";
 import { FormSubmitButton } from "../internal/form-submit.js";
 /**
- * A record's form opened inside its own row (DESIGN.md "Menus and commands"),
- * a `DataTable`'s `rowEditor`: the fields under the record's line, then a
- * footer one tone below with an optional hint at its leading edge, then Cancel
- * and the save rightmost. Cancel holds while
- * the save runs.
+ * A record's form opened inside its own row, the rows above and below staying where they are.
+ *
+ * @family Compositions
+ * @when A person changes a record they see in a list: edit a mailbox, a task, an MCP server, a channel. It is a `RecordList`'s `editor` or a `DataTable`'s `rowEditor`.
+ * @instead A new record from a few fields is a `FormDialog`; a fact on the record's own page changes in place in its section; a choice from a catalogue is a `CatalogDrawer`.
+ * @behaviour The fields open under the record's line; a refusal or a failed save sits above the footer. The footer, one tone below, holds an optional hint at its leading edge, then Cancel and the save rightmost. Save stays off until a field changes: the caller sets `submit.disabled` from its own fields. Cancel holds while the save runs, and the waiting line runs under them.
+ * @words The save says what it does, "Save"; Cancel is "Cancel". The hint is a way on, such as where to find a token, never a restatement of a field's label.
+ * @access A form in the row's place, which the caller moves focus into. The running save is marked busy, and the line saying why the save cannot run yet is its description (`submit.describedBy`).
  */
 export function RowEditForm({ cancelLabel, onCancel, submit, notice, hint, children, ...form }) {
     const pending = submit.pending === true;

package/dist/components/run-timeline.d.ts

@@ -1,16 +1,29 @@
-import * as React from "react";
-export type RunTimelineState = "ready" | "running" | "review" | "blocked" | "complete";
+import type { ComponentProps, ReactNode } from "react";
+import type { RecordStatus } from "./record-list.js";
 export type RunTimelineStep = {
     id: string;
+    /** "Step 01" */
+    label: string;
     title: string;
-    label?: string;
-    detail?: string;
-    state?: RunTimelineState;
-    /** Escape hatch: rich detail content that replaces the serializable `detail`. */
-    detailSlot?: React.ReactNode;
+    detail?: ReactNode;
+    /** The node marks the step and never grades it. */
+    progress: "done" | "current" | "upcoming";
+    /** The outcome that needs a person, inside the step: "Needs your decision". */
+    status?: RecordStatus | null;
+    /** In the feed's time style; "—" until it happens. */
+    time?: ReactNode;
 };
-declare function RunTimeline({ className, steps, ...props }: Omit<React.ComponentProps<"div">, "children"> & {
-    steps: RunTimelineStep[];
-}): React.JSX.Element;
-export { RunTimeline };
+/**
+ * One run of an Agent, read step by step on a neutral rail.
+ *
+ * @family Data
+ * @when The steps of one run, in order: a scheduled task's run, an Agent's handoff. Each step is something the run did or will do.
+ * @instead What happened to a record over time is an ActivityFeed; steps a person follows are NumberedSteps; the stages a system runs on an entry screen are the EntryStageList.
+ * @behaviour Each step is a node on one rail, its label and title, one line of detail, and its time at the trailing edge ("—" until it happens). The node marks the step and never grades it: the current step's node is ink, a step to come is drawn in the line colour with its title muted. An outcome that needs a person is the StatusBadge inside its step. Nothing moves.
+ * @words The label numbers the step ("Step 01"); a done step's title is in the past tense ("Filed the invoices"), a step to come in the imperative ("Send the summary to Marco"); a waiting step's detail says what it waits for ("Waits for your decision on step 03").
+ * @access An ordered list; the current step carries `aria-current="step"`; the rail and nodes are hidden from assistive technology, and so is the dash of a step that has not happened.
+ */
+export declare function RunTimeline({ className, steps, ...props }: Omit<ComponentProps<"ol">, "children"> & {
+    steps: readonly RunTimelineStep[];
+}): import("react").JSX.Element;
 //# sourceMappingURL=run-timeline.d.ts.map

package/dist/components/run-timeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-timeline.d.ts","sourceRoot":"","sources":["../../src/components/run-timeline.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AAEvF,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,iFAAiF;IACjF,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC9B,CAAC;AAEF,iBAAS,WAAW,CAAC,EACnB,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,GAAG;IACjD,KAAK,EAAE,eAAe,EAAE,CAAC;CAC1B,qBA0BA;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"run-timeline.d.ts","sourceRoot":"","sources":["../../src/components/run-timeline.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAI7D,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;IAC1C,+EAA+E;IAC/E,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC7B,sDAAsD;IACtD,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,EAC1B,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,GAAG;IAAE,KAAK,EAAE,SAAS,eAAe,EAAE,CAAA;CAAE,+BA+BhF"}

package/dist/components/run-timeline.js

@@ -1,9 +1,16 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { StatusBadge } from "./status-badge.js";
 import { cn } from "../lib/utils.js";
-function RunTimeline({ className, steps, ...props }) {
-    return (_jsx("div", { "data-slot": "run-timeline", className: cn("nc-run-timeline", className), ...props, children: steps.map((step) => {
-            const detail = step.detailSlot ?? step.detail;
-            return (_jsxs("div", { "data-slot": "run-timeline-step", "data-state": step.state, className: "nc-run-timeline-step", children: [_jsx("span", { className: "nc-run-timeline-node", "aria-hidden": "true" }), _jsxs("div", { className: "nc-run-timeline-content", children: [_jsxs("div", { className: "nc-run-timeline-label", children: [step.label, _jsx("span", { className: "nc-run-timeline-title", children: step.title })] }), detail != null && _jsx("div", { className: "nc-run-timeline-detail", children: detail })] })] }, step.id));
-        }) }));
+/**
+ * One run of an Agent, read step by step on a neutral rail.
+ *
+ * @family Data
+ * @when The steps of one run, in order: a scheduled task's run, an Agent's handoff. Each step is something the run did or will do.
+ * @instead What happened to a record over time is an ActivityFeed; steps a person follows are NumberedSteps; the stages a system runs on an entry screen are the EntryStageList.
+ * @behaviour Each step is a node on one rail, its label and title, one line of detail, and its time at the trailing edge ("—" until it happens). The node marks the step and never grades it: the current step's node is ink, a step to come is drawn in the line colour with its title muted. An outcome that needs a person is the StatusBadge inside its step. Nothing moves.
+ * @words The label numbers the step ("Step 01"); a done step's title is in the past tense ("Filed the invoices"), a step to come in the imperative ("Send the summary to Marco"); a waiting step's detail says what it waits for ("Waits for your decision on step 03").
+ * @access An ordered list; the current step carries `aria-current="step"`; the rail and nodes are hidden from assistive technology, and so is the dash of a step that has not happened.
+ */
+export function RunTimeline({ className, steps, ...props }) {
+    return (_jsx("ol", { "data-slot": "run-timeline", className: cn("nc-run-timeline", className), ...props, children: steps.map((step) => (_jsxs("li", { "aria-current": step.progress === "current" ? "step" : undefined, className: "nc-run-timeline-step", "data-progress": step.progress, "data-slot": "run-timeline-step", children: [_jsx("span", { "aria-hidden": "true", className: "nc-run-timeline-node" }), _jsxs("div", { className: "nc-run-timeline-content", children: [_jsxs("div", { className: "flex flex-wrap items-baseline gap-x-2", children: [_jsx("span", { className: "nc-run-timeline-label", children: step.label }), _jsx("span", { className: "nc-run-timeline-title", children: step.title })] }), step.detail != null ? (_jsx("div", { className: "nc-run-timeline-detail", children: step.detail })) : null, step.status ? (_jsx(StatusBadge, { className: "mt-1.5", label: step.status.label, tone: step.status.tone })) : null] }), _jsx("div", { className: "shrink-0 text-label-sm leading-5 whitespace-nowrap tabular-nums text-muted-foreground", children: step.time ?? _jsx("span", { "aria-hidden": "true", children: "\u2014" }) })] }, step.id))) }));
 }
-export { RunTimeline };

package/dist/components/scope-switcher.d.ts

@@ -13,6 +13,7 @@ export type ScopeSwitcherCopy = {
 export type ScopeSwitcherProps = {
     value: string;
     options: readonly ScopeOption[];
+    /** Writes the choice to the URL, so sibling pages keep it. */
     onValueChange: (value: string) => void;
     copy: ScopeSwitcherCopy;
     create?: {
@@ -20,5 +21,15 @@ export type ScopeSwitcherProps = {
         onSelect: () => void;
     };
 };
+/**
+ * Says which part of the account a page reads, and changes it.
+ *
+ * @family Navigation
+ * @when Changing which part of the account a page reads, such as Analytics' scope: the whole fleet, one partner, one customer. Only when the viewer has more than one.
+ * @instead A viewer with one scope and nothing to create reads its name with no control, which this draws by itself. Finding anything is `CommandDialog`; narrowing rows is `CollectionFilters`.
+ * @behaviour A ghost trigger, at most 16rem, opens a 288 px popover with focus in its search. Type to filter, Enter chooses and closes; choosing the current one changes nothing. The caller writes the choice to the URL in `onValueChange`, so sibling pages keep it. An optional create command sits last.
+ * @words `copy.label` names what is chosen ("Scope") beside the current scope's name. Search and empty lines name the thing: "Find a scope", "No scope matches".
+ * @access The trigger reads "Scope: All customers"; the popover has a hidden title; options are a listbox with the current one checked.
+ */
 export declare function ScopeSwitcher({ value, options, onValueChange, copy, create }: ScopeSwitcherProps): React.JSX.Element;
 //# sourceMappingURL=scope-switcher.d.ts.map

package/dist/components/scope-switcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope-switcher.d.ts","sourceRoot":"","sources":["../../src/components/scope-switcher.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAe/B,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IAChC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,IAAI,EAAE,iBAAiB,CAAC;IACxB,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;CAClD,CAAC;AAEF,wBAAgB,aAAa,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,kBAAkB,qBAgFhG"}
+{"version":3,"file":"scope-switcher.d.ts","sourceRoot":"","sources":["../../src/components/scope-switcher.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAe/B,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IAChC,8DAA8D;IAC9D,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,IAAI,EAAE,iBAAiB,CAAC;IACxB,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;CAClD,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,kBAAkB,qBA6FhG"}

package/dist/components/scope-switcher.js

@@ -5,10 +5,20 @@ import { ChevronsUpDown, Plus } from "lucide-react";
 import { Button } from "./button.js";
 import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, } from "./command.js";
 import { Popover, PopoverContent, PopoverTitle, PopoverTrigger } from "./popover.js";
+/**
+ * Says which part of the account a page reads, and changes it.
+ *
+ * @family Navigation
+ * @when Changing which part of the account a page reads, such as Analytics' scope: the whole fleet, one partner, one customer. Only when the viewer has more than one.
+ * @instead A viewer with one scope and nothing to create reads its name with no control, which this draws by itself. Finding anything is `CommandDialog`; narrowing rows is `CollectionFilters`.
+ * @behaviour A ghost trigger, at most 16rem, opens a 288 px popover with focus in its search. Type to filter, Enter chooses and closes; choosing the current one changes nothing. The caller writes the choice to the URL in `onValueChange`, so sibling pages keep it. An optional create command sits last.
+ * @words `copy.label` names what is chosen ("Scope") beside the current scope's name. Search and empty lines name the thing: "Find a scope", "No scope matches".
+ * @access The trigger reads "Scope: All customers"; the popover has a hidden title; options are a listbox with the current one checked.
+ */
 export function ScopeSwitcher({ value, options, onValueChange, copy, create }) {
     const [open, setOpen] = React.useState(false);
     const search = React.useRef(null);
-    const current = options.find((option) => option.value === value);
+    const currentLabel = options.find((option) => option.value === value)?.label ?? value;
     const groups = React.useMemo(() => {
         const byGroup = new Map();
         for (const option of options) {
@@ -23,12 +33,13 @@ export function ScopeSwitcher({ value, options, onValueChange, copy, create }) {
         if (next !== value)
             onValueChange(next);
     };
-    return (_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsxs(PopoverTrigger, { render: _jsx(Button, { variant: "ghost", "aria-label": `${copy.label}: ${current?.label ?? value}`, className: "max-w-64" }), children: [_jsx("span", { className: "truncate", children: current?.label ?? value }), _jsx(ChevronsUpDown, { "data-icon": "inline-end", "aria-hidden": "true" })] }), _jsxs(PopoverContent, { align: "start", className: "w-72 p-0", initialFocus: search, children: [_jsx(PopoverTitle, { className: "sr-only", children: copy.label }), _jsxs(Command, { label: copy.search, children: [_jsx(CommandInput, { ref: search, "aria-label": copy.search, placeholder: copy.search }), _jsxs(CommandList, { label: copy.label, children: [_jsx(CommandEmpty, { children: copy.empty }), groups.map(([group, items]) => (_jsx(CommandGroup, { heading: group, children: items.map((option) => (_jsx(CommandItem, { value: option.value, keywords: [
-                                                option.label,
-                                                ...(option.group ? [option.group] : []),
-                                                ...(option.keywords ?? []),
-                                            ], "data-checked": option.value === value, onSelect: () => choose(option.value), children: _jsx("span", { className: "truncate", children: option.label }) }, option.value))) }, group ?? ""))), create ? (_jsxs(_Fragment, { children: [_jsx(CommandSeparator, { alwaysRender: true }), _jsx(CommandGroup, { forceMount: true, children: _jsxs(CommandItem, { value: `create ${create.label}`, forceMount: true, onSelect: () => {
-                                                        setOpen(false);
-                                                        create.onSelect();
-                                                    }, children: [_jsx(Plus, { "aria-hidden": "true" }), create.label] }) })] })) : null] })] })] })] }));
+    const switchable = options.length > 1 || create !== undefined;
+    return (_jsxs("span", { "data-slot": "scope-switcher", className: "flex min-w-0 items-center gap-2", children: [_jsx("span", { "aria-hidden": switchable ? "true" : undefined, className: "text-xs font-medium text-muted-foreground", children: copy.label }), switchable ? (_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsxs(PopoverTrigger, { render: _jsx(Button, { variant: "ghost", "aria-label": `${copy.label}: ${currentLabel}`, className: "max-w-64" }), children: [_jsx("span", { className: "truncate", children: currentLabel }), _jsx(ChevronsUpDown, { "data-icon": "inline-end", "aria-hidden": "true" })] }), _jsxs(PopoverContent, { align: "start", className: "w-72 p-0", initialFocus: search, children: [_jsx(PopoverTitle, { className: "sr-only", children: copy.label }), _jsxs(Command, { label: copy.search, children: [_jsx(CommandInput, { ref: search, "aria-label": copy.search, placeholder: copy.search }), _jsxs(CommandList, { label: copy.label, children: [_jsx(CommandEmpty, { children: copy.empty }), groups.map(([group, items]) => (_jsx(CommandGroup, { heading: group, children: items.map((option) => (_jsx(CommandItem, { value: option.value, keywords: [
+                                                        option.label,
+                                                        ...(option.group ? [option.group] : []),
+                                                        ...(option.keywords ?? []),
+                                                    ], "data-checked": option.value === value, onSelect: () => choose(option.value), children: _jsx("span", { className: "truncate", children: option.label }) }, option.value))) }, group ?? ""))), create ? (_jsxs(_Fragment, { children: [_jsx(CommandSeparator, { alwaysRender: true }), _jsx(CommandGroup, { forceMount: true, children: _jsxs(CommandItem, { value: `create ${create.label}`, forceMount: true, onSelect: () => {
+                                                                setOpen(false);
+                                                                create.onSelect();
+                                                            }, children: [_jsx(Plus, { "aria-hidden": "true" }), create.label] }) })] })) : null] })] })] })] })) : (_jsx("span", { className: "truncate px-3 text-sm", children: currentLabel }))] }));
 }

package/dist/components/scroll-area.d.ts

@@ -1,5 +1,17 @@
 import * as React from "react";
 import { ScrollArea as ScrollAreaPrimitive } from "@base-ui/react/scroll-area";
+/**
+ * An area that scrolls with the product's own thin scrollbar.
+ *
+ * @family Other
+ * @when A bounded area whose content overflows on one axis: a side panel's list, a menu's long
+ * body.
+ * @instead A page scrolls as the document. A rail of slides is `Carousel`.
+ * @behaviour The viewport scrolls natively, so wheel, touch and keyboard all reach it; the thin
+ * scrollbar is drawn over the content.
+ * @words None of its own.
+ * @access The content keeps its own semantics; the scrollbar is paint.
+ */
 declare function ScrollArea({ className, children, ...props }: ScrollAreaPrimitive.Root.Props): React.JSX.Element;
 declare function ScrollBar({ className, orientation, ...props }: ScrollAreaPrimitive.Scrollbar.Props): React.JSX.Element;
 export { ScrollArea, ScrollBar };

package/dist/components/scroll-area.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scroll-area.d.ts","sourceRoot":"","sources":["../../src/components/scroll-area.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,UAAU,IAAI,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAI/E,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,mBAAmB,CAAC,IAAI,CAAC,KAAK,qBAiBpF;AAED,iBAAS,SAAS,CAAC,EACjB,SAAS,EACT,WAAwB,EACxB,GAAG,KAAK,EACT,EAAE,mBAAmB,CAAC,SAAS,CAAC,KAAK,qBAkBrC;AAED,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"scroll-area.d.ts","sourceRoot":"","sources":["../../src/components/scroll-area.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,UAAU,IAAI,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAI/E;;;;;;;;;;;GAWG;AACH,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,mBAAmB,CAAC,IAAI,CAAC,KAAK,qBAiBpF;AAED,iBAAS,SAAS,CAAC,EACjB,SAAS,EACT,WAAwB,EACxB,GAAG,KAAK,EACT,EAAE,mBAAmB,CAAC,SAAS,CAAC,KAAK,qBAkBrC;AAED,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC"}

package/dist/components/scroll-area.js

@@ -1,6 +1,18 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ScrollArea as ScrollAreaPrimitive } from "@base-ui/react/scroll-area";
 import { cn } from "../lib/utils.js";
+/**
+ * An area that scrolls with the product's own thin scrollbar.
+ *
+ * @family Other
+ * @when A bounded area whose content overflows on one axis: a side panel's list, a menu's long
+ * body.
+ * @instead A page scrolls as the document. A rail of slides is `Carousel`.
+ * @behaviour The viewport scrolls natively, so wheel, touch and keyboard all reach it; the thin
+ * scrollbar is drawn over the content.
+ * @words None of its own.
+ * @access The content keeps its own semantics; the scrollbar is paint.
+ */
 function ScrollArea({ className, children, ...props }) {
     return (_jsxs(ScrollAreaPrimitive.Root, { "data-slot": "scroll-area", className: cn("relative", className), ...props, children: [_jsx(ScrollAreaPrimitive.Viewport, { "data-slot": "scroll-area-viewport", className: "size-full rounded-[inherit] transition-colors", children: children }), _jsx(ScrollBar, {}), _jsx(ScrollAreaPrimitive.Corner, {})] }));
 }

package/dist/components/select.d.ts

@@ -1,5 +1,21 @@
 import * as React from "react";
 import { Select as SelectPrimitive } from "@base-ui/react/select";
+/**
+ * A short fixed list in our style, opened from a trigger that shows the choice.
+ *
+ * @family Choices
+ * @when Four to about ten fixed options in our style, each short enough to need no sentence: how
+ * often a task runs.
+ * @instead Two or three options are radios or a segmented control. A list to type into is a
+ * `Combobox`. Inside a native form a long list is `NativeSelect`.
+ * @behaviour The trigger shows the chosen value; the list floats under it with 12 px corners and a
+ * check at the chosen row's end. Arrows, typing, Enter, Escape. A placeholder reads in the muted
+ * grey and is never an option.
+ * @words Options are parallel phrases in sentence case: *Every hour*, *Every weekday*. The trigger
+ * never says *Select…*.
+ * @access A visible label tied to the trigger; listbox and option roles from Base UI; focus returns
+ * to the trigger on close.
+ */
 declare const Select: typeof SelectPrimitive.Root;
 declare function SelectGroup({ className, ...props }: SelectPrimitive.Group.Props): React.JSX.Element;
 declare function SelectValue({ className, ...props }: SelectPrimitive.Value.Props): React.JSX.Element;

package/dist/components/select.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../src/components/select.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,MAAM,IAAI,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAMlE,QAAA,MAAM,MAAM,6BAAuB,CAAC;AAEpC,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,eAAe,CAAC,KAAK,CAAC,KAAK,qBAQxE;AAED,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,eAAe,CAAC,KAAK,CAAC,KAAK,qBAQxE;AAED,iBAAS,aAAa,CAAC,EACrB,SAAS,EACT,IAAgB,EAChB,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,eAAe,CAAC,OAAO,CAAC,KAAK,GAAG;IACjC,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;CACzB,qBAiBA;AAED,iBAAS,aAAa,CAAC,EACrB,SAAS,EACT,QAAQ,EACR,IAAe,EACf,UAAc,EACd,KAAgB,EAChB,WAAe,EACf,oBAA2B,EAC3B,GAAG,KAAK,EACT,EAAE,eAAe,CAAC,KAAK,CAAC,KAAK,GAC5B,IAAI,CACF,eAAe,CAAC,UAAU,CAAC,KAAK,EAChC,OAAO,GAAG,aAAa,GAAG,MAAM,GAAG,YAAY,GAAG,sBAAsB,CACzE,qBA4BF;AAED,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,eAAe,CAAC,UAAU,CAAC,KAAK,qBAQ7E;AAED,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,eAAe,CAAC,IAAI,CAAC,KAAK,qBAsBhF;AAED,iBAAS,eAAe,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,eAAe,CAAC,SAAS,CAAC,KAAK,qBAQhF;AAED,iBAAS,oBAAoB,CAAC,EAC5B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,aAAa,CAAC,qBAa5D;AAED,iBAAS,sBAAsB,CAAC,EAC9B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,eAAe,CAAC,qBAa9D;AAED,OAAO,EACL,MAAM,EACN,aAAa,EACb,WAAW,EACX,UAAU,EACV,WAAW,EACX,sBAAsB,EACtB,oBAAoB,EACpB,eAAe,EACf,aAAa,EACb,WAAW,GACZ,CAAC"}
+{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../src/components/select.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,MAAM,IAAI,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAMlE;;;;;;;;;;;;;;;GAeG;AACH,QAAA,MAAM,MAAM,6BAAuB,CAAC;AAEpC,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,eAAe,CAAC,KAAK,CAAC,KAAK,qBAQxE;AAED,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,eAAe,CAAC,KAAK,CAAC,KAAK,qBAQxE;AAED,iBAAS,aAAa,CAAC,EACrB,SAAS,EACT,IAAgB,EAChB,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,eAAe,CAAC,OAAO,CAAC,KAAK,GAAG;IACjC,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;CACzB,qBAiBA;AAED,iBAAS,aAAa,CAAC,EACrB,SAAS,EACT,QAAQ,EACR,IAAe,EACf,UAAc,EACd,KAAgB,EAChB,WAAe,EACf,oBAA2B,EAC3B,GAAG,KAAK,EACT,EAAE,eAAe,CAAC,KAAK,CAAC,KAAK,GAC5B,IAAI,CACF,eAAe,CAAC,UAAU,CAAC,KAAK,EAChC,OAAO,GAAG,aAAa,GAAG,MAAM,GAAG,YAAY,GAAG,sBAAsB,CACzE,qBA4BF;AAED,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,eAAe,CAAC,UAAU,CAAC,KAAK,qBAQ7E;AAED,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,eAAe,CAAC,IAAI,CAAC,KAAK,qBAsBhF;AAED,iBAAS,eAAe,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,eAAe,CAAC,SAAS,CAAC,KAAK,qBAQhF;AAED,iBAAS,oBAAoB,CAAC,EAC5B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,aAAa,CAAC,qBAa5D;AAED,iBAAS,sBAAsB,CAAC,EAC9B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,eAAe,CAAC,qBAa9D;AAED,OAAO,EACL,MAAM,EACN,aAAa,EACb,WAAW,EACX,UAAU,EACV,WAAW,EACX,sBAAsB,EACtB,oBAAoB,EACpB,eAAe,EACf,aAAa,EACb,WAAW,GACZ,CAAC"}

package/dist/components/select.js

@@ -4,6 +4,22 @@ import { Select as SelectPrimitive } from "@base-ui/react/select";
 import { cn } from "../lib/utils.js";
 import { anchoredOverlayMotion } from "../lib/motion.js";
 import { ChevronDownIcon, CheckIcon, ChevronUpIcon } from "lucide-react";
+/**
+ * A short fixed list in our style, opened from a trigger that shows the choice.
+ *
+ * @family Choices
+ * @when Four to about ten fixed options in our style, each short enough to need no sentence: how
+ * often a task runs.
+ * @instead Two or three options are radios or a segmented control. A list to type into is a
+ * `Combobox`. Inside a native form a long list is `NativeSelect`.
+ * @behaviour The trigger shows the chosen value; the list floats under it with 12 px corners and a
+ * check at the chosen row's end. Arrows, typing, Enter, Escape. A placeholder reads in the muted
+ * grey and is never an option.
+ * @words Options are parallel phrases in sentence case: *Every hour*, *Every weekday*. The trigger
+ * never says *Select…*.
+ * @access A visible label tied to the trigger; listbox and option roles from Base UI; focus returns
+ * to the trigger on close.
+ */
 const Select = SelectPrimitive.Root;
 function SelectGroup({ className, ...props }) {
     return (_jsx(SelectPrimitive.Group, { "data-slot": "select-group", className: cn("scroll-my-1 p-nadicode-xxs", className), ...props }));

package/dist/components/separator.d.ts

@@ -1,4 +1,15 @@
 import { Separator as SeparatorPrimitive } from "@base-ui/react/separator";
+/**
+ * A 1 px line between groups.
+ *
+ * @family Other
+ * @when Separating groups inside one surface: menu sections, a card's header from its toolbar.
+ * @instead A card's footer draws its own seam; a list in a card is a `divided` `ItemGroup`. Never a
+ * border around a region.
+ * @behaviour Horizontal or vertical, in the line colour.
+ * @words None.
+ * @access A `separator` from Base UI with no name of its own.
+ */
 declare function Separator({ className, orientation, ...props }: SeparatorPrimitive.Props): import("react").JSX.Element;
 export { Separator };
 //# sourceMappingURL=separator.d.ts.map

package/dist/components/separator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"separator.d.ts","sourceRoot":"","sources":["../../src/components/separator.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,IAAI,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAI3E,iBAAS,SAAS,CAAC,EAAE,SAAS,EAAE,WAA0B,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,CAAC,KAAK,+BAY/F;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"separator.d.ts","sourceRoot":"","sources":["../../src/components/separator.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,IAAI,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAI3E;;;;;;;;;;GAUG;AACH,iBAAS,SAAS,CAAC,EAAE,SAAS,EAAE,WAA0B,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,CAAC,KAAK,+BAY/F;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/components/separator.js

@@ -1,6 +1,17 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Separator as SeparatorPrimitive } from "@base-ui/react/separator";
 import { cn } from "../lib/utils.js";
+/**
+ * A 1 px line between groups.
+ *
+ * @family Other
+ * @when Separating groups inside one surface: menu sections, a card's header from its toolbar.
+ * @instead A card's footer draws its own seam; a list in a card is a `divided` `ItemGroup`. Never a
+ * border around a region.
+ * @behaviour Horizontal or vertical, in the line colour.
+ * @words None.
+ * @access A `separator` from Base UI with no name of its own.
+ */
 function Separator({ className, orientation = "horizontal", ...props }) {
     return (_jsx(SeparatorPrimitive, { "data-slot": "separator", orientation: orientation, className: cn("shrink-0 bg-border data-horizontal:h-px data-horizontal:w-full data-vertical:w-px data-vertical:self-stretch", className), ...props }));
 }

package/dist/components/settings-facts.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { type ComponentPropsWithoutRef, type ReactNode } from "react";
 import { Card, type CardSurface } from "./card.js";
 export type SettingsFact = {
     /**
@@ -30,5 +30,22 @@ export type SettingsFactsSectionProps = Omit<ComponentPropsWithoutRef<"section">
      */
     size?: ComponentPropsWithoutRef<typeof Card>["size"];
 };
+/**
+ * Read-only facts about one object, framed as a card with a title and one action.
+ *
+ * @family Data
+ * @when Read-only facts about one object: who it is, where it belongs, its identifiers.
+ * `SettingsFactsSection` frames them as a card with a title and one action; `ObjectFacts` is the
+ * list alone.
+ * @instead Facts a person changes are a `SettingsSection` with its own Save. Facts compared across
+ * records are a table. A relation is its identity or a `Tag`, never its own card.
+ * @behaviour Label above value, two equal columns, one column on a phone. Every label stays when
+ * its value is missing, as *—*. A long value spans both columns. No fact gets a box of its own. In
+ * a side column, `presentation="summary"` drops the card.
+ * @words Labels are nouns, sentence case, no colon: *VAT number*. Values are exact: identifiers in
+ * mono with a copy button, dates in the person's locale.
+ * @access A `dl` of `dt` and `dd`, each value named by its label. The section is labelled by its heading, which also takes focus
+ * when an editor closes. A dash carries screen-reader text.
+ */
 export declare function SettingsFactsSection({ action, presentation, description, facts, footer, missingValueLabel, headingId, title, surface, size, ...props }: SettingsFactsSectionProps): import("react").JSX.Element;
 //# sourceMappingURL=settings-facts.d.ts.map

package/dist/components/settings-facts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings-facts.d.ts","sourceRoot":"","sources":["../../src/components/settings-facts.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAKjE,OAAO,EACL,IAAI,EAOJ,KAAK,WAAW,EACjB,MAAM,QAAQ,CAAC;AAEhB,MAAM,MAAM,YAAY,GAAG;IACzB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC1C,wBAAwB,CAAC,SAAS,CAAC,EACnC,UAAU,GAAG,WAAW,CACzB,GAAG;IACF,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IAC/B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,IAAI,CAAC,EAAE,wBAAwB,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC;CACtD,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,EACnC,MAAM,EACN,YAAqB,EACrB,WAAW,EACX,KAAK,EACL,MAAM,EACN,iBAAiB,EACjB,SAAS,EACT,KAAK,EACL,OAAmB,EACnB,IAAgB,EAChB,GAAG,KAAK,EACT,EAAE,yBAAyB,+BA4D3B"}
+{"version":3,"file":"settings-facts.d.ts","sourceRoot":"","sources":["../../src/components/settings-facts.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,wBAAwB,EAAE,KAAK,SAAS,EAAS,MAAM,OAAO,CAAC;AAK7E,OAAO,EACL,IAAI,EAOJ,KAAK,WAAW,EACjB,MAAM,QAAQ,CAAC;AAEhB,MAAM,MAAM,YAAY,GAAG;IACzB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC1C,wBAAwB,CAAC,SAAS,CAAC,EACnC,UAAU,GAAG,WAAW,CACzB,GAAG;IACF,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IAC/B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,IAAI,CAAC,EAAE,wBAAwB,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC;CACtD,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,MAAM,EACN,YAAqB,EACrB,WAAW,EACX,KAAK,EACL,MAAM,EACN,iBAAiB,EACjB,SAAS,EACT,KAAK,EACL,OAAmB,EACnB,IAAgB,EAChB,GAAG,KAAK,EACT,EAAE,yBAAyB,+BA+D3B"}

package/dist/components/settings-facts.js

@@ -1,10 +1,29 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
 import { ObjectFacts } from "./object-workspace.js";
 import { TableValue } from "./table-value.js";
 import { Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, } from "./card.js";
+/**
+ * Read-only facts about one object, framed as a card with a title and one action.
+ *
+ * @family Data
+ * @when Read-only facts about one object: who it is, where it belongs, its identifiers.
+ * `SettingsFactsSection` frames them as a card with a title and one action; `ObjectFacts` is the
+ * list alone.
+ * @instead Facts a person changes are a `SettingsSection` with its own Save. Facts compared across
+ * records are a table. A relation is its identity or a `Tag`, never its own card.
+ * @behaviour Label above value, two equal columns, one column on a phone. Every label stays when
+ * its value is missing, as *—*. A long value spans both columns. No fact gets a box of its own. In
+ * a side column, `presentation="summary"` drops the card.
+ * @words Labels are nouns, sentence case, no colon: *VAT number*. Values are exact: identifiers in
+ * mono with a copy button, dates in the person's locale.
+ * @access A `dl` of `dt` and `dd`, each value named by its label. The section is labelled by its heading, which also takes focus
+ * when an editor closes. A dash carries screen-reader text.
+ */
 export function SettingsFactsSection({ action, presentation = "card", description, facts, footer, missingValueLabel, headingId, title, surface = "resting", size = "default", ...props }) {
+    const termId = useId();
     if (presentation === "summary") {
-        return (_jsxs("section", { ...props, "aria-labelledby": headingId, className: "grid min-w-0 gap-3", children: [_jsxs("div", { className: "flex flex-wrap items-center justify-between gap-3", children: [_jsx("h2", { id: headingId, tabIndex: -1, className: "text-sm font-medium", children: title }), action] }), description ? _jsx("p", { className: "text-sm text-muted-foreground", children: description }) : null, _jsx("dl", { className: "flex flex-wrap items-start gap-x-6 gap-y-3", children: facts.map((fact) => (_jsxs("div", { className: "grid gap-1", children: [_jsx("dt", { className: "text-xs text-muted-foreground", children: fact.label }), _jsx("dd", { className: "text-sm", children: fact.value ?? _jsx(TableValue, { missingLabel: missingValueLabel, value: null }) })] }, fact.label))) }), footer] }));
+        return (_jsxs("section", { ...props, "aria-labelledby": headingId, className: "grid min-w-0 gap-3", children: [_jsxs("div", { className: "flex flex-wrap items-center justify-between gap-3", children: [_jsx("h2", { id: headingId, tabIndex: -1, className: "text-sm font-medium", children: title }), action] }), description ? _jsx("p", { className: "text-sm text-muted-foreground", children: description }) : null, _jsx("dl", { className: "flex flex-wrap items-start gap-x-6 gap-y-3", children: facts.map((fact, index) => (_jsxs("div", { className: "grid gap-1", children: [_jsx("dt", { className: "text-xs text-muted-foreground", id: `${termId}-${index}`, children: fact.label }), _jsx("dd", { "aria-labelledby": `${termId}-${index}`, className: "text-sm", children: fact.value ?? _jsx(TableValue, { missingLabel: missingValueLabel, value: null }) })] }, fact.label))) }), footer] }));
     }
     return (_jsxs(Card, { render: _jsx("section", {}), ...props, "aria-labelledby": headingId, surface: surface, size: size, className: "min-w-0", children: [_jsxs(CardHeader, { children: [_jsx(CardTitle, { children: _jsx("h2", { id: headingId, tabIndex: -1, children: title }) }), description ? _jsx(CardDescription, { children: description }) : null, action ? _jsx(CardAction, { children: action }) : null] }), _jsx(CardContent, { children: _jsx(ObjectFacts, { facts: facts.map((fact) => ({
                         label: fact.label,

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

@@ -0,0 +1,20 @@
+import type { ComponentProps, ReactElement, ReactNode } from "react";
+export type SettingsPageProps = {
+    /** A screen-reader h1, where the product's chrome does not draw one: the path already names the place. */
+    title?: string;
+    headingProps?: Omit<ComponentProps<"h1">, "children">;
+    /** The section cards, in order: SettingsSection, SettingsFactsSection. */
+    children: ReactNode;
+};
+/**
+ * A page of settings: a centred column of section cards, each saving its own values.
+ *
+ * @family Compositions
+ * @when A place whose job is changing how something behaves: an account's profile, a company's identity, Nadia's notifications.
+ * @instead One object's page with a settings card among its sections is an ObjectPage; Theme and Language, which apply on change, stay in the account menu.
+ * @behaviour The sections stack 20 apart in a centred column at most 56rem wide. The page draws no header and no save of its own: each SettingsSection saves from its footer.
+ * @words `title` names the place as the navigation does ("Profile"); the sections' titles and lines carry the rest.
+ * @access `title` becomes a visually hidden h1 for a product whose chrome shows the place without a heading; leave it out where the chrome already draws the h1.
+ */
+export declare function SettingsPage({ title, headingProps, children }: SettingsPageProps): ReactElement;
+//# sourceMappingURL=settings-page.d.ts.map

package/dist/components/settings-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-page.d.ts","sourceRoot":"","sources":["../../src/components/settings-page.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAKrE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,0GAA0G;IAC1G,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC;IACtD,0EAA0E;IAC1E,QAAQ,EAAE,SAAS,CAAC;CACrB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,EAAE,iBAAiB,GAAG,YAAY,CAW/F"}

package/dist/components/settings-page.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../lib/utils.js";
+import { ReadingColumn } from "./reading-column.js";
+/**
+ * A page of settings: a centred column of section cards, each saving its own values.
+ *
+ * @family Compositions
+ * @when A place whose job is changing how something behaves: an account's profile, a company's identity, Nadia's notifications.
+ * @instead One object's page with a settings card among its sections is an ObjectPage; Theme and Language, which apply on change, stay in the account menu.
+ * @behaviour The sections stack 20 apart in a centred column at most 56rem wide. The page draws no header and no save of its own: each SettingsSection saves from its footer.
+ * @words `title` names the place as the navigation does ("Profile"); the sections' titles and lines carry the rest.
+ * @access `title` becomes a visually hidden h1 for a product whose chrome shows the place without a heading; leave it out where the chrome already draws the h1.
+ */
+export function SettingsPage({ title, headingProps, children }) {
+    return (_jsxs(ReadingColumn, { className: "gap-5", width: "configuration", children: [title ? (_jsx("h1", { ...headingProps, className: cn("sr-only", headingProps?.className), children: title })) : null, children] }));
+}

package/dist/components/settings-section.d.ts

@@ -1,6 +1,7 @@
 import * as React from "react";
-import { type CardSurface } from "./card.js";
+import { type SettingsSave } from "../internal/settings-save.js";
 import { Field } from "./field.js";
+export type { SettingsSave, SettingsSaveFailure } from "../internal/settings-save.js";
 export type SettingsFieldControlProps = {
     id: string;
     "aria-invalid"?: true;
@@ -8,16 +9,45 @@ export type SettingsFieldControlProps = {
     disabled?: boolean;
     required?: boolean;
 };
-declare function SettingsSection({ title, description, actions, footer, footerHint, children, className, surface, presentation, columns, ...props }: Omit<React.ComponentProps<"section">, "title"> & {
-    title?: React.ReactNode;
-    description?: React.ReactNode;
+export type SettingsSectionProps = Omit<React.ComponentProps<"section">, "title" | "children"> & {
+    title: string;
+    /** One line saying what changing it does. */
+    description: string;
+    /** A control on the section's own header: an avatar's upload, a state. */
     actions?: React.ReactNode;
+    /** Two columns where related fields fit. */
+    columns?: 1 | 2;
+    children?: React.ReactNode;
+} & ({
+    save: SettingsSave;
+    footer?: never;
+    footerHint?: never;
+} | {
+    save?: never;
     footer?: React.ReactNode;
     footerHint?: React.ReactNode;
-    surface?: CardSurface;
-    presentation?: "split" | "form";
-    columns?: 1 | 2;
-}): React.JSX.Element;
+});
+/**
+ * A card of related settings that says what changing them does and saves them from its own footer.
+ *
+ * @family Compositions
+ * @when A few related values a person changes and saves together, on a SettingsPage or as a section of an ObjectPage: Personal details, Company identity, Notifications.
+ * @instead Read-only values are a SettingsFactsSection; Theme and Language, which apply on change, live in the account menu; a record's edit in a list is a RowEditForm.
+ * @behaviour With `save`: Save stays disabled until a field differs from what is saved, says `pendingLabel` while saving with Cancel held beside it, then the footer shows the ok check and `savedLabel` until the next change. A failure keeps every value and shows under its field until that field changes, or above the footer until the next save. A `cancel` that runs work of its own says its `pendingLabel` while `pending`. Without `save`, the footer holds `footerHint` and `footer`, and is left out when both are.
+ * @words The title names the values ("Personal details"); the description says what changing them does, in one line; the hint says where the save applies ("Saved for every device you sign in on."); Save, Saving and Saved come from the product's catalogue.
+ * @access The title is the section's h2 and names the form that saves it. The footer's hint and saved line are one status, announced politely; a failure under a field marks the control invalid and describes it.
+ */
+declare function SettingsSection({ title, description, actions, columns, children, className, save, footer, footerHint, ...props }: SettingsSectionProps): React.JSX.Element;
+/**
+ * One setting: its label and help above its control, and what went wrong under it.
+ *
+ * @family Inputs
+ * @when A value inside a SettingsSection: a name, an address, a choice, a switch.
+ * @instead A field of a drawer's or a dialog's form is a Field from the form's own owner; a read-only value is a fact in a SettingsFactsSection.
+ * @behaviour The control is 20rem wide under its label and help by default; a switch row passes `orientation="horizontal"` and sits at the end of its label's row at its own width. A validation `error`, or a failed save about this field, shows under the control and marks it invalid.
+ * @words The label is a noun for the value ("Display name"); the help is one line saying what it is for or where it shows; an error says what to do next.
+ * @access The control receives its id, `aria-invalid` and `aria-describedby` through `controlProps`, so the label, help and error are read with it.
+ */
 declare function SettingsField({ id, label, description, error, invalid, disabled, required, orientation, children, className, contentClassName, controlClassName, controlWidth, ...props }: Omit<React.ComponentProps<typeof Field>, "children"> & {
     id: string;
     label: React.ReactNode;

package/dist/components/settings-section.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings-section.d.ts","sourceRoot":"","sources":["../../src/components/settings-section.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,OAAO,EAOL,KAAK,WAAW,EACjB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,KAAK,EAMN,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,yBAAyB,GAAG;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,CAAC,EAAE,IAAI,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,iBAAS,eAAe,CAAC,EACvB,KAAK,EACL,WAAW,EACX,OAAO,EACP,MAAM,EACN,UAAU,EACV,QAAQ,EACR,SAAS,EACT,OAAmB,EACnB,YAAsB,EACtB,OAAW,EACX,GAAG,KAAK,EACT,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,GAAG;IAClD,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC9B,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,MAAM,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACzB,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC7B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAChC,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;CACjB,qBAwCA;AAED,iBAAS,aAAa,CAAC,EACrB,EAAE,EACF,KAAK,EACL,WAAW,EACX,KAAK,EACL,OAAwB,EACxB,QAAQ,EACR,QAAQ,EACR,WAA0B,EAC1B,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,YAAwB,EACxB,GAAG,KAAK,EACT,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,KAAK,CAAC,EAAE,UAAU,CAAC,GAAG;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC;IACvB,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC9B,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,YAAY,EAAE,yBAAyB,CAAA;KAAE,KAAK,KAAK,CAAC,SAAS,CAAC;IAClF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;CAChD,qBA+CA;AAED,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"settings-section.d.ts","sourceRoot":"","sources":["../../src/components/settings-section.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,KAAK,EAMN,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAElF,MAAM,MAAM,yBAAyB,GAAG;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,CAAC,EAAE,IAAI,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC,GAAG;IAC/F,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,4CAA4C;IAC5C,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAChB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,GAAG,CACE;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,GAC1D;IAAE,IAAI,CAAC,EAAE,KAAK,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,CAC3E,CAAC;AAEJ;;;;;;;;;GASG;AACH,iBAAS,eAAe,CAAC,EACvB,KAAK,EACL,WAAW,EACX,OAAO,EACP,OAAW,EACX,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,MAAM,EACN,UAAU,EACV,GAAG,KAAK,EACT,EAAE,oBAAoB,qBAwCtB;AAED;;;;;;;;;GASG;AACH,iBAAS,aAAa,CAAC,EACrB,EAAE,EACF,KAAK,EACL,WAAW,EACX,KAAK,EACL,OAAwB,EACxB,QAAQ,EACR,QAAQ,EACR,WAAwB,EACxB,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,YAAoE,EACpE,GAAG,KAAK,EACT,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,KAAK,CAAC,EAAE,UAAU,CAAC,GAAG;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC;IACvB,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC9B,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,YAAY,EAAE,yBAAyB,CAAA;KAAE,KAAK,KAAK,CAAC,SAAS,CAAC;IAClF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;CAChD,qBAyDA;AAED,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC"}