@nadicodeai/ui 12.1.96 → 12.1.98

package/dist/components/label-system.d.ts

@@ -1,4 +1,16 @@
 import * as React from "react";
+/**
+ * A small muted label of metadata, and its mono sibling for a command's suffix.
+ *
+ * @family Status
+ * @when A short fixed fact set beside a name in dense chrome: *Built in*, *Read only*.
+ * `CommandSuffix` holds a count or a key after a command.
+ * @instead A state is `StatusBadge`; a category is `Tag`; a plan or role is `Badge`. A bound
+ * shortcut is `Kbd`.
+ * @behaviour 20 px, 6 px corners, the muted fill, never interactive, never wraps.
+ * @words One or two words in sentence case.
+ * @access Read in place as text.
+ */
 declare function MetaLabel({ className, ...props }: React.ComponentProps<"span">): React.JSX.Element;
 declare function CommandSuffix({ className, ...props }: React.ComponentProps<"span">): React.JSX.Element;
 export { CommandSuffix, MetaLabel };

package/dist/components/label-system.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"label-system.d.ts","sourceRoot":"","sources":["../../src/components/label-system.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,iBAAS,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,qBAWvE;AAED,iBAAS,aAAa,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,qBAW3E;AAED,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"label-system.d.ts","sourceRoot":"","sources":["../../src/components/label-system.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B;;;;;;;;;;;GAWG;AACH,iBAAS,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,qBAWvE;AAED,iBAAS,aAAa,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,qBAW3E;AAED,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC"}

package/dist/components/label-system.js

@@ -1,5 +1,17 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cn } from "../lib/utils.js";
+/**
+ * A small muted label of metadata, and its mono sibling for a command's suffix.
+ *
+ * @family Status
+ * @when A short fixed fact set beside a name in dense chrome: *Built in*, *Read only*.
+ * `CommandSuffix` holds a count or a key after a command.
+ * @instead A state is `StatusBadge`; a category is `Tag`; a plan or role is `Badge`. A bound
+ * shortcut is `Kbd`.
+ * @behaviour 20 px, 6 px corners, the muted fill, never interactive, never wraps.
+ * @words One or two words in sentence case.
+ * @access Read in place as text.
+ */
 function MetaLabel({ className, ...props }) {
     return (_jsx("span", { "data-slot": "meta-label", className: cn("inline-flex h-5 w-fit shrink-0 items-center justify-center rounded-sm border border-border bg-muted/40 px-2 text-xs font-medium text-muted-foreground whitespace-nowrap", className), ...props }));
 }

package/dist/components/label.d.ts

@@ -1,4 +1,19 @@
 import * as React from "react";
+/**
+ * The visible name of one control.
+ *
+ * @family Inputs
+ * @when A control standing on its own that needs a visible name: a checkbox's sentence, a switch's
+ * setting.
+ * @instead A control inside a form takes `FieldLabel` through `Field`; a group of controls takes
+ * `FieldLegend`. A short tag of metadata is `MetaLabel`.
+ * @behaviour Sits beside or above its control and dims with it when the control is disabled.
+ * Clicking it moves to its control.
+ * @words A noun or a positive statement in sentence case, no colon: *Approvals*, *Send a copy to
+ * the person who asked*.
+ * @access A `label` tied to its control by `htmlFor`. Never replaced by a placeholder or overridden
+ * by another `aria-label`.
+ */
 declare function Label({ className, ...props }: React.ComponentProps<"label">): React.JSX.Element;
 export { Label };
 //# sourceMappingURL=label.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"label.d.ts","sourceRoot":"","sources":["../../src/components/label.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,iBAAS,KAAK,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,qBAWpE;AAED,OAAO,EAAE,KAAK,EAAE,CAAC"}
+{"version":3,"file":"label.d.ts","sourceRoot":"","sources":["../../src/components/label.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B;;;;;;;;;;;;;;GAcG;AACH,iBAAS,KAAK,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,qBAWpE;AAED,OAAO,EAAE,KAAK,EAAE,CAAC"}

package/dist/components/label.js

@@ -1,6 +1,21 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cn } from "../lib/utils.js";
+/**
+ * The visible name of one control.
+ *
+ * @family Inputs
+ * @when A control standing on its own that needs a visible name: a checkbox's sentence, a switch's
+ * setting.
+ * @instead A control inside a form takes `FieldLabel` through `Field`; a group of controls takes
+ * `FieldLegend`. A short tag of metadata is `MetaLabel`.
+ * @behaviour Sits beside or above its control and dims with it when the control is disabled.
+ * Clicking it moves to its control.
+ * @words A noun or a positive statement in sentence case, no colon: *Approvals*, *Send a copy to
+ * the person who asked*.
+ * @access A `label` tied to its control by `htmlFor`. Never replaced by a placeholder or overridden
+ * by another `aria-label`.
+ */
 function Label({ className, ...props }) {
     return (_jsx("label", { "data-slot": "label", className: cn("flex items-center gap-2 text-label font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50", className), ...props }));
 }

package/dist/components/library-shelf.d.ts

@@ -0,0 +1,35 @@
+import type { ReactElement, ReactNode } from "react";
+import type { CatalogSection } from "./catalog-entry.js";
+import { type CollectionSearchProps } from "./collection-search.js";
+import { type EmptyStateKind } from "./empty-state.js";
+export type LibraryShelfProps = {
+    /** The one line under the shelf's title saying what it holds. */
+    definition: string;
+    /** Above the search, for the people who keep the shelf: the hub's sync. */
+    notice?: ReactNode;
+    search?: CollectionSearchProps;
+    loadingLabel: string;
+    empty: EmptyStateKind<"firstUse"> | EmptyStateKind<"nothingYet">;
+    /** Offered only while the search holds text; otherwise a shelf with nothing in it is `empty`. */
+    noMatch?: Omit<EmptyStateKind<"noResults">, "kind">;
+    failed?: EmptyStateKind<"failed">;
+} & ({
+    sections: readonly CatalogSection[] | undefined;
+}
+/** The Agent templates shelf: AgentCard elements, three to a row. */
+ | {
+    templates: readonly ReactElement[] | undefined;
+});
+/**
+ * A Library shelf: the one line saying what it holds, the search, then the
+ * reusable things a person adds, as two-column entries or Agent template cards.
+ *
+ * @family Compositions
+ * @when A page of reusable things a person adds to an Agent: Skills, Plugins, Agent templates.
+ * @instead Records a person already has and acts on are a CollectionPage; choosing from a catalogue without leaving the page is a CatalogDrawer.
+ * @behaviour Shows, the first that holds: the failure; still entries while the shelf loads; noMatch while the search finds nothing; empty when the shelf holds nothing; then each section's title over its entries, two to a row from md, or the templates three to a row. Each entry has its kind's tile, its name (the link to its page), one line, one fact, one Add control or the word saying it is already added, then its menu. A failed add puts its message in the entry's line and its next steps beside its controls. The search shows unless the shelf is empty.
+ * @words The product words every string: the definition (one sentence on what the shelf holds), the search's label ("Search skills"), the loading label, each entry's name, line, Add label and added word, the empty, noMatch and failed messages.
+ * @access Each section is a region named by its h2; entries are list items; loading is a status named by loadingLabel and aria-busy; a failed add is announced as an alert; each entry's menu is named by its label.
+ */
+export declare function LibraryShelf(props: LibraryShelfProps): import("react").JSX.Element;
+//# sourceMappingURL=library-shelf.d.ts.map

package/dist/components/library-shelf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"library-shelf.d.ts","sourceRoot":"","sources":["../../src/components/library-shelf.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEjE,OAAO,EAAoB,KAAK,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAC9F,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG3E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;IACjE,iGAAiG;IACjG,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC;IACpD,MAAM,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;CACnC,GAAG,CACA;IAAE,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,CAAA;CAAE;AACrD,qEAAqE;GACnE;IAAE,SAAS,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,CAAA;CAAE,CACrD,CAAC;AA0BF;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,+BAyBpD"}

package/dist/components/library-shelf.js

@@ -0,0 +1,40 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CardRow } from "./card-row.js";
+import { CollectionSearch } from "./collection-search.js";
+import { EmptyState } from "./empty-state.js";
+import { CatalogList, CatalogSkeleton, catalogIsEmpty } from "../internal/catalog-list.js";
+function loadedShelf(props) {
+    if ("sections" in props)
+        return props.sections && { sections: props.sections };
+    return props.templates && { templates: props.templates };
+}
+function holdsNothing(shelf) {
+    return "sections" in shelf ? catalogIsEmpty(shelf.sections) : shelf.templates.length === 0;
+}
+function ShelfContents({ shelf }) {
+    if ("sections" in shelf) {
+        return _jsx(CatalogList, { columns: 2, headingLevel: 2, sections: shelf.sections });
+    }
+    return (_jsx(CardRow, { className: "gap-3", columns: 3, render: _jsx("ul", {}), children: shelf.templates.map((template, index) => (_jsx("li", { children: template }, template.key ?? index))) }));
+}
+/**
+ * A Library shelf: the one line saying what it holds, the search, then the
+ * reusable things a person adds, as two-column entries or Agent template cards.
+ *
+ * @family Compositions
+ * @when A page of reusable things a person adds to an Agent: Skills, Plugins, Agent templates.
+ * @instead Records a person already has and acts on are a CollectionPage; choosing from a catalogue without leaving the page is a CatalogDrawer.
+ * @behaviour Shows, the first that holds: the failure; still entries while the shelf loads; noMatch while the search finds nothing; empty when the shelf holds nothing; then each section's title over its entries, two to a row from md, or the templates three to a row. Each entry has its kind's tile, its name (the link to its page), one line, one fact, one Add control or the word saying it is already added, then its menu. A failed add puts its message in the entry's line and its next steps beside its controls. The search shows unless the shelf is empty.
+ * @words The product words every string: the definition (one sentence on what the shelf holds), the search's label ("Search skills"), the loading label, each entry's name, line, Add label and added word, the empty, noMatch and failed messages.
+ * @access Each section is a region named by its h2; entries are list items; loading is a status named by loadingLabel and aria-busy; a failed add is announced as an alert; each entry's menu is named by its label.
+ */
+export function LibraryShelf(props) {
+    const { definition, empty, failed, loadingLabel, notice, search } = props;
+    const noMatch = search?.value ? props.noMatch : undefined;
+    const shelf = loadedShelf(props);
+    const nothing = shelf !== undefined && holdsNothing(shelf);
+    const body = failed ? (_jsx(EmptyState, { ...failed, scope: "page" })) : !shelf ? (_jsx(CatalogSkeleton, { columns: 2, label: loadingLabel })) : nothing && noMatch ? (_jsx(EmptyState, { kind: "noResults", ...noMatch, scope: "page" })) : nothing ? (_jsx(EmptyState, { ...empty, scope: "page" })) : (_jsx(ShelfContents, { shelf: shelf }));
+    const showsEmpty = !failed && nothing && !noMatch;
+    return (_jsxs("div", { className: "grid min-w-0 gap-6", "data-slot": "library-shelf", children: [_jsx("p", { className: "text-body-md text-muted-foreground", children: definition }), notice, search && !showsEmpty ? _jsx(CollectionSearch, { ...search }) : null, body] }));
+}

package/dist/components/memory-item.d.ts

@@ -1,4 +1,16 @@
 import * as React from "react";
+/**
+ * One fact an Agent keeps, under its muted label.
+ *
+ * @family Data
+ * @when A fact from an Agent's memory shown in her conversation or her profile.
+ * @instead A fact about a record is `ObjectFacts`. A note a person writes is a `Textarea`.
+ * @behaviour A short label over the fact; `children` replace the plain `fact` when it needs rich
+ * content.
+ * @words The label is the product's word for memory from the catalogue; the fact is in the Agent's
+ * own words.
+ * @access Read in place as text.
+ */
 declare function MemoryItem({ className, label, fact, children, ...props }: Omit<React.ComponentProps<"div">, "children"> & {
     label?: string;
     fact?: string;

package/dist/components/memory-item.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-item.d.ts","sourceRoot":"","sources":["../../src/components/memory-item.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,iBAAS,UAAU,CAAC,EAClB,SAAS,EACT,KAAgB,EAChB,IAAI,EACJ,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,GAAG;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,qBAOA;AAED,OAAO,EAAE,UAAU,EAAE,CAAC"}
+{"version":3,"file":"memory-item.d.ts","sourceRoot":"","sources":["../../src/components/memory-item.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B;;;;;;;;;;;GAWG;AACH,iBAAS,UAAU,CAAC,EAClB,SAAS,EACT,KAAgB,EAChB,IAAI,EACJ,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,GAAG;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,qBAOA;AAED,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/components/memory-item.js

@@ -1,5 +1,17 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cn } from "../lib/utils.js";
+/**
+ * One fact an Agent keeps, under its muted label.
+ *
+ * @family Data
+ * @when A fact from an Agent's memory shown in her conversation or her profile.
+ * @instead A fact about a record is `ObjectFacts`. A note a person writes is a `Textarea`.
+ * @behaviour A short label over the fact; `children` replace the plain `fact` when it needs rich
+ * content.
+ * @words The label is the product's word for memory from the catalogue; the fact is in the Agent's
+ * own words.
+ * @access Read in place as text.
+ */
 function MemoryItem({ className, label = "Memory", fact, children, ...props }) {
     return (_jsxs("div", { "data-slot": "memory-item", className: cn("nc-memory-item", className), ...props, children: [_jsx("span", { className: "nc-memory-item-label", children: label }), _jsx("span", { children: children ?? fact })] }));
 }

package/dist/components/menu-choice-row.d.ts

@@ -8,17 +8,25 @@ export type MenuChoiceOption<Value extends string = string> = {
 };
 export type MenuChoiceRowProps<Value extends string = string> = Omit<React.ComponentProps<"div">, "children" | "onChange"> & {
     label: string;
+    /** Leads the label, so the row starts on the commands' line: the current theme's glyph. */
+    icon?: React.ReactElement | undefined;
     options: readonly MenuChoiceOption<Value>[];
     onValueChange: (value: Value) => void;
     value: Value;
     disabled?: boolean;
 };
 /**
- * A named preference inside a menu: the label reads at the leading edge and the
- * exclusive choices sit together at the trailing edge, close enough to read as
- * one control. Selecting keeps the menu open, so a reader can see the result
- * without reopening it.
+ * A named preference inside a menu: its icon and label at the leading edge, the
+ * exclusive choices together at the trailing edge, close enough to read as one
+ * control.
+ *
+ * @family Menus
+ * @when A setting that applies at once from inside a menu: the account menu's Theme and Language.
+ * @instead A product's own setting with more choices or longer names is a submenu of radio items (`AccountMenu`'s `choices`). A setting on a page is a `ToggleGroup` or a `Select` in its section.
+ * @behaviour Icon and label lead, on the commands' 12 px line; the choices sit in one bordered group at the trailing edge. Choosing applies at once and keeps the menu open, so the result shows without reopening it.
+ * @words The label is a noun: "Theme", "Language". Each choice carries a full name even when it shows a glyph or a short code: "EN" is named "English".
+ * @access A radio group named by the label; each choice is a radio named by its `label`, with the same text as its tooltip. The icon is hidden.
  */
-declare function MenuChoiceRow<Value extends string = string>({ className, disabled, label, onValueChange, options, value, ...props }: MenuChoiceRowProps<Value>): React.JSX.Element;
+declare function MenuChoiceRow<Value extends string = string>({ className, disabled, icon, label, onValueChange, options, value, ...props }: MenuChoiceRowProps<Value>): React.JSX.Element;
 export { MenuChoiceRow };
 //# sourceMappingURL=menu-choice-row.d.ts.map

package/dist/components/menu-choice-row.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"menu-choice-row.d.ts","sourceRoot":"","sources":["../../src/components/menu-choice-row.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B,MAAM,MAAM,gBAAgB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,IAAI;IAC5D,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC;IACzB,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,kBAAkB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,IAAI,IAAI,CAClE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,EAC3B,UAAU,GAAG,UAAU,CACxB,GAAG;IACF,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;IAC5C,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACtC,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;;;GAKG;AACH,iBAAS,aAAa,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,EAAE,EACpD,SAAS,EACT,QAAQ,EACR,KAAK,EACL,aAAa,EACb,OAAO,EACP,KAAK,EACL,GAAG,KAAK,EACT,EAAE,kBAAkB,CAAC,KAAK,CAAC,qBAoC3B;AAED,OAAO,EAAE,aAAa,EAAE,CAAC"}
+{"version":3,"file":"menu-choice-row.d.ts","sourceRoot":"","sources":["../../src/components/menu-choice-row.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B,MAAM,MAAM,gBAAgB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,IAAI;IAC5D,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC;IACzB,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,kBAAkB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,IAAI,IAAI,CAClE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,EAC3B,UAAU,GAAG,UAAU,CACxB,GAAG;IACF,KAAK,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,IAAI,CAAC,EAAE,KAAK,CAAC,YAAY,GAAG,SAAS,CAAC;IACtC,OAAO,EAAE,SAAS,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;IAC5C,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACtC,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,iBAAS,aAAa,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,EAAE,EACpD,SAAS,EACT,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,aAAa,EACb,OAAO,EACP,KAAK,EACL,GAAG,KAAK,EACT,EAAE,kBAAkB,CAAC,KAAK,CAAC,qBA8C3B;AAED,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/components/menu-choice-row.js

@@ -2,13 +2,19 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { DropdownMenuRadioGroup, DropdownMenuRadioItem } from "./dropdown-menu.js";
 import { cn } from "../lib/utils.js";
 /**
- * A named preference inside a menu: the label reads at the leading edge and the
- * exclusive choices sit together at the trailing edge, close enough to read as
- * one control. Selecting keeps the menu open, so a reader can see the result
- * without reopening it.
+ * A named preference inside a menu: its icon and label at the leading edge, the
+ * exclusive choices together at the trailing edge, close enough to read as one
+ * control.
+ *
+ * @family Menus
+ * @when A setting that applies at once from inside a menu: the account menu's Theme and Language.
+ * @instead A product's own setting with more choices or longer names is a submenu of radio items (`AccountMenu`'s `choices`). A setting on a page is a `ToggleGroup` or a `Select` in its section.
+ * @behaviour Icon and label lead, on the commands' 12 px line; the choices sit in one bordered group at the trailing edge. Choosing applies at once and keeps the menu open, so the result shows without reopening it.
+ * @words The label is a noun: "Theme", "Language". Each choice carries a full name even when it shows a glyph or a short code: "EN" is named "English".
+ * @access A radio group named by the label; each choice is a radio named by its `label`, with the same text as its tooltip. The icon is hidden.
  */
-function MenuChoiceRow({ className, disabled, label, onValueChange, options, value, ...props }) {
-    return (_jsxs("div", { "data-slot": "menu-choice-row", className: cn("flex min-h-touch-target items-center justify-between gap-4 px-3 py-1 text-sm", className), ...props, children: [_jsx("span", { children: label }), _jsx(DropdownMenuRadioGroup, { "aria-label": label, className: "flex shrink-0 items-center gap-0.5 rounded-md border border-border p-0.5", value: value, onValueChange: (next) => {
+function MenuChoiceRow({ className, disabled, icon, label, onValueChange, options, value, ...props }) {
+    return (_jsxs("div", { "data-slot": "menu-choice-row", className: cn("flex min-h-touch-target items-center justify-between gap-4 px-3 py-1 text-sm", className), ...props, children: [_jsxs("span", { className: "flex min-w-0 items-center gap-2.5", children: [icon ? (_jsx("span", { "aria-hidden": "true", className: "flex h-5 shrink-0 items-center justify-center text-muted-foreground [&_svg:not([class*='size-'])]:size-4", children: icon })) : null, _jsx("span", { children: label })] }), _jsx(DropdownMenuRadioGroup, { "aria-label": label, className: "flex shrink-0 items-center gap-0.5 rounded-md border border-border p-0.5", value: value, onValueChange: (next) => {
                     const selected = options.find((option) => option.value === next);
                     if (selected)
                         onValueChange(selected.value);

package/dist/components/menubar.d.ts

@@ -2,6 +2,19 @@ import * as React from "react";
 import { Menu as MenuPrimitive } from "@base-ui/react/menu";
 import { Menubar as MenubarPrimitive } from "@base-ui/react/menubar";
 import { DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger } from "./dropdown-menu.js";
+/**
+ * A row of menus, as a desktop application's menu bar.
+ *
+ * @family Menus
+ * @when A desktop surface whose commands are many and grouped, as an application's File and Edit
+ * menus are.
+ * @instead A record's commands are its `ActionMenu`; a page's are `PageActions`. Finding anything
+ * is `CommandDialog`.
+ * @behaviour Each menu has the dropdown's surface and rows. Arrow keys move between menus and
+ * through items; Escape closes and returns focus to the bar.
+ * @words Menu names are single nouns; items are verb and noun in sentence case.
+ * @access `role="menubar"`; each trigger exposes `aria-expanded`; items are `menuitem`s.
+ */
 declare function Menubar({ className, ...props }: MenubarPrimitive.Props): React.JSX.Element;
 declare function MenubarMenu({ ...props }: React.ComponentProps<typeof DropdownMenu>): React.JSX.Element;
 declare function MenubarGroup({ ...props }: React.ComponentProps<typeof DropdownMenuGroup>): React.JSX.Element;

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

@@ -1 +1 @@
-{"version":3,"file":"menubar.d.ts","sourceRoot":"","sources":["../../src/components/menubar.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"menubar.d.ts","sourceRoot":"","sources":["../../src/components/menubar.tsx"],"names":[],"mappings":"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"}

package/dist/components/menubar.js

@@ -5,6 +5,19 @@ import { Menubar as MenubarPrimitive } from "@base-ui/react/menubar";
 import { cn } from "../lib/utils.js";
 import { DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, } from "./dropdown-menu.js";
 import { CheckIcon } from "lucide-react";
+/**
+ * A row of menus, as a desktop application's menu bar.
+ *
+ * @family Menus
+ * @when A desktop surface whose commands are many and grouped, as an application's File and Edit
+ * menus are.
+ * @instead A record's commands are its `ActionMenu`; a page's are `PageActions`. Finding anything
+ * is `CommandDialog`.
+ * @behaviour Each menu has the dropdown's surface and rows. Arrow keys move between menus and
+ * through items; Escape closes and returns focus to the bar.
+ * @words Menu names are single nouns; items are verb and noun in sentence case.
+ * @access `role="menubar"`; each trigger exposes `aria-expanded`; items are `menuitem`s.
+ */
 function Menubar({ className, ...props }) {
     return (_jsx(MenubarPrimitive, { "data-slot": "menubar", className: cn("flex h-control-height min-h-touch-target items-center gap-0.5 rounded-sm border p-1 [@media(hover:hover)_and_(pointer:fine)]:min-h-0", className), ...props }));
 }

package/dist/components/message-notice.d.ts

@@ -14,5 +14,21 @@ export type MessageNoticeProps = {
     tone?: MessageNoticeTone;
     className?: string;
 };
+/**
+ * A catalogue message about one thing on the screen.
+ *
+ * @family Feedback
+ * @when A catalogue message about one thing on the screen: under the control whose write failed
+ * (`action`), or atop the section whose condition lasts (`section`).
+ * @instead For a whole page or the account use `NoticeBanner`. For a finished action use a toast.
+ * For a field's wrong value use `FieldError`. For a failed read use `EmptyState failed`.
+ * @behaviour Tone `destructive` by default, `warning` or `info`. Its actions are outline buttons.
+ * Long words wrap, nothing truncates. A successful retry removes it. A `section` message with no
+ * action is drawn as the passage under a control, because a banner always carries its fix.
+ * @words From the catalogue only. Title says what happened to which object; body only when it adds
+ * something. Action labelled with its result: *Try again*, *Sign in*.
+ * @access `action`: `role="alert"` (`status` for info). `section`: `role="status"`,
+ * `aria-live="polite"`, atomic. Focus stays where the person was.
+ */
 export declare function MessageNotice({ message, placement, tone, className, }: MessageNoticeProps): import("react").JSX.Element;
 //# sourceMappingURL=message-notice.d.ts.map

package/dist/components/message-notice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message-notice.d.ts","sourceRoot":"","sources":["../../src/components/message-notice.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAE1E,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,SAAS,GAAG,MAAM,CAAC;AAEnE;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,QAAQ,GAAG,SAAS,CAAC;IAChC,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAeF,wBAAgB,aAAa,CAAC,EAC5B,OAAO,EACP,SAAS,EACT,IAAoB,EACpB,SAAS,GACV,EAAE,kBAAkB,+BA2CpB"}
+{"version":3,"file":"message-notice.d.ts","sourceRoot":"","sources":["../../src/components/message-notice.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAE1E,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,SAAS,GAAG,MAAM,CAAC;AAEnE;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,QAAQ,GAAG,SAAS,CAAC;IAChC,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAeF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,EAC5B,OAAO,EACP,SAAS,EACT,IAAoB,EACpB,SAAS,GACV,EAAE,kBAAkB,+BA2CpB"}

package/dist/components/message-notice.js

@@ -10,10 +10,26 @@ function MessageActions({ message }) {
     }
     return (_jsx("div", { className: "flex flex-wrap items-center gap-2", "data-message-actions": true, children: message.actions.map((action) => (_jsx(PageCommandButton, { command: action, variant: "outline" }, action.label))) }));
 }
+/**
+ * A catalogue message about one thing on the screen.
+ *
+ * @family Feedback
+ * @when A catalogue message about one thing on the screen: under the control whose write failed
+ * (`action`), or atop the section whose condition lasts (`section`).
+ * @instead For a whole page or the account use `NoticeBanner`. For a finished action use a toast.
+ * For a field's wrong value use `FieldError`. For a failed read use `EmptyState failed`.
+ * @behaviour Tone `destructive` by default, `warning` or `info`. Its actions are outline buttons.
+ * Long words wrap, nothing truncates. A successful retry removes it. A `section` message with no
+ * action is drawn as the passage under a control, because a banner always carries its fix.
+ * @words From the catalogue only. Title says what happened to which object; body only when it adds
+ * something. Action labelled with its result: *Try again*, *Sign in*.
+ * @access `action`: `role="alert"` (`status` for info). `section`: `role="status"`,
+ * `aria-live="polite"`, atomic. Focus stays where the person was.
+ */
 export function MessageNotice({ message, placement, tone = "destructive", className, }) {
     const body = bodyBeyondTitle(message);
-    if (placement === "section") {
-        return (_jsx(NoticeBanner, { action: message.actions.length > 0 ? _jsx(MessageActions, { message: message }) : undefined, className: className, "data-message-code": message.code, description: body ?? undefined, liveRegion: "polite", title: _jsx("span", { className: "min-w-0 break-words", children: message.title }), tone: tone }));
+    if (placement === "section" && message.actions.length > 0) {
+        return (_jsx(NoticeBanner, { action: _jsx(MessageActions, { message: message }), className: className, "data-message-code": message.code, description: body ?? undefined, liveRegion: "polite", title: _jsx("span", { className: "min-w-0 break-words", children: message.title }), tone: tone }));
     }
     return (_jsxs("div", { className: cn("flex min-w-0 flex-col gap-2 text-sm", className), "data-message-code": message.code, "data-message-notice": "action", role: tone === "info" ? "status" : "alert", children: [_jsxs("p", { className: cn("m-0 min-w-0 break-words", tone === "destructive" && "text-destructive", tone === "warning" && "text-warning-soft-foreground", tone === "info" && "text-muted-foreground"), children: [_jsx("span", { className: "block font-medium", children: message.title }), body ? (_jsxs(_Fragment, { children: [" ", _jsx("span", { className: "block", children: body })] })) : null] }), _jsx(MessageActions, { message: message })] }));
 }

package/dist/components/model-identity.d.ts

@@ -18,11 +18,24 @@ export type ModelIdentityProps = Omit<ComponentPropsWithoutRef<"span">, "childre
 };
 /**
  * A model as every surface reads it: the maker's mark, one name, the muted
- * maker. Callers pass the id and nothing else about its shape — the split, the
- * name form and the mark all belong here, so a ranked list, a routing table and
- * a settings row cannot drift into three readings of the same model. A product
+ * maker.
+ *
+ * Callers pass the id and nothing else about its shape — the split, the name
+ * form and the mark all belong here, so a ranked list, a routing table and a
+ * settings row cannot drift into three readings of the same model. A product
  * whose runtime names its models itself, as Hermes does in Nadia, passes that
  * `name` so a model reads the same in its settings as in its chat.
+ *
+ * @family Status
+ * @when Any place a model is shown: a ranked list, a routing table, a settings row, an option in
+ * `ModelSelect`.
+ * @instead A maker's mark with a name already in hand is `ModelMark`. Choosing a model is
+ * `ModelSelect`.
+ * @behaviour The caller passes the id and nothing else about its shape: the split, the name form
+ * and the mark all belong here. An id with no maker prefix falls back to the neutral tile.
+ * @words The maker's own spelling when the table has it (*Claude Opus 5*), else the id without its
+ * maker prefix; a product whose runtime names models passes that `name`.
+ * @access The name is text; the mark beside it is decorative.
  */
 export declare function ModelIdentity({ model, name, markSize, ...props }: ModelIdentityProps): import("react").JSX.Element;
 //# sourceMappingURL=model-identity.d.ts.map

package/dist/components/model-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-identity.d.ts","sourceRoot":"","sources":["../../src/components/model-identity.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,OAAO,CAAC;AAItD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGjD;AAUD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,wBAAwB,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,GAAG;IACpF,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,+BASpF"}
+{"version":3,"file":"model-identity.d.ts","sourceRoot":"","sources":["../../src/components/model-identity.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,OAAO,CAAC;AAItD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGjD;AAUD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,wBAAwB,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,GAAG;IACpF,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,+BASpF"}

package/dist/components/model-identity.js

@@ -30,11 +30,24 @@ export function modelDisplayName(model) {
 }
 /**
  * A model as every surface reads it: the maker's mark, one name, the muted
- * maker. Callers pass the id and nothing else about its shape — the split, the
- * name form and the mark all belong here, so a ranked list, a routing table and
- * a settings row cannot drift into three readings of the same model. A product
+ * maker.
+ *
+ * Callers pass the id and nothing else about its shape — the split, the name
+ * form and the mark all belong here, so a ranked list, a routing table and a
+ * settings row cannot drift into three readings of the same model. A product
  * whose runtime names its models itself, as Hermes does in Nadia, passes that
  * `name` so a model reads the same in its settings as in its chat.
+ *
+ * @family Status
+ * @when Any place a model is shown: a ranked list, a routing table, a settings row, an option in
+ * `ModelSelect`.
+ * @instead A maker's mark with a name already in hand is `ModelMark`. Choosing a model is
+ * `ModelSelect`.
+ * @behaviour The caller passes the id and nothing else about its shape: the split, the name form
+ * and the mark all belong here. An id with no maker prefix falls back to the neutral tile.
+ * @words The maker's own spelling when the table has it (*Claude Opus 5*), else the id without its
+ * maker prefix; a product whose runtime names models passes that `name`.
+ * @access The name is text; the mark beside it is decorative.
  */
 export function ModelIdentity({ model, name, markSize, ...props }) {
     return (_jsx(ModelMark, { author: modelAuthor(model), name: name ?? modelDisplayName(model), ...(markSize === undefined ? {} : { size: markSize }), ...props }));

package/dist/components/model-mark.d.ts

@@ -15,8 +15,21 @@ type ModelMarkProps = Omit<React.ComponentProps<"span">, "children"> & {
 };
 /**
  * A model's maker as LobeHub draws it, in the tile every mark shares, with the
- * model's name beside it when one is given. A maker LobeHub has no mark for
- * keeps its initials and is named in words.
+ * model's name beside it when one is given.
+ *
+ * A maker LobeHub has no mark for keeps its initials and is named in words.
+ *
+ * @family Status
+ * @when A maker's mark beside a name the caller already has, such as a usage row reporting an
+ * author slug.
+ * @instead A model read from its id is `ModelIdentity`, which splits the id and names it. An app is
+ * `AppMark`. A platform is `PlatformMark`.
+ * @behaviour Looks the maker up in LobeHub's set by its slug, through the one table of names that
+ * differ. While the mark loads the tile keeps its size; a maker with no mark keeps its initials.
+ * The glyph is 62% of the tile, 24 px by default.
+ * @words The model's name as the product reads it; the maker is never spelled by this component.
+ * @access Decorative beside the name. A bare mark takes `label` and becomes `role="img"`; with no
+ * name it stays hidden.
  */
 declare function ModelMark({ author, name, size, label, className, ...props }: ModelMarkProps): React.JSX.Element;
 export { ModelMark };

package/dist/components/model-mark.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-mark.d.ts","sourceRoot":"","sources":["../../src/components/model-mark.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAqG/B,KAAK,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,GAAG;IACrE,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AA+DF;;;;GAIG;AACH,iBAAS,SAAS,CAAC,EACjB,MAAM,EACN,IAAI,EACJ,IAAsB,EACtB,KAAK,EACL,SAAS,EACT,GAAG,KAAK,EACT,EAAE,cAAc,qBAsChB;AAED,OAAO,EAAE,SAAS,EAAE,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"model-mark.d.ts","sourceRoot":"","sources":["../../src/components/model-mark.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAqG/B,KAAK,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,GAAG;IACrE,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AA+DF;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAS,SAAS,CAAC,EACjB,MAAM,EACN,IAAI,EACJ,IAAsB,EACtB,KAAK,EACL,SAAS,EACT,GAAG,KAAK,EACT,EAAE,cAAc,qBAsChB;AAED,OAAO,EAAE,SAAS,EAAE,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,CAAC"}

package/dist/components/model-mark.js

@@ -96,8 +96,21 @@ function LoadedReading({ mark, ...reading }) {
 }
 /**
  * A model's maker as LobeHub draws it, in the tile every mark shares, with the
- * model's name beside it when one is given. A maker LobeHub has no mark for
- * keeps its initials and is named in words.
+ * model's name beside it when one is given.
+ *
+ * A maker LobeHub has no mark for keeps its initials and is named in words.
+ *
+ * @family Status
+ * @when A maker's mark beside a name the caller already has, such as a usage row reporting an
+ * author slug.
+ * @instead A model read from its id is `ModelIdentity`, which splits the id and names it. An app is
+ * `AppMark`. A platform is `PlatformMark`.
+ * @behaviour Looks the maker up in LobeHub's set by its slug, through the one table of names that
+ * differ. While the mark loads the tile keeps its size; a maker with no mark keeps its initials.
+ * The glyph is 62% of the tile, 24 px by default.
+ * @words The model's name as the product reads it; the maker is never spelled by this component.
+ * @access Decorative beside the name. A bare mark takes `label` and becomes `role="img"`; with no
+ * name it stays hidden.
  */
 function ModelMark({ author, name, size = MODEL_MARK_SIZE, label, className, ...props }) {
     const slug = normalizedAuthor(author);

package/dist/components/nadia-presence.d.ts

@@ -12,11 +12,17 @@ export type NadiaPresenceProps = {
 /** The arrival curve: a trace at the start, not a ribbon already half-built. */
 export declare function arrivalOpacity(reveal: number): number;
 /**
- * Nadia at an entry screen.
+ * Nadia at an entry screen: her ribbon, arriving through the picture behind her.
  *
- * `reveal` drives one opacity, so the value a Customer sees is the value
- * assistive technology is told. The ribbon itself carries the celebration at
- * `state="ready"`, so the screen spends no colour of its own on the moment.
+ * @family Other
+ * @when Nadia's entry, sign-in and update screens, standing in the middle of `EntryScene`.
+ * @instead Nadia anywhere else is her `AgentOrb`. A system wait is the waiting line.
+ * @behaviour `reveal` drives one opacity from a trace to whole; each presence state maps to her
+ * orb's state, so a person sees whether she is working, waiting, finished or stopped. 160 px unless
+ * the scene sets its size.
+ * @words The label names the arrival: *Nadia is getting ready*.
+ * @access A hidden `progressbar` named by `label` carries the same value the person sees; the
+ * ribbon is decorative.
  */
 export declare function NadiaPresence({ className, label, reveal, state, motionKey, }: NadiaPresenceProps): import("react").JSX.Element;
 //# sourceMappingURL=nadia-presence.d.ts.map

package/dist/components/nadia-presence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nadia-presence.d.ts","sourceRoot":"","sources":["../../src/components/nadia-presence.tsx"],"names":[],"mappings":"AAsBA,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAYlG,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,aAAa,CAAC;IACrB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAIF,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,EAC5B,SAAS,EACT,KAAK,EACL,MAAM,EACN,KAAK,EACL,SAAa,GACd,EAAE,kBAAkB,+BAgCpB"}
+{"version":3,"file":"nadia-presence.d.ts","sourceRoot":"","sources":["../../src/components/nadia-presence.tsx"],"names":[],"mappings":"AAsBA,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAYlG,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,aAAa,CAAC;IACrB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAIF,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,EAC5B,SAAS,EACT,KAAK,EACL,MAAM,EACN,KAAK,EACL,SAAa,GACd,EAAE,kBAAkB,+BAgCpB"}

package/dist/components/nadia-presence.js

@@ -33,11 +33,17 @@ export function arrivalOpacity(reveal) {
     return ARRIVAL_FLOOR + (1 - ARRIVAL_FLOOR) * clampUnit(reveal) ** ARRIVAL_CURVE;
 }
 /**
- * Nadia at an entry screen.
+ * Nadia at an entry screen: her ribbon, arriving through the picture behind her.
  *
- * `reveal` drives one opacity, so the value a Customer sees is the value
- * assistive technology is told. The ribbon itself carries the celebration at
- * `state="ready"`, so the screen spends no colour of its own on the moment.
+ * @family Other
+ * @when Nadia's entry, sign-in and update screens, standing in the middle of `EntryScene`.
+ * @instead Nadia anywhere else is her `AgentOrb`. A system wait is the waiting line.
+ * @behaviour `reveal` drives one opacity from a trace to whole; each presence state maps to her
+ * orb's state, so a person sees whether she is working, waiting, finished or stopped. 160 px unless
+ * the scene sets its size.
+ * @words The label names the arrival: *Nadia is getting ready*.
+ * @access A hidden `progressbar` named by `label` carries the same value the person sees; the
+ * ribbon is decorative.
  */
 export function NadiaPresence({ className, label, reveal, state, motionKey = 0, }) {
     const value = clampUnit(reveal);

package/dist/components/native-select.d.ts

@@ -2,6 +2,22 @@ import * as React from "react";
 type NativeSelectProps = Omit<React.ComponentProps<"select">, "size"> & {
     size?: "sm" | "default";
 };
+/**
+ * The platform's own select, drawn as our input box.
+ *
+ * @family Inputs
+ * @when A long fixed list inside a native form, where the platform's own picker serves best: a time
+ * zone, a country.
+ * @instead Two or three options are radios or a segmented control. Up to about ten, drawn in our
+ * style, is `Select`. A list people type into is `Combobox`.
+ * @behaviour Same box as `Input`, the chevron 10 px from the edge in the muted grey. It opens the
+ * system's list, with native keyboard and typing. As an uncontrolled field it keeps a saved value
+ * instead of snapping back to the page's first default.
+ * @words The label names the thing chosen (*Time zone*). A placeholder option is distinct from a
+ * real one and never preselected as if chosen.
+ * @access A real `select` with a visible label; option groups are `optgroup`. The chevron is
+ * decorative.
+ */
 declare function NativeSelect({ className, size, ref, ...props }: NativeSelectProps): React.JSX.Element;
 declare function NativeSelectOption({ className, ...props }: React.ComponentProps<"option">): React.JSX.Element;
 declare function NativeSelectOptGroup({ className, ...props }: React.ComponentProps<"optgroup">): React.JSX.Element;