@nadicodeai/ui 12.1.96 → 12.1.97

package/dist/components/native-select.js

@@ -3,6 +3,22 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { cn } from "../lib/utils.js";
 import { ChevronDownIcon } from "lucide-react";
+/**
+ * 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.
+ */
 function NativeSelect({ className, size = "default", ref, ...props }) {
     const select = React.useRef(null);
     const setRef = React.useCallback((node) => {

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

@@ -1,4 +1,18 @@
 import { NavigationMenu as NavigationMenuPrimitive } from "@base-ui/react/navigation-menu";
+/**
+ * A website header's top-level links, some opening a panel of links.
+ *
+ * @family Navigation
+ * @when The website's header: a few top-level destinations, where one may open a panel of related
+ * pages.
+ * @instead A product's navigation is its `Sidebar`. Commands are a menu; sibling views are tabs.
+ * @behaviour Opens on hover and on click; one panel at a time, positioned under its trigger. Escape
+ * closes it and returns focus.
+ * @words Nouns, one or two words, sentence case. A panel's links name their page and may carry one
+ * short line.
+ * @access A labelled `nav`; triggers expose `aria-expanded`; links are real anchors with
+ * `aria-current="page"` on the current one.
+ */
 declare function NavigationMenu({ align, className, children, ...props }: NavigationMenuPrimitive.Root.Props & Pick<NavigationMenuPrimitive.Positioner.Props, "align">): import("react").JSX.Element;
 declare function NavigationMenuList({ className, ...props }: React.ComponentPropsWithRef<typeof NavigationMenuPrimitive.List>): import("react").JSX.Element;
 declare function NavigationMenuItem({ className, ...props }: React.ComponentPropsWithRef<typeof NavigationMenuPrimitive.Item>): import("react").JSX.Element;

package/dist/components/navigation-menu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation-menu.d.ts","sourceRoot":"","sources":["../../src/components/navigation-menu.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,IAAI,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAM3F,iBAAS,cAAc,CAAC,EACtB,KAAe,EACf,SAAS,EACT,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,uBAAuB,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,uBAAuB,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,+BAc9F;AAED,iBAAS,kBAAkB,CAAC,EAC1B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,qBAAqB,CAAC,OAAO,uBAAuB,CAAC,IAAI,CAAC,+BAQlE;AAED,iBAAS,kBAAkB,CAAC,EAC1B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,qBAAqB,CAAC,OAAO,uBAAuB,CAAC,IAAI,CAAC,+BAQlE;AAED,QAAA,MAAM,0BAA0B,oFAE/B,CAAC;AAEF,iBAAS,qBAAqB,CAAC,EAC7B,SAAS,EACT,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,uBAAuB,CAAC,OAAO,CAAC,KAAK,+BAcvC;AAED,iBAAS,qBAAqB,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,uBAAuB,CAAC,OAAO,CAAC,KAAK,+BAW5F;AAED,iBAAS,wBAAwB,CAAC,EAChC,SAAS,EACT,IAAe,EACf,UAAc,EACd,KAAe,EACf,WAAe,EACf,GAAG,KAAK,EACT,EAAE,uBAAuB,CAAC,UAAU,CAAC,KAAK,+BAoB1C;AAED,iBAAS,kBAAkB,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,uBAAuB,CAAC,IAAI,CAAC,KAAK,+BAWtF;AAED,iBAAS,uBAAuB,CAAC,EAC/B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,qBAAqB,CAAC,OAAO,uBAAuB,CAAC,IAAI,CAAC,+BAWlE;AAED,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,0BAA0B,EAC1B,wBAAwB,GACzB,CAAC"}
+{"version":3,"file":"navigation-menu.d.ts","sourceRoot":"","sources":["../../src/components/navigation-menu.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,IAAI,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAM3F;;;;;;;;;;;;;GAaG;AACH,iBAAS,cAAc,CAAC,EACtB,KAAe,EACf,SAAS,EACT,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,uBAAuB,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,uBAAuB,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,+BAc9F;AAED,iBAAS,kBAAkB,CAAC,EAC1B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,qBAAqB,CAAC,OAAO,uBAAuB,CAAC,IAAI,CAAC,+BAQlE;AAED,iBAAS,kBAAkB,CAAC,EAC1B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,qBAAqB,CAAC,OAAO,uBAAuB,CAAC,IAAI,CAAC,+BAQlE;AAED,QAAA,MAAM,0BAA0B,oFAE/B,CAAC;AAEF,iBAAS,qBAAqB,CAAC,EAC7B,SAAS,EACT,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,uBAAuB,CAAC,OAAO,CAAC,KAAK,+BAcvC;AAED,iBAAS,qBAAqB,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,uBAAuB,CAAC,OAAO,CAAC,KAAK,+BAW5F;AAED,iBAAS,wBAAwB,CAAC,EAChC,SAAS,EACT,IAAe,EACf,UAAc,EACd,KAAe,EACf,WAAe,EACf,GAAG,KAAK,EACT,EAAE,uBAAuB,CAAC,UAAU,CAAC,KAAK,+BAoB1C;AAED,iBAAS,kBAAkB,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,uBAAuB,CAAC,IAAI,CAAC,KAAK,+BAWtF;AAED,iBAAS,uBAAuB,CAAC,EAC/B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,qBAAqB,CAAC,OAAO,uBAAuB,CAAC,IAAI,CAAC,+BAWlE;AAED,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,0BAA0B,EAC1B,wBAAwB,GACzB,CAAC"}

package/dist/components/navigation-menu.js

@@ -3,6 +3,20 @@ import { NavigationMenu as NavigationMenuPrimitive } from "@base-ui/react/naviga
 import { cva } from "class-variance-authority";
 import { cn } from "../lib/utils.js";
 import { ChevronDownIcon } from "lucide-react";
+/**
+ * A website header's top-level links, some opening a panel of links.
+ *
+ * @family Navigation
+ * @when The website's header: a few top-level destinations, where one may open a panel of related
+ * pages.
+ * @instead A product's navigation is its `Sidebar`. Commands are a menu; sibling views are tabs.
+ * @behaviour Opens on hover and on click; one panel at a time, positioned under its trigger. Escape
+ * closes it and returns focus.
+ * @words Nouns, one or two words, sentence case. A panel's links name their page and may carry one
+ * short line.
+ * @access A labelled `nav`; triggers expose `aria-expanded`; links are real anchors with
+ * `aria-current="page"` on the current one.
+ */
 function NavigationMenu({ align = "start", className, children, ...props }) {
     return (_jsxs(NavigationMenuPrimitive.Root, { "data-slot": "navigation-menu", className: cn("group/navigation-menu relative flex max-w-max flex-1 items-center justify-center", className), ...props, children: [children, _jsx(NavigationMenuPositioner, { align: align })] }));
 }

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

@@ -2,7 +2,8 @@ import type { ComponentProps, ReactElement, ReactNode } from "react";
 export type NoticeBannerTone = "neutral" | "info" | "warning" | "destructive";
 export type NoticeBannerLiveRegion = "off" | "polite";
 export type NoticeBannerProps = {
-    action?: ReactElement;
+    /** The fix the page offers, as a button or a link. Required: a condition is shown with its fix. */
+    action: ReactElement;
     className?: string;
     description?: ReactNode;
     detail?: ReactNode;
@@ -11,8 +12,14 @@ export type NoticeBannerProps = {
     tone: NoticeBannerTone;
 } & Omit<ComponentProps<"div">, "children" | "title">;
 /**
- * Non-blocking operational, stale-data, replacement, and read-only guidance, and
- * a section that cannot be shown.
+ * A condition of the whole page, the account or the service, with its fix.
+ *
+ * @family Feedback
+ * @when A condition of the whole page, the account or the service that the page itself can resolve, with that resolving action on the banner. One at a time, above the page's content, under its title.
+ * @instead For one section use `MessageNotice placement="section"`. For a measured level use a `KpiCard` with its tone; crossing a threshold is a notification in the inbox, not a banner.
+ * @behaviour Tone `neutral` (the plain card fill), `info`, `warning`, `destructive`: a soft ground, deep text, the 1 px line edge, 6 px corners; neutral and info take the Info mark, warning and destructive the TriangleAlert. No close button on an unresolved condition. No action, no banner: `action` is required.
+ * @words Title names the condition, description what it stops, the action the fix as verb and noun: "Open Slack settings", "Sign in". Sentence case, no "Please". The words come from the product's catalogue code.
+ * @access `liveRegion="polite"` gives `role="status"`, announced once when it appears; `"off"` gives `role="note"` for one already there at load. The mark is hidden.
  */
 export declare function NoticeBanner({ action, className, description, detail, liveRegion, title, tone, ...props }: NoticeBannerProps): import("react").JSX.Element;
 //# sourceMappingURL=notice-banner.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"notice-banner.d.ts","sourceRoot":"","sources":["../../src/components/notice-banner.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAKrE,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,aAAa,CAAC;AAC9E,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEtD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,UAAU,EAAE,sBAAsB,CAAC;IACnC,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC;AAEtD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,EAC3B,MAAM,EACN,SAAS,EACT,WAAW,EACX,MAAM,EACN,UAAU,EACV,KAAK,EACL,IAAI,EACJ,GAAG,KAAK,EACT,EAAE,iBAAiB,+BAyBnB"}
+{"version":3,"file":"notice-banner.d.ts","sourceRoot":"","sources":["../../src/components/notice-banner.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAKrE,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,aAAa,CAAC;AAC9E,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEtD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,mGAAmG;IACnG,MAAM,EAAE,YAAY,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,UAAU,EAAE,sBAAsB,CAAC;IACnC,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC;AAEtD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,EAC3B,MAAM,EACN,SAAS,EACT,WAAW,EACX,MAAM,EACN,UAAU,EACV,KAAK,EACL,IAAI,EACJ,GAAG,KAAK,EACT,EAAE,iBAAiB,+BAyBnB"}

package/dist/components/notice-banner.js

@@ -2,11 +2,17 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Info, TriangleAlert } from "lucide-react";
 import { Alert, AlertAction, AlertDescription, AlertTitle } from "./alert.js";
 /**
- * Non-blocking operational, stale-data, replacement, and read-only guidance, and
- * a section that cannot be shown.
+ * A condition of the whole page, the account or the service, with its fix.
+ *
+ * @family Feedback
+ * @when A condition of the whole page, the account or the service that the page itself can resolve, with that resolving action on the banner. One at a time, above the page's content, under its title.
+ * @instead For one section use `MessageNotice placement="section"`. For a measured level use a `KpiCard` with its tone; crossing a threshold is a notification in the inbox, not a banner.
+ * @behaviour Tone `neutral` (the plain card fill), `info`, `warning`, `destructive`: a soft ground, deep text, the 1 px line edge, 6 px corners; neutral and info take the Info mark, warning and destructive the TriangleAlert. No close button on an unresolved condition. No action, no banner: `action` is required.
+ * @words Title names the condition, description what it stops, the action the fix as verb and noun: "Open Slack settings", "Sign in". Sentence case, no "Please". The words come from the product's catalogue code.
+ * @access `liveRegion="polite"` gives `role="status"`, announced once when it appears; `"off"` gives `role="note"` for one already there at load. The mark is hidden.
  */
 export function NoticeBanner({ action, className, description, detail, liveRegion, title, tone, ...props }) {
     const Icon = tone === "warning" || tone === "destructive" ? TriangleAlert : Info;
     const isLive = liveRegion === "polite";
-    return (_jsxs(Alert, { "aria-atomic": isLive ? "true" : undefined, "aria-live": isLive ? "polite" : undefined, className: className, "data-live-region": liveRegion, "data-notice-banner": true, "data-tone": tone, role: isLive ? "status" : "note", variant: tone === "neutral" ? "default" : tone, ...props, children: [_jsx(Icon, { "aria-hidden": "true" }), _jsx(AlertTitle, { children: title }), _jsxs(AlertDescription, { className: "min-w-0 flex flex-col gap-2", children: [description ? _jsx("div", { "data-notice-description": true, children: description }) : null, detail ? _jsx("div", { "data-notice-detail": true, children: detail }) : null] }), action ? _jsx(AlertAction, { "data-notice-action": true, children: action }) : null] }));
+    return (_jsxs(Alert, { "aria-atomic": isLive ? "true" : undefined, "aria-live": isLive ? "polite" : undefined, className: className, "data-live-region": liveRegion, "data-notice-banner": true, "data-tone": tone, role: isLive ? "status" : "note", variant: tone === "neutral" ? "default" : tone, ...props, children: [_jsx(Icon, { "aria-hidden": "true" }), _jsx(AlertTitle, { children: title }), _jsxs(AlertDescription, { className: "min-w-0 flex flex-col gap-2", children: [description ? _jsx("div", { "data-notice-description": true, children: description }) : null, detail ? _jsx("div", { "data-notice-detail": true, children: detail }) : null] }), _jsx(AlertAction, { "data-notice-action": true, children: action })] }));
 }

package/dist/components/numbered-steps.d.ts

@@ -0,0 +1,33 @@
+import type { ReactNode } from "react";
+export type NumberedStep = {
+    id: string;
+    /** The person's step, or a finished one in the past tense. */
+    title: string;
+    description?: ReactNode;
+    /** The step's own action, under it, with its platform line. */
+    action?: ReactNode;
+};
+export type NumberedStepsProps = {
+    /** "How to start" */
+    label: string;
+    steps: readonly NumberedStep[];
+    /** Where the sequence tracks real progress: the current step and its word, "Now". Instructions leave it out. */
+    current?: {
+        id: string;
+        label: string;
+    };
+    /** One bordered list with a seam between steps. */
+    framed?: boolean;
+};
+/**
+ * Steps a person follows, each with its number, its words and its own action.
+ *
+ * @family Other
+ * @when A short sequence the person does: installing Nadia from Downloads, connecting Teams, the Dashboard's setup guide; or a sequence whose real progress the page tracks, such as the company check.
+ * @instead Stages the system runs on an entry screen are the EntryStageList; the steps of an Agent's run are a RunTimeline; a setup with a wait is a FormDrawer with its "Step 2 of 3" line.
+ * @behaviour Each step is a 28 px square number in label-mono, its title, one muted description and, under it, the step's own action. Instructions mark no step and every number stays muted, because the page cannot know which one the person is on. Where the page tracks real progress, `current` turns that step's number to ink and writes its word beside the title. `framed` draws one bordered list with a seam between steps. It is the one owner of a drawn step number.
+ * @words The title is what the person does, in the imperative ("Install Nadia"), or a finished step in the past tense ("Sofia looked up acme.it"). The current step's word is short: "Now". An action names its verb and carries its platform line ("macOS · 2.14.0 · Apple silicon").
+ * @access An ordered list named by `label`, so assistive technology reads the count and position; the drawn numbers are hidden. The current step carries `aria-current="step"`. The titles are not headings, so the list never breaks the page's heading order.
+ */
+export declare function NumberedSteps({ label, steps, current, framed }: NumberedStepsProps): import("react").JSX.Element;
+//# sourceMappingURL=numbered-steps.d.ts.map

package/dist/components/numbered-steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numbered-steps.d.ts","sourceRoot":"","sources":["../../src/components/numbered-steps.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IAC/B,gHAAgH;IAChH,OAAO,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,mDAAmD;IACnD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAc,EAAE,EAAE,kBAAkB,+BAsD1F"}

package/dist/components/numbered-steps.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../lib/utils.js";
+/**
+ * Steps a person follows, each with its number, its words and its own action.
+ *
+ * @family Other
+ * @when A short sequence the person does: installing Nadia from Downloads, connecting Teams, the Dashboard's setup guide; or a sequence whose real progress the page tracks, such as the company check.
+ * @instead Stages the system runs on an entry screen are the EntryStageList; the steps of an Agent's run are a RunTimeline; a setup with a wait is a FormDrawer with its "Step 2 of 3" line.
+ * @behaviour Each step is a 28 px square number in label-mono, its title, one muted description and, under it, the step's own action. Instructions mark no step and every number stays muted, because the page cannot know which one the person is on. Where the page tracks real progress, `current` turns that step's number to ink and writes its word beside the title. `framed` draws one bordered list with a seam between steps. It is the one owner of a drawn step number.
+ * @words The title is what the person does, in the imperative ("Install Nadia"), or a finished step in the past tense ("Sofia looked up acme.it"). The current step's word is short: "Now". An action names its verb and carries its platform line ("macOS · 2.14.0 · Apple silicon").
+ * @access An ordered list named by `label`, so assistive technology reads the count and position; the drawn numbers are hidden. The current step carries `aria-current="step"`. The titles are not headings, so the list never breaks the page's heading order.
+ */
+export function NumberedSteps({ label, steps, current, framed = false }) {
+    return (_jsx("ol", { "aria-label": label, className: framed
+            ? "grid divide-y divide-border rounded-md border border-border bg-card"
+            : "grid gap-6", "data-slot": "numbered-steps", children: steps.map((step, index) => {
+            const word = current && step.id === current.id ? current.label : undefined;
+            const isCurrent = word !== undefined;
+            return (_jsxs("li", { "aria-current": isCurrent ? "step" : undefined, className: cn("grid grid-cols-[1.75rem_minmax(0,1fr)] gap-x-3 gap-y-1", framed && "p-4"), children: [_jsx("span", { "aria-hidden": "true", className: isCurrent
+                            ? "flex size-7 items-center justify-center rounded-md bg-foreground font-label-mono text-label-mono tabular-nums text-background"
+                            : "flex size-7 items-center justify-center rounded-md bg-muted font-label-mono text-label-mono tabular-nums text-muted-foreground", children: index + 1 }), _jsxs("div", { className: "flex min-h-7 min-w-0 flex-wrap items-center gap-2", children: [_jsx("span", { className: "text-body-sm font-medium text-foreground", children: step.title }), isCurrent ? (_jsx("span", { className: "font-label-mono text-label-mono uppercase text-muted-foreground", children: word })) : null] }), step.description ? (_jsx("div", { className: "col-start-2 text-body-sm text-muted-foreground", children: step.description })) : null, step.action ? (_jsx("div", { className: "col-start-2 grid justify-items-start gap-1.5 pt-3", children: step.action })) : null] }, step.id));
+        }) }));
+}

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

@@ -0,0 +1,37 @@
+import type { ComponentProps, ReactElement, ReactNode } from "react";
+import { type IdentityMarkProps } from "./identity-mark.js";
+import { type PageCommand, type PageMenu } from "./page-actions.js";
+export type ObjectPageProps = {
+    /** The object's mark, drawn at 64. */
+    mark: IdentityMarkProps;
+    name: string;
+    /** Given where the name is the page's h1 (the product's chrome draws no title row here). */
+    headingProps?: Omit<ComponentProps<"h1">, "children">;
+    /** One line saying what it is: "Customer of Partner Alpha · since 3 August 2026". */
+    description?: ReactNode;
+    /** Key facts as labelled values in one row. */
+    facts?: readonly {
+        label: string;
+        value: ReactNode;
+    }[];
+    /** On the name's row: one secondary action, then the three dots. */
+    actions?: {
+        secondary?: PageCommand;
+        menu?: PageMenu;
+    };
+    /** The sections, each a card that owns a decision: ObjectSection, RecordList with a heading, SettingsSection, ActivityFeed. */
+    children: ReactNode;
+};
+/**
+ * One object's page: its mark, name, one line and key facts on the page ground, its commands on the name's row, then
+ * its sections as cards.
+ *
+ * @family Compositions
+ * @when One thing a person opened from a list and now reads or acts on: a customer, a partner, an Installation, a Library entry.
+ * @instead A list of records is a CollectionPage; a page of settings only is a SettingsPage; an Agent opens on its AgentProfileCard, the documented exception.
+ * @behaviour The header sits on the page, never in a card: the mark at 64, the name, one line, the facts in one row, and at the trailing edge one secondary action then the three dots; below `md` the actions wrap under the name. The sections follow, 24 apart, each drawing its own states.
+ * @words The name as the object is called everywhere else; the line says what it is and whose ("Customer of Partner Alpha · since 3 August 2026"); a fact's label is a noun ("Plan"), its value the figure; the menu's trigger reads "More for {name}".
+ * @access With `headingProps` the name is the page's h1; without them it is text, for a product whose chrome already titles the page. The facts are a description list; the mark is decorative beside the name.
+ */
+export declare function ObjectPage({ mark, name, headingProps, description, facts, actions, children, }: ObjectPageProps): ReactElement;
+//# sourceMappingURL=object-page.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"object-page.d.ts","sourceRoot":"","sources":["../../src/components/object-page.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGrE,OAAO,EAAgB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAkB,MAAM,gBAAgB,CAAC;AAEjF,MAAM,MAAM,eAAe,GAAG;IAC5B,sCAAsC;IACtC,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,4FAA4F;IAC5F,YAAY,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC;IACtD,qFAAqF;IACrF,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,+CAA+C;IAC/C,KAAK,CAAC,EAAE,SAAS;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,CAAA;KAAE,EAAE,CAAC;IACvD,oEAAoE;IACpE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,WAAW,CAAC;QAAC,IAAI,CAAC,EAAE,QAAQ,CAAA;KAAE,CAAC;IACvD,+HAA+H;IAC/H,QAAQ,EAAE,SAAS,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,EACzB,IAAI,EACJ,IAAI,EACJ,YAAY,EACZ,WAAW,EACX,KAAK,EACL,OAAO,EACP,QAAQ,GACT,EAAE,eAAe,GAAG,YAAY,CA6ChC"}

package/dist/components/object-page.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../lib/utils.js";
+import { IdentityMark } from "./identity-mark.js";
+import { PageActionsRow } from "./page-actions.js";
+/**
+ * One object's page: its mark, name, one line and key facts on the page ground, its commands on the name's row, then
+ * its sections as cards.
+ *
+ * @family Compositions
+ * @when One thing a person opened from a list and now reads or acts on: a customer, a partner, an Installation, a Library entry.
+ * @instead A list of records is a CollectionPage; a page of settings only is a SettingsPage; an Agent opens on its AgentProfileCard, the documented exception.
+ * @behaviour The header sits on the page, never in a card: the mark at 64, the name, one line, the facts in one row, and at the trailing edge one secondary action then the three dots; below `md` the actions wrap under the name. The sections follow, 24 apart, each drawing its own states.
+ * @words The name as the object is called everywhere else; the line says what it is and whose ("Customer of Partner Alpha · since 3 August 2026"); a fact's label is a noun ("Plan"), its value the figure; the menu's trigger reads "More for {name}".
+ * @access With `headingProps` the name is the page's h1; without them it is text, for a product whose chrome already titles the page. The facts are a description list; the mark is decorative beside the name.
+ */
+export function ObjectPage({ mark, name, headingProps, description, facts, actions, children, }) {
+    const nameClass = "text-heading-md break-words text-foreground";
+    return (_jsxs("div", { className: "grid min-w-0 gap-6", "data-slot": "object-page", children: [_jsxs("header", { className: "flex min-w-0 flex-wrap items-start gap-x-5 gap-y-4", "data-slot": "object-page-header", children: [_jsx(IdentityMark, { ...mark, size: 64 }), _jsxs("div", { className: "grid min-w-0 flex-1 basis-60 gap-1", children: [headingProps ? (_jsx("h1", { ...headingProps, className: cn(nameClass, "outline-none", headingProps.className), children: name })) : (_jsx("p", { className: nameClass, children: name })), description ? (_jsx("div", { className: "min-w-0 text-body-sm text-muted-foreground", children: description })) : null, facts && facts.length > 0 ? (_jsx("dl", { className: "mt-3 flex min-w-0 flex-wrap gap-x-8 gap-y-2", "data-slot": "object-page-facts", children: facts.map((fact) => (_jsxs("div", { className: "grid min-w-0 gap-1", children: [_jsx("dt", { className: "text-label-sm text-muted-foreground", children: fact.label }), _jsx("dd", { className: "min-w-0 text-label font-medium break-words text-foreground", children: fact.value })] }, fact.label))) })) : null] }), actions?.secondary || actions?.menu ? (_jsx("div", { className: "flex basis-full md:basis-auto md:justify-end", children: _jsx(PageActionsRow, { ...actions }) })) : null] }), children] }));
+}

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"}