@nadicodeai/ui 12.1.95 → 12.1.97

package/dist/components/object-workspace.d.ts

@@ -1,57 +1,47 @@
-import type { ComponentProps, ReactNode } from "react";
+import { type ReactNode } from "react";
+import { type PageCommand } from "./page-actions.js";
 export type ObjectFact = {
     label: string;
     value: ReactNode;
-    icon?: ReactNode;
     /**
      * A value long enough to be a paragraph rather than a figure, such as a note
      * or a pasted reference. It takes the full measure with its label above it.
      */
     block?: boolean;
 };
-export type ObjectIdentityFact = {
-    label: string;
-    value: ReactNode;
-};
 /**
- * An object's page opens with this header on the page ground, never in a card:
- * its picture, its name, one line saying what it is, a row of key facts, and at
- * the trailing edge the page's one primary action and its three dots. The
- * sections below it are the cards. On a page it opens, the header is the page's
- * title and its name is the h1; elsewhere the name is text at heading size.
+ * A section of an object's page: a card that owns one decision about the object.
+ *
+ * @family Compositions
+ * @when A part of an ObjectPage a person reads or changes on its own: a customer's Company details, an Agent's Instructions, a Library entry's source.
+ * @instead Values a person edits and saves together are a SettingsSection; a list of the object's records is a RecordList with its heading; a passing condition is a MessageNotice.
+ * @behaviour A resting card: its title and an optional line, at the trailing edge `meta` (muted) then `action` as an outline button, then its body. No icon in the header.
+ * @words The title names what the section holds ("Company", "Instructions"); the action is a verb on it ("Edit"); `meta` is a short count or time ("2 of 5 Agents").
+ * @access The title is a heading one level under the page (h2), deeper only under another heading through `headingLevel`.
  */
-export declare function ObjectIdentity({ visual, title, description, facts, action, menu, headingProps, }: {
-    /** The object's picture: an Agent's orb, an app's mark, a Library entry's tile. */
-    visual?: ReactNode;
-    title: ReactNode;
-    description?: ReactNode;
-    facts?: readonly ObjectIdentityFact[];
-    /** The page's single primary action. */
-    action?: ReactNode;
-    /** The three dots holding every other action on the object. */
-    menu?: ReactNode;
-    /**
-     * Given on a page this header opens, where the name is the page's title: the
-     * name is then its h1, with these attributes. Without it the name is text.
-     */
-    headingProps?: Omit<ComponentProps<"h1">, "children">;
-}): import("react").JSX.Element;
-export declare function ObjectOverview({ primary, supporting, }: {
-    primary: ReactNode;
-    supporting: ReactNode;
-}): import("react").JSX.Element;
-export declare function ObjectSection({ title, description, action, icon, children, headingLevel, }: {
+export declare function ObjectSection({ title, description, action, meta, children, headingLevel, }: {
     title: string;
     description?: ReactNode;
-    action?: ReactNode;
-    icon?: ReactNode;
+    /** The section's one command, an outline button in its header. */
+    action?: PageCommand;
+    /** A muted note at the header's trailing edge, before the action: "2 of 5 Agents". */
+    meta?: ReactNode;
     children: ReactNode;
     /** A card titles a section of its page; nest it deeper only under another heading. */
     headingLevel?: 2 | 3 | 4;
 }): import("react").JSX.Element;
-export declare function ObjectFacts({ facts, density, layout, }: {
+/**
+ * An object's facts as labelled values in a grid, inside one of its sections.
+ *
+ * @family Data
+ * @when Read-only values that describe an object, inside an ObjectSection: a company's legal name, VAT number and address.
+ * @instead Facts under the object's name belong to ObjectPage's `facts`; values a person changes are SettingsFields in a SettingsSection; figures compared across records are a DataTable.
+ * @behaviour Two columns from `sm`, one below; `compact` tightens the gaps for a dense card; a `block` fact takes the full width and keeps its line breaks.
+ * @words A label is a noun ("Billing email"); a value is the fact itself, with no unit the label already says.
+ * @access A description list: each label is its value's term and names it.
+ */
+export declare function ObjectFacts({ facts, density, }: {
     facts: readonly ObjectFact[];
     density?: "compact" | "default";
-    layout?: "grid" | "rows";
 }): import("react").JSX.Element;
 //# sourceMappingURL=object-workspace.d.ts.map

package/dist/components/object-workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"object-workspace.d.ts","sourceRoot":"","sources":["../../src/components/object-workspace.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAKvD,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAErE;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,EAC7B,MAAM,EACN,KAAK,EACL,WAAW,EACX,KAAK,EACL,MAAM,EACN,IAAI,EACJ,YAAY,GACb,EAAE;IACD,mFAAmF;IACnF,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,EAAE,SAAS,CAAC;IACjB,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,KAAK,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACtC,wCAAwC;IACxC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC;CACvD,+BA0CA;AAED,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,UAAU,GACX,EAAE;IACD,OAAO,EAAE,SAAS,CAAC;IACnB,UAAU,EAAE,SAAS,CAAC;CACvB,+BAUA;AAED,wBAAgB,aAAa,CAAC,EAC5B,KAAK,EACL,WAAW,EACX,MAAM,EACN,IAAI,EACJ,QAAQ,EACR,YAAgB,GACjB,EAAE;IACD,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,SAAS,CAAC;IACpB,sFAAsF;IACtF,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CAC1B,+BAkBA;AAED,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,OAAmB,EACnB,MAAe,GAChB,EAAE;IACD,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B,+BA2CA"}
+{"version":3,"file":"object-workspace.d.ts","sourceRoot":"","sources":["../../src/components/object-workspace.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAS,MAAM,OAAO,CAAC;AAI9C,OAAO,EAAE,KAAK,WAAW,EAAqB,MAAM,gBAAgB,CAAC;AAErE,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,EAC5B,KAAK,EACL,WAAW,EACX,MAAM,EACN,IAAI,EACJ,QAAQ,EACR,YAAgB,GACjB,EAAE;IACD,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,kEAAkE;IAClE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,sFAAsF;IACtF,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,SAAS,CAAC;IACpB,sFAAsF;IACtF,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CAC1B,+BAsBA;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,OAAmB,GACpB,EAAE;IACD,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CACjC,+BAiCA"}

package/dist/components/object-workspace.js

@@ -1,31 +1,34 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
 import { cn } from "../lib/utils.js";
 import { Card, CardAction, CardContent, CardDescription, CardHeader, CardTitle } from "./card.js";
+import { PageCommandButton } from "./page-actions.js";
 /**
- * An object's page opens with this header on the page ground, never in a card:
- * its picture, its name, one line saying what it is, a row of key facts, and at
- * the trailing edge the page's one primary action and its three dots. The
- * sections below it are the cards. On a page it opens, the header is the page's
- * title and its name is the h1; elsewhere the name is text at heading size.
+ * A section of an object's page: a card that owns one decision about the object.
+ *
+ * @family Compositions
+ * @when A part of an ObjectPage a person reads or changes on its own: a customer's Company details, an Agent's Instructions, a Library entry's source.
+ * @instead Values a person edits and saves together are a SettingsSection; a list of the object's records is a RecordList with its heading; a passing condition is a MessageNotice.
+ * @behaviour A resting card: its title and an optional line, at the trailing edge `meta` (muted) then `action` as an outline button, then its body. No icon in the header.
+ * @words The title names what the section holds ("Company", "Instructions"); the action is a verb on it ("Edit"); `meta` is a short count or time ("2 of 5 Agents").
+ * @access The title is a heading one level under the page (h2), deeper only under another heading through `headingLevel`.
  */
-export function ObjectIdentity({ visual, title, description, facts, action, menu, headingProps, }) {
-    const nameClass = "text-heading-md break-words text-foreground";
-    return (_jsxs("header", { className: "grid min-w-0 gap-5", "data-slot": "object-identity", children: [_jsxs("div", { className: "flex min-w-0 flex-wrap items-center justify-between gap-x-6 gap-y-4", children: [_jsxs("div", { className: "flex min-w-0 flex-1 basis-72 items-center gap-4", children: [visual ? _jsx("div", { className: "shrink-0", children: visual }) : null, _jsxs("div", { className: "grid min-w-0 gap-1", children: [headingProps ? (_jsx("h1", { ...headingProps, className: cn(nameClass, "outline-none", headingProps.className), children: title })) : (_jsx("p", { className: nameClass, children: title })), description ? (_jsx("div", { className: "min-w-0 text-body-md text-muted-foreground", children: description })) : null] })] }), action || menu ? (_jsxs("div", { className: "flex shrink-0 items-center gap-2", "data-slot": "object-identity-actions", children: [action, menu] })) : null] }), facts && facts.length > 0 ? (_jsx("dl", { className: "flex min-w-0 flex-wrap gap-x-10 gap-y-4", "data-slot": "object-identity-facts", children: facts.map((fact) => (_jsxs("div", { className: "grid min-w-0 gap-1", children: [_jsx("dt", { className: "text-xs text-muted-foreground", children: fact.label }), _jsx("dd", { className: "flex min-h-6 min-w-0 items-center text-sm", children: fact.value })] }, fact.label))) })) : null] }));
+export function ObjectSection({ title, description, action, meta, children, headingLevel = 2, }) {
+    return (_jsxs(Card, { "data-slot": "object-section", children: [_jsxs(CardHeader, { children: [_jsx(CardTitle, { role: "heading", "aria-level": headingLevel, children: title }), description ? _jsx(CardDescription, { children: description }) : null, action || meta ? (_jsxs(CardAction, { className: "flex items-center gap-3", children: [meta ? (_jsx("span", { className: "text-label-sm text-muted-foreground", "data-slot": "object-section-meta", children: meta })) : null, action ? _jsx(PageCommandButton, { command: action, variant: "outline" }) : null] })) : null] }), _jsx(CardContent, { children: children })] }));
 }
-export function ObjectOverview({ primary, supporting, }) {
-    return (_jsxs("div", { "data-slot": "object-overview", className: "grid min-w-0 items-start gap-6 xl:grid-cols-[minmax(0,1.6fr)_minmax(0,1fr)]", children: [_jsx("div", { className: "grid min-w-0 gap-6", children: primary }), _jsx("div", { className: "grid min-w-0 gap-6", children: supporting })] }));
-}
-export function ObjectSection({ title, description, action, icon, children, headingLevel = 2, }) {
-    return (_jsxs(Card, { "data-slot": "object-section", children: [_jsxs(CardHeader, { children: [_jsxs(CardTitle, { role: "heading", "aria-level": headingLevel, className: "flex items-center gap-2", children: [icon ? (_jsx("span", { "aria-hidden": "true", className: "text-muted-foreground [&_svg]:size-4", children: icon })) : null, title] }), description ? _jsx(CardDescription, { children: description }) : null, action ? _jsx(CardAction, { children: action }) : null] }), _jsx(CardContent, { children: children })] }));
-}
-export function ObjectFacts({ facts, density = "default", layout = "grid", }) {
-    return (_jsx("dl", { "data-density": density, "data-slot": "object-facts", className: layout === "rows"
-            ? "grid min-w-0 divide-y divide-border"
-            : density === "compact"
-                ? "grid min-w-0 grid-cols-2 gap-x-6 gap-y-2"
-                : "grid min-w-0 gap-x-6 gap-y-5 sm:grid-cols-2", children: facts.map((fact) => (_jsxs("div", { className: cn(layout === "rows"
-                ? cn("grid min-w-0 gap-2 py-3", !fact.block && "sm:grid-cols-[minmax(0,12rem)_minmax(0,1fr)]")
-                : density === "compact"
-                    ? "grid min-w-0 gap-0.5"
-                    : "grid min-w-0 gap-1.5", fact.block && "col-span-full"), children: [_jsxs("dt", { className: "flex items-center gap-2 text-xs text-muted-foreground", children: [fact.icon ? (_jsx("span", { "aria-hidden": "true", className: "[&_svg]:size-3.5", children: fact.icon })) : null, fact.label] }), _jsx("dd", { className: cn("text-sm break-words", fact.block && "whitespace-pre-wrap"), children: fact.value })] }, fact.label))) }));
+/**
+ * An object's facts as labelled values in a grid, inside one of its sections.
+ *
+ * @family Data
+ * @when Read-only values that describe an object, inside an ObjectSection: a company's legal name, VAT number and address.
+ * @instead Facts under the object's name belong to ObjectPage's `facts`; values a person changes are SettingsFields in a SettingsSection; figures compared across records are a DataTable.
+ * @behaviour Two columns from `sm`, one below; `compact` tightens the gaps for a dense card; a `block` fact takes the full width and keeps its line breaks.
+ * @words A label is a noun ("Billing email"); a value is the fact itself, with no unit the label already says.
+ * @access A description list: each label is its value's term and names it.
+ */
+export function ObjectFacts({ facts, density = "default", }) {
+    const termId = useId();
+    return (_jsx("dl", { "data-density": density, "data-slot": "object-facts", className: density === "compact"
+            ? "grid min-w-0 grid-cols-2 gap-x-6 gap-y-2"
+            : "grid min-w-0 gap-x-6 gap-y-5 sm:grid-cols-2", children: facts.map((fact, index) => (_jsxs("div", { className: cn(density === "compact" ? "grid min-w-0 gap-0.5" : "grid min-w-0 gap-1.5", fact.block && "col-span-full"), children: [_jsx("dt", { className: "text-xs text-muted-foreground", id: `${termId}-${index}`, children: fact.label }), _jsx("dd", { "aria-labelledby": `${termId}-${index}`, className: cn("text-sm break-words", fact.block && "whitespace-pre-wrap"), children: fact.value })] }, fact.label))) }));
 }

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

@@ -0,0 +1,24 @@
+import type { ReactElement, ReactNode } from "react";
+import { type KpiCardProps } from "./kpi-card.js";
+export type OverviewPageProps = {
+    /** On the title row, through PageActions. */
+    period?: ReactElement;
+    /** The figures, one row of equal cards, one column below md. */
+    figures?: readonly Omit<KpiCardProps, "presentation">[];
+    /** The chart cards, each with its one header, in reading order. */
+    charts?: ReactNode;
+    /** The exceptions that need a person, each opening its owner: a RecordList with its heading. */
+    exceptions?: ReactNode;
+};
+/**
+ * The page that answers "what needs attention?": is anything wrong, and where.
+ *
+ * @family Compositions
+ * @when The landing page of an area a person checks: the Portal's Dashboard, Analytics, Statements, System health, an Agent's Usage.
+ * @instead A list of records a person finds one of is a `CollectionPage`; one record is an `ObjectPage`. Never a stack of previews of every section: each exception links to its owner instead.
+ * @behaviour The reading period on the title row, then the figures in one row of equal `KpiCard`s (four columns from md, fewer when fewer, one column below), then the chart cards, then the exceptions, 16 px apart. It has no states of its own: each card and the exceptions' `RecordList` draw theirs.
+ * @words The product words every figure, chart and exception. A figure's label names its measure ("Active Agents", "Spend"), the chart's title names its reading ("Usage"), and the exceptions' heading says what they are ("Needs attention").
+ * @access Each chart card is a named section at the page's heading level, and the exceptions carry their own heading; figures are text, never colour alone.
+ */
+export declare function OverviewPage({ period, figures, charts, exceptions }: OverviewPageProps): import("react").JSX.Element;
+//# sourceMappingURL=overview-page.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overview-page.d.ts","sourceRoot":"","sources":["../../src/components/overview-page.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGrD,OAAO,EAAW,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGnE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,6CAA6C;IAC7C,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,gEAAgE;IAChE,OAAO,CAAC,EAAE,SAAS,IAAI,CAAC,YAAY,EAAE,cAAc,CAAC,EAAE,CAAC;IACxD,mEAAmE;IACnE,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,gGAAgG;IAChG,UAAU,CAAC,EAAE,SAAS,CAAC;CACxB,CAAC;AAUF;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,EAAE,MAAM,EAAE,OAAY,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,iBAAiB,+BAe3F"}

package/dist/components/overview-page.js

@@ -0,0 +1,26 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CardRow } from "./card-row.js";
+import { KpiCard } from "./kpi-card.js";
+import { PageActions } from "./page-actions.js";
+const MAX_FIGURE_COLUMNS = 4;
+function figureColumns(count) {
+    if (count >= MAX_FIGURE_COLUMNS)
+        return MAX_FIGURE_COLUMNS;
+    if (count === 3 || count === 2)
+        return count;
+    return "auto";
+}
+/**
+ * The page that answers "what needs attention?": is anything wrong, and where.
+ *
+ * @family Compositions
+ * @when The landing page of an area a person checks: the Portal's Dashboard, Analytics, Statements, System health, an Agent's Usage.
+ * @instead A list of records a person finds one of is a `CollectionPage`; one record is an `ObjectPage`. Never a stack of previews of every section: each exception links to its owner instead.
+ * @behaviour The reading period on the title row, then the figures in one row of equal `KpiCard`s (four columns from md, fewer when fewer, one column below), then the chart cards, then the exceptions, 16 px apart. It has no states of its own: each card and the exceptions' `RecordList` draw theirs.
+ * @words The product words every figure, chart and exception. A figure's label names its measure ("Active Agents", "Spend"), the chart's title names its reading ("Usage"), and the exceptions' heading says what they are ("Needs attention").
+ * @access Each chart card is a named section at the page's heading level, and the exceptions carry their own heading; figures are text, never colour alone.
+ */
+export function OverviewPage({ period, figures = [], charts, exceptions }) {
+    return (_jsxs("div", { "data-slot": "overview-page", className: "grid min-w-0 gap-4", children: [_jsx(PageActions, { ...(period ? { period } : {}) }), figures.length > 0 ? (_jsx(CardRow, { columns: figureColumns(figures.length), from: "md", children: figures.map((figure) => (_jsx(KpiCard, { ...figure }, figure.label))) })) : null, charts, exceptions] }));
+}

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

@@ -1,4 +1,5 @@
 import { type MouseEvent, type ReactElement, type ReactNode } from "react";
+import { type MenuCommand, type RecordMenu } from "./action-menu.js";
 export type PageCommandAction = {
     onClick: (event: MouseEvent<HTMLElement>) => void;
     render?: never;
@@ -11,41 +12,37 @@ export type PageCommandAction = {
     render: ReactElement;
     onClick?: never;
 };
-/** A command drawn as a button on the title's row. Its variant is its slot's. */
+/** A command drawn as a button: on the title row, in an empty state, in a row. Its icon leads the label. */
 export type PageCommand = PageCommandAction & {
     label: string;
-    icon?: ReactElement;
-    /** Opens outside the product, marked with the arrow at its end. */
-    external?: boolean;
-    disabled?: boolean;
-};
-export type PageMenuCommand = PageCommandAction & {
-    label: string;
-    icon?: ReactElement;
-    disabled?: boolean;
-    destructive?: boolean;
+    icon?: ReactElement | undefined;
+    /** Read instead of the label when the label alone does not name the target: "Sign in to Notion". */
+    accessibleName?: string | undefined;
+    /** Opens outside the product: the arrow after the label. */
+    external?: boolean | undefined;
+    disabled?: boolean | undefined;
+    /** Running: the button keeps its place, size and icon and says `pendingLabel`, with aria-busy. */
+    pending?: boolean | undefined;
+    pendingLabel?: string | undefined;
 };
 /** The page's three dots, which open only for two commands or more. */
-export type PageMenu = {
-    label: string;
-    commands: readonly [PageMenuCommand, PageMenuCommand, ...PageMenuCommand[]];
+export type PageMenu = Omit<RecordMenu, "commands"> & {
+    commands: readonly [MenuCommand, MenuCommand, ...MenuCommand[]];
 };
-/**
- * A page's actions (DESIGN.md "Page compositions"): at most one
- * secondary button, the primary action, then the overflow menu at the end.
- */
 export type PageActionsProps = {
-    primary?: PageCommand | undefined;
+    /** An overview's reading period, first on the title row: a period `Select` or `DateRangeControl`. */
+    period?: ReactElement | undefined;
     secondary?: PageCommand | undefined;
-    menu?: PageMenu | ReactElement | undefined;
+    primary?: PageCommand | undefined;
+    menu?: PageMenu | undefined;
 };
-/** One command as a button in a given slot's variant. */
+type CommandVariant = "default" | "outline" | "ghost" | "link";
 export declare function PageCommandButton({ command, variant, }: {
     command: PageCommand;
-    variant: "default" | "outline" | "ghost";
+    variant: CommandVariant;
 }): import("react").JSX.Element;
 /** The row of a page's actions where it stands, for a page whose header is its own card. */
-export declare function PageActionsRow({ primary, secondary, menu }: PageActionsProps): import("react").JSX.Element | null;
+export declare function PageActionsRow({ period, primary, secondary, menu }: PageActionsProps): import("react").JSX.Element | null;
 /**
  * Holds the place on the title's row where the open page puts its actions. The
  * product's chrome draws the row (`PageHeader`) and the page below draws its
@@ -60,6 +57,14 @@ export declare function PageActionsSlot(): import("react").JSX.Element;
  * A page's actions, drawn on its title's row. Only the page shown last owns
  * the row: a page kept hidden for a quick return gives the row back. Outside a
  * `PageActionsHostProvider`, they render where they stand.
+ *
+ * @family Actions
+ * @when The actions of a collection, an object or an overview page, on the title's row at its trailing edge. A Configuration page has none: each section saves from its footer.
+ * @instead A row's actions are the row's one button and its `ActionMenu`. A collection toolbar holds search and filters, never a page action.
+ * @behaviour Takes `period`, `secondary`, `primary` and `menu` and draws their order and variants itself: the period, outline, default, then the three dots last. The menu needs two commands or more; a single extra command is the secondary. A destination outside the product ends in the arrow. A running command keeps its place and icon, says its pending word and holds.
+ * @words The primary is the page's main job as verb and noun: "Invite member", "New Agent". The pending word is its -ing form: "Inviting member". The menu names the page's record at its top and keeps the destructive command last, after a divider.
+ * @access DOM order is visual order. A command whose label does not name its target carries `accessibleName`. A running command is `aria-busy` and keeps focus. The three dots carry "More for {record}"; the menu returns focus to them when it closes.
  */
 export declare function PageActions(props: PageActionsProps): import("react").JSX.Element | null;
+export {};
 //# sourceMappingURL=page-actions.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"page-actions.d.ts","sourceRoot":"","sources":["../../src/components/page-actions.tsx"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,SAAS,EAMf,MAAM,OAAO,CAAC;AAOf,MAAM,MAAM,iBAAiB,GACzB;IAAE,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE;AACvE;;;GAGG;GACD;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,OAAO,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAE9C,iFAAiF;AACjF,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,iBAAiB,GAAG;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,uEAAuE;AACvE,MAAM,MAAM,QAAQ,GAAG;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,CAAC,eAAe,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAAC,CAAC;CAC7E,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAClC,SAAS,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACpC,IAAI,CAAC,EAAE,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;CAC5C,CAAC;AAwBF,yDAAyD;AACzD,wBAAgB,iBAAiB,CAAC,EAChC,OAAO,EACP,OAAO,GACR,EAAE;IACD,OAAO,EAAE,WAAW,CAAC;IACrB,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;CAC1C,+BAoBA;AAsBD,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,gBAAgB,sCAiB5E;AAYD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAa5E;AAED,yFAAyF;AACzF,wBAAgB,eAAe,gCAS9B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,sCAuBlD"}
+{"version":3,"file":"page-actions.d.ts","sourceRoot":"","sources":["../../src/components/page-actions.tsx"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,SAAS,EAMf,MAAM,OAAO,CAAC;AAGf,OAAO,EAAc,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAI9E,MAAM,MAAM,iBAAiB,GACzB;IAAE,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE;AACvE;;;GAGG;GACD;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,OAAO,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAE9C,4GAA4G;AAC5G,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAChC,oGAAoG;IACpG,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,kGAAkG;IAClG,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC,CAAC;AAEF,uEAAuE;AACvE,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,GAAG;IACpD,QAAQ,EAAE,SAAS,CAAC,WAAW,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAAC,CAAC;CACjE,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qGAAqG;IACrG,MAAM,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAClC,SAAS,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACpC,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAClC,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC7B,CAAC;AAEF,KAAK,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AA8B/D,wBAAgB,iBAAiB,CAAC,EAChC,OAAO,EACP,OAAO,GACR,EAAE;IACD,OAAO,EAAE,WAAW,CAAC;IACrB,OAAO,EAAE,cAAc,CAAC;CACzB,+BAqCA;AAED,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,gBAAgB,sCAUpF;AAYD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAa5E;AAED,yFAAyF;AACzF,wBAAgB,eAAe,gCAS9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,sCAuBlD"}

package/dist/components/page-actions.js

@@ -2,38 +2,37 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useRender } from "@base-ui/react/use-render";
 import { ArrowUpRight } from "lucide-react";
-import { createContext, isValidElement, useCallback, useContext, useEffect, useId, useState, } from "react";
+import { createContext, useCallback, useContext, useEffect, useId, useState, } from "react";
 import { createPortal } from "react-dom";
 import { ActionMenu } from "./action-menu.js";
 import { Button, buttonVariants } from "./button.js";
-import { DropdownMenuItem, DropdownMenuSeparator } from "./dropdown-menu.js";
-function CommandElement({ children, disabled, element, variant, }) {
+import { PendingLabel } from "./pending-label.js";
+function CommandElement({ accessibleName, busy, children, disabled, element, variant, }) {
     return useRender({
         render: element,
         props: {
+            "aria-busy": busy || undefined,
             "aria-disabled": disabled || undefined,
+            "aria-label": accessibleName,
             children,
             className: buttonVariants({ variant }),
             "data-slot": "button",
         },
     });
 }
-/** One command as a button in a given slot's variant. */
 export function PageCommandButton({ command, variant, }) {
-    const content = (_jsxs(_Fragment, { children: [command.icon ? _jsx("span", { "data-icon": "inline-start", children: command.icon }) : null, command.label, command.external ? _jsx(ArrowUpRight, { "aria-hidden": "true", "data-icon": "inline-end" }) : null] }));
+    const pending = command.pending === true;
+    const content = (_jsxs(_Fragment, { children: [command.icon ? _jsx("span", { "data-icon": "inline-start", children: command.icon }) : null, _jsx(PendingLabel, { pending: pending, pendingLabel: command.pendingLabel ?? command.label, children: command.label }), command.external ? _jsx(ArrowUpRight, { "aria-hidden": "true", "data-icon": "inline-end" }) : null] }));
     if (command.render) {
-        return (_jsx(CommandElement, { disabled: command.disabled, element: command.render, variant: variant, children: content }));
+        return (_jsx(CommandElement, { accessibleName: command.accessibleName, busy: pending, disabled: pending || command.disabled === true, element: command.render, variant: variant, children: content }));
     }
-    return (_jsx(Button, { disabled: command.disabled, onClick: command.onClick, type: "button", variant: variant, children: content }));
-}
-function MenuCommand({ command }) {
-    return (_jsxs(_Fragment, { children: [command.destructive ? _jsx(DropdownMenuSeparator, {}) : null, _jsxs(DropdownMenuItem, { disabled: command.disabled, variant: command.destructive ? "destructive" : "default", ...(command.render ? { render: command.render } : { onClick: command.onClick }), children: [command.label, command.icon ? (_jsx("span", { "aria-hidden": "true", className: "ml-auto flex items-center", children: command.icon })) : null] })] }));
+    return (_jsx(Button, { "aria-busy": pending || undefined, "aria-label": command.accessibleName, disabled: pending || command.disabled, focusableWhenDisabled: pending, onClick: command.onClick, type: "button", variant: variant, children: content }));
 }
 /** The row of a page's actions where it stands, for a page whose header is its own card. */
-export function PageActionsRow({ primary, secondary, menu }) {
-    if (!primary && !secondary && !menu)
+export function PageActionsRow({ period, primary, secondary, menu }) {
+    if (!period && !primary && !secondary && !menu)
         return null;
-    return (_jsxs("div", { "data-slot": "page-actions", className: "flex shrink-0 flex-wrap items-center gap-2", children: [secondary ? _jsx(PageCommandButton, { command: secondary, variant: "outline" }) : null, primary ? _jsx(PageCommandButton, { command: primary, variant: "default" }) : null, isValidElement(menu) ? (menu) : menu ? (_jsx(ActionMenu, { label: menu.label, children: menu.commands.map((command) => (_jsx(MenuCommand, { command: command }, command.label))) })) : null] }));
+    return (_jsxs("div", { "data-slot": "page-actions", className: "flex shrink-0 flex-wrap items-center gap-2", children: [period, secondary ? _jsx(PageCommandButton, { command: secondary, variant: "outline" }) : null, primary ? _jsx(PageCommandButton, { command: primary, variant: "default" }) : null, menu ? _jsx(ActionMenu, { ...menu }) : null] }));
 }
 const PageActionsHostContext = createContext(null);
 /**
@@ -57,13 +56,20 @@ export function PageActionsSlot() {
  * A page's actions, drawn on its title's row. Only the page shown last owns
  * the row: a page kept hidden for a quick return gives the row back. Outside a
  * `PageActionsHostProvider`, they render where they stand.
+ *
+ * @family Actions
+ * @when The actions of a collection, an object or an overview page, on the title's row at its trailing edge. A Configuration page has none: each section saves from its footer.
+ * @instead A row's actions are the row's one button and its `ActionMenu`. A collection toolbar holds search and filters, never a page action.
+ * @behaviour Takes `period`, `secondary`, `primary` and `menu` and draws their order and variants itself: the period, outline, default, then the three dots last. The menu needs two commands or more; a single extra command is the secondary. A destination outside the product ends in the arrow. A running command keeps its place and icon, says its pending word and holds.
+ * @words The primary is the page's main job as verb and noun: "Invite member", "New Agent". The pending word is its -ing form: "Inviting member". The menu names the page's record at its top and keeps the destructive command last, after a divider.
+ * @access DOM order is visual order. A command whose label does not name its target carries `accessibleName`. A running command is `aria-busy` and keeps focus. The three dots carry "More for {record}"; the menu returns focus to them when it closes.
  */
 export function PageActions(props) {
     const host = useContext(PageActionsHostContext);
     const id = useId();
     const claim = host?.claim;
     const release = host?.release;
-    const hasActions = Boolean(props.primary || props.secondary || props.menu);
+    const hasActions = Boolean(props.period || props.primary || props.secondary || props.menu);
     useEffect(() => {
         if (!hasActions)
             return;

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

@@ -1,10 +1,16 @@
 import * as React from "react";
 /**
- * The top of a product page (DESIGN.md "Page compositions"): its title at
- * heading size on the left, the page's actions on the title's row at the right,
- * which the page draws with `PageActions`. Nothing explains the page under its
- * title. The path above it is the top bar's; the toolbar below it holds only
- * filters, search and sort.
+ * The top of a product page: its title, and the page's actions on the title's row.
+ *
+ * @family Compositions
+ * @when The top of every collection and working page: the title at heading size, `PageActions` at
+ * the trailing edge of its row.
+ * @instead An object's own header is `ObjectPage`'s. The path above it is the top bar's
+ * `Breadcrumb`; filters, search and sort sit in the toolbar below.
+ * @behaviour Nothing explains the page under its title. The actions arrive through the
+ * `PageActions` slot, so the page draws its commands once.
+ * @words The title is the page's name as the sidebar writes it: *Customers*, *Agents*.
+ * @access The title is the page's `h1`; DOM order is visual order.
  */
 declare function PageHeader({ title, headingProps, className, ...props }: Omit<React.ComponentProps<"header">, "title" | "children"> & {
     title: React.ReactNode;

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

@@ -1 +1 @@
-{"version":3,"file":"page-header.d.ts","sourceRoot":"","sources":["../../src/components/page-header.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAM/B;;;;;;GAMG;AACH,iBAAS,UAAU,CAAC,EAClB,KAAK,EACL,YAAY,EACZ,SAAS,EACT,GAAG,KAAK,EACT,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC,GAAG;IAC9D,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC;IACvB,YAAY,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC;CAC7D,qBAiBA;AAED,OAAO,EAAE,UAAU,EAAE,CAAC"}
+{"version":3,"file":"page-header.d.ts","sourceRoot":"","sources":["../../src/components/page-header.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAM/B;;;;;;;;;;;;GAYG;AACH,iBAAS,UAAU,CAAC,EAClB,KAAK,EACL,YAAY,EACZ,SAAS,EACT,GAAG,KAAK,EACT,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC,GAAG;IAC9D,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC;IACvB,YAAY,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC;CAC7D,qBAiBA;AAED,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/components/page-header.js

@@ -2,11 +2,17 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cn } from "../lib/utils.js";
 import { PageActionsSlot } from "./page-actions.js";
 /**
- * The top of a product page (DESIGN.md "Page compositions"): its title at
- * heading size on the left, the page's actions on the title's row at the right,
- * which the page draws with `PageActions`. Nothing explains the page under its
- * title. The path above it is the top bar's; the toolbar below it holds only
- * filters, search and sort.
+ * The top of a product page: its title, and the page's actions on the title's row.
+ *
+ * @family Compositions
+ * @when The top of every collection and working page: the title at heading size, `PageActions` at
+ * the trailing edge of its row.
+ * @instead An object's own header is `ObjectPage`'s. The path above it is the top bar's
+ * `Breadcrumb`; filters, search and sort sit in the toolbar below.
+ * @behaviour Nothing explains the page under its title. The actions arrive through the
+ * `PageActions` slot, so the page draws its commands once.
+ * @words The title is the page's name as the sidebar writes it: *Customers*, *Agents*.
+ * @access The title is the page's `h1`; DOM order is visual order.
  */
 function PageHeader({ title, headingProps, className, ...props }) {
     return (_jsx("header", { "data-slot": "page-header", className: cn("min-w-0", className), ...props, children: _jsxs("div", { className: "flex min-h-9 min-w-0 flex-wrap items-center justify-between gap-x-6 gap-y-3", children: [_jsx("h1", { ...headingProps, className: cn("min-w-0 flex-1 basis-48 truncate text-heading-md text-foreground outline-none", headingProps?.className), children: title }), _jsx(PageActionsSlot, {})] }) }));

package/dist/components/pagination.d.ts

@@ -1,5 +1,20 @@
 import * as React from "react";
 import { Button } from "./button.js";
+/**
+ * Numbered sibling pages with Previous and Next.
+ *
+ * @family Navigation
+ * @when `Pagination` for numbered sibling pages. A table of server pages takes `DataTable`'s own
+ * Previous and Next under its card; the card's footer strip holds the count or the paging.
+ * @instead Appending rows in place is a `Button` with `PendingLabel` (*Load more*). A fixed
+ * comparison passes `pagination={false}` and stays whole.
+ * @behaviour Boundaries are disabled. While the next page loads both buttons disable and the rows
+ * stay. The order and the page live in the URL. The labels hide under `sm`, leaving the chevrons.
+ * @words *Previous*, *Next*. The footer is a count with its noun or *Page 1 of 6*, never a help
+ * sentence.
+ * @access A labelled `nav`; the current page has `aria-current="page"`; the arrows read *Go to
+ * previous page*; a pending button is `aria-busy`.
+ */
 declare function Pagination({ className, ...props }: React.ComponentProps<"nav">): React.JSX.Element;
 declare function PaginationContent({ className, ...props }: React.ComponentProps<"ul">): React.JSX.Element;
 declare function PaginationItem({ ...props }: React.ComponentProps<"li">): React.JSX.Element;

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

@@ -1 +1 @@
-{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/components/pagination.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAG7C,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,qBASvE;AAED,iBAAS,iBAAiB,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,qBAQ7E;AAED,iBAAS,cAAc,CAAC,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,qBAE/D;AAED,KAAK,mBAAmB,GAAG;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,MAAM,CAAC,EAAE,MAAM,CAAC,GACnD,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;AAE5B,iBAAS,cAAc,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAa,EAAE,GAAG,KAAK,EAAE,EAAE,mBAAmB,qBAiB5F;AAED,iBAAS,kBAAkB,CAAC,EAC1B,SAAS,EACT,IAAiB,EACjB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,cAAc,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,qBAYjE;AAED,iBAAS,cAAc,CAAC,EACtB,SAAS,EACT,IAAa,EACb,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,cAAc,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,qBAYjE;AAED,iBAAS,kBAAkB,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,qBAehF;AAED,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,cAAc,EACd,kBAAkB,GACnB,CAAC"}
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/components/pagination.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAG7C;;;;;;;;;;;;;;GAcG;AACH,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,qBASvE;AAED,iBAAS,iBAAiB,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,qBAQ7E;AAED,iBAAS,cAAc,CAAC,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,qBAE/D;AAED,KAAK,mBAAmB,GAAG;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,MAAM,CAAC,EAAE,MAAM,CAAC,GACnD,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;AAE5B,iBAAS,cAAc,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAa,EAAE,GAAG,KAAK,EAAE,EAAE,mBAAmB,qBAiB5F;AAED,iBAAS,kBAAkB,CAAC,EAC1B,SAAS,EACT,IAAiB,EACjB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,cAAc,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,qBAYjE;AAED,iBAAS,cAAc,CAAC,EACtB,SAAS,EACT,IAAa,EACb,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,cAAc,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,qBAYjE;AAED,iBAAS,kBAAkB,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,qBAehF;AAED,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,cAAc,EACd,kBAAkB,GACnB,CAAC"}

package/dist/components/pagination.js

@@ -2,6 +2,21 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cn } from "../lib/utils.js";
 import { Button } from "./button.js";
 import { ChevronLeftIcon, ChevronRightIcon, MoreHorizontalIcon } from "lucide-react";
+/**
+ * Numbered sibling pages with Previous and Next.
+ *
+ * @family Navigation
+ * @when `Pagination` for numbered sibling pages. A table of server pages takes `DataTable`'s own
+ * Previous and Next under its card; the card's footer strip holds the count or the paging.
+ * @instead Appending rows in place is a `Button` with `PendingLabel` (*Load more*). A fixed
+ * comparison passes `pagination={false}` and stays whole.
+ * @behaviour Boundaries are disabled. While the next page loads both buttons disable and the rows
+ * stay. The order and the page live in the URL. The labels hide under `sm`, leaving the chevrons.
+ * @words *Previous*, *Next*. The footer is a count with its noun or *Page 1 of 6*, never a help
+ * sentence.
+ * @access A labelled `nav`; the current page has `aria-current="page"`; the arrows read *Go to
+ * previous page*; a pending button is `aria-busy`.
+ */
 function Pagination({ className, ...props }) {
     return (_jsx("nav", { "aria-label": "pagination", "data-slot": "pagination", className: cn("mx-auto flex w-full justify-center", className), ...props }));
 }

package/dist/components/pairing-code.d.ts

@@ -6,10 +6,21 @@ export type PairingCodeProps = Omit<React.ComponentProps<"div">, "children" | "r
     label: string;
 };
 /**
- * The short code two screens show at once so a person can tell they are
- * talking to each other, such as the four digits Nadia and Alveare Server both
- * show while a Nadia asks to join. Each digit stands in its own cell, large
- * enough to compare from across a desk. The caller places it.
+ * The short code two screens show at once so a person can tell they are talking
+ * to each other, such as the four digits Nadia and Alveare Server both show
+ * while a Nadia asks to join.
+ *
+ * Each digit stands in its own cell, large enough to compare from across a
+ * desk. The caller places it.
+ *
+ * @family Data
+ * @when Pairing two devices or apps a person can see side by side: the four digits Nadia and
+ * Alveare Server both show while a Nadia asks to join.
+ * @instead A code a person types is `InputOTP`. A link another device scans is `QrCode`.
+ * @behaviour Each digit in its own cell, large enough to compare from across a desk. A leading zero
+ * is a digit.
+ * @words The label says what the code is: *Pairing code*.
+ * @access `role="img"` named by the label and the digits read one by one.
  */
 declare function PairingCode({ code, label, className, ...props }: PairingCodeProps): React.JSX.Element;
 export { PairingCode };

package/dist/components/pairing-code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pairing-code.d.ts","sourceRoot":"","sources":["../../src/components/pairing-code.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAIpC,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC,GAAG;IACtF,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,8FAA8F;IAC9F,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;GAKG;AACH,iBAAS,WAAW,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,gBAAgB,qBAsB1E;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"pairing-code.d.ts","sourceRoot":"","sources":["../../src/components/pairing-code.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAIpC,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC,GAAG;IACtF,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,8FAA8F;IAC9F,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,iBAAS,WAAW,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,gBAAgB,qBAsB1E;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/components/pairing-code.js

@@ -1,10 +1,21 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cn } from "../lib/utils.js";
 /**
- * The short code two screens show at once so a person can tell they are
- * talking to each other, such as the four digits Nadia and Alveare Server both
- * show while a Nadia asks to join. Each digit stands in its own cell, large
- * enough to compare from across a desk. The caller places it.
+ * The short code two screens show at once so a person can tell they are talking
+ * to each other, such as the four digits Nadia and Alveare Server both show
+ * while a Nadia asks to join.
+ *
+ * Each digit stands in its own cell, large enough to compare from across a
+ * desk. The caller places it.
+ *
+ * @family Data
+ * @when Pairing two devices or apps a person can see side by side: the four digits Nadia and
+ * Alveare Server both show while a Nadia asks to join.
+ * @instead A code a person types is `InputOTP`. A link another device scans is `QrCode`.
+ * @behaviour Each digit in its own cell, large enough to compare from across a desk. A leading zero
+ * is a digit.
+ * @words The label says what the code is: *Pairing code*.
+ * @access `role="img"` named by the label and the digits read one by one.
  */
 function PairingCode({ code, label, className, ...props }) {
     const digits = [...code];

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

@@ -1,11 +1,19 @@
 import type * as React from "react";
 /**
  * A control's own label while the system works on what it was asked to do.
- * The word changes and nothing moves; the control keeps its place, its icon
- * and its size. The caller owns `disabled` and `aria-busy` on the control
- * itself, because only the caller knows which element the wait belongs to.
  *
- * Work that runs past a second adds one `WaitingLine` beside the control.
+ * @family Feedback
+ * @when Every control that starts work the system does: from the press until the result, whatever
+ * the wait. Under about a second it is the only sign. Every save in a footer goes through it.
+ * @instead Past a second add one `WaitingLine` beside the control. An Agent's work is never this:
+ * it is her orb and a sentence. A queued or paused request is a status.
+ * @behaviour Swaps the word, nothing else: same place, size and icon. The caller sets `disabled`
+ * (50% opacity) and `aria-busy` and blocks a second submit, because only the caller knows which
+ * element the wait belongs to. Failure returns the rest label.
+ * @words The rest label's verb in its -ing form with the same noun: *Remove mailbox* to *Removing
+ * mailbox*. No ellipsis, no *Please wait*.
+ * @access `aria-busy` on the control; its name changes to the pending word and is read once. Focus
+ * stays on it.
  */
 declare function PendingLabel({ children, className, pending, pendingLabel, ...props }: React.ComponentProps<"span"> & {
     pending: boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"pending-label.d.ts","sourceRoot":"","sources":["../../src/components/pending-label.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAIpC;;;;;;;GAOG;AACH,iBAAS,YAAY,CAAC,EACpB,QAAQ,EACR,SAAS,EACT,OAAO,EACP,YAAY,EACZ,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,GAAG;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC;CAC/B,qBAWA;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"pending-label.d.ts","sourceRoot":"","sources":["../../src/components/pending-label.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAIpC;;;;;;;;;;;;;;;GAeG;AACH,iBAAS,YAAY,CAAC,EACpB,QAAQ,EACR,SAAS,EACT,OAAO,EACP,YAAY,EACZ,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,GAAG;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC;CAC/B,qBAWA;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}