@nadicodeai/ui 12.1.96 → 12.1.97

package/AGENTS.md

@@ -6,7 +6,8 @@ product compositions. Source lives in `src/`; consumers receive `dist/` through
 
 Every design rule a component follows is in `../design-system/DESIGN.md`:
 tokens, roles, materials, glass, motion, status, activity, Agent orbs, marks and
-the component rules in its "Components" section. This file holds only how the
+the component rules in its "Components" section. A component change a person
+can see goes through `product-design` first. This file holds only how the
 package is kept.
 
 - **Styling.** A component uses the semantic roles and the generated tokens, and
@@ -29,6 +30,9 @@ package is kept.
   package ships no auth abstraction. A value or function an app's server code
   calls lives in a module without `"use client"`, and only the Portal's
   production build (`npm run build -w @nadicodeai/portal`) proves it.
+- **Usage.** The main export's TSDoc carries `@family`, `@when`, `@instead`,
+  `@behaviour`, `@words` and `@access`; `generate:usage` refreshes the
+  showcase's index from it, and `lint` fails until it runs.
 - **Agents.** `@nadicodeai/ui/agents` re-exports assistant-ui and our reviewed
   compositions; `@nadicodeai/ui/agent-orb` is the React-free entry a native
   startup screen paints an orb with before React loads.

package/dist/components/accordion.d.ts

@@ -1,4 +1,17 @@
 import { Accordion as AccordionPrimitive } from "@base-ui/react/accordion";
+/**
+ * Sections that open and close under their headings.
+ *
+ * @family Other
+ * @when Optional or advanced content in named sections, such as the questions of a help page.
+ * @instead One piece of supporting detail is `Disclosure`. A long block cut short is
+ * `ExpandableBlock`. The page's main answer is never hidden in one.
+ * @behaviour Related sections may stay open together; exclusive ones open one at a time. The
+ * trigger's chevron turns when open.
+ * @words Each trigger names its topic as a noun phrase or a question a person asks.
+ * @access Each trigger is a `button` with `aria-expanded` controlling its panel; headings keep the
+ * page's outline.
+ */
 declare function Accordion({ className, ...props }: AccordionPrimitive.Root.Props): import("react").JSX.Element;
 declare function AccordionItem({ className, ...props }: AccordionPrimitive.Item.Props): import("react").JSX.Element;
 declare function AccordionTrigger({ className, children, ...props }: AccordionPrimitive.Trigger.Props): import("react").JSX.Element;

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

@@ -1 +1 @@
-{"version":3,"file":"accordion.d.ts","sourceRoot":"","sources":["../../src/components/accordion.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,IAAI,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAK3E,iBAAS,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,CAAC,IAAI,CAAC,KAAK,+BAQxE;AAED,iBAAS,aAAa,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,CAAC,IAAI,CAAC,KAAK,+BAQ5E;AAED,iBAAS,gBAAgB,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,CAAC,OAAO,CAAC,KAAK,+BAmB5F;AAED,iBAAS,gBAAgB,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,CAAC,KAAK,CAAC,KAAK,+BAiB1F;AAED,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC"}
+{"version":3,"file":"accordion.d.ts","sourceRoot":"","sources":["../../src/components/accordion.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,IAAI,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAK3E;;;;;;;;;;;;GAYG;AACH,iBAAS,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,CAAC,IAAI,CAAC,KAAK,+BAQxE;AAED,iBAAS,aAAa,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,CAAC,IAAI,CAAC,KAAK,+BAQ5E;AAED,iBAAS,gBAAgB,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,CAAC,OAAO,CAAC,KAAK,+BAmB5F;AAED,iBAAS,gBAAgB,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,CAAC,KAAK,CAAC,KAAK,+BAiB1F;AAED,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/components/accordion.js

@@ -2,6 +2,19 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Accordion as AccordionPrimitive } from "@base-ui/react/accordion";
 import { cn } from "../lib/utils.js";
 import { ChevronDownIcon } from "lucide-react";
+/**
+ * Sections that open and close under their headings.
+ *
+ * @family Other
+ * @when Optional or advanced content in named sections, such as the questions of a help page.
+ * @instead One piece of supporting detail is `Disclosure`. A long block cut short is
+ * `ExpandableBlock`. The page's main answer is never hidden in one.
+ * @behaviour Related sections may stay open together; exclusive ones open one at a time. The
+ * trigger's chevron turns when open.
+ * @words Each trigger names its topic as a noun phrase or a question a person asks.
+ * @access Each trigger is a `button` with `aria-expanded` controlling its panel; headings keep the
+ * page's outline.
+ */
 function Accordion({ className, ...props }) {
     return (_jsx(AccordionPrimitive.Root, { "data-slot": "accordion", className: cn("flex w-full flex-col", className), ...props }));
 }

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

@@ -1,4 +1,9 @@
-import type { ReactElement, ReactNode } from "react";
+import type { ComponentProps, ReactElement, ReactNode } from "react";
+import type { MenuCommand } from "./action-menu.js";
+import { type MenuChoiceRowProps } from "./menu-choice-row.js";
+import type { PageCommandAction } from "./page-actions.js";
+import { type ResolvedMessage } from "./product-message.js";
+import { ThemeModeMenu } from "./theme-mode-switcher.js";
 /** Whose account it is: the name people recognise, the picture, and the lines under it. */
 export type AccountIdentity = {
     /**
@@ -31,34 +36,73 @@ export type AccountMenuIdentityProps = {
  * same block in both places.
  */
 export declare function AccountMenuIdentity({ className, identity, pictureOnly, size, }: AccountMenuIdentityProps): import("react").JSX.Element;
+export type AccountMenuCommand = MenuCommand & {
+    /** A reading at the row's end: "62% left". */
+    value?: ReactNode;
+};
+/** A product's own exclusive setting, in a submenu: Alveare's presence. */
+export type AccountMenuChoice = {
+    label: string;
+    icon: ReactElement;
+    value: string;
+    /** Each option's name, its mark, and one muted line under the name when the name alone does not say what it is. */
+    options: readonly {
+        value: string;
+        label: string;
+        mark?: ReactNode;
+        detail?: string;
+    }[];
+    onValueChange: (value: string) => void;
+};
+export type AccountMenuSignOut = {
+    /** "Sign out". */
+    label: string;
+    /** "Signing out". */
+    pendingLabel: string;
+    pending: boolean;
+    failure?: ResolvedMessage | null;
+    onSignOut: () => void;
+    /** Sign out opens the product's own confirmation, so the menu closes and leaves focus to it. */
+    confirms?: boolean;
+};
 export type AccountMenuProps = {
-    /** Where the menu sits against its trigger. */
-    align?: "center" | "end" | "start";
-    /** The groups under the header: what this account can do, ending in the way out. */
-    children: ReactNode;
-    className?: string;
-    /** Closes the trigger to further presses while the account is leaving. */
-    disabled?: boolean;
-    /** Sits beside the header, for a single icon-only action on the account itself. */
-    headerAction?: ReactNode;
     identity: AccountIdentity;
-    /** The trigger's accessible name; it carries only the identity otherwise. */
+    /** Names the trigger and the menu: "Account" reads "Account: Ada Rossi". */
     label: string;
-    /** Runs when the menu opens or closes, for a shell that records where it was. */
-    onOpenChange?: (open: boolean) => void;
+    /** The gear beside the identity, to the account's settings. */
+    settings?: PageCommandAction & {
+        label: string;
+    };
+    /** Applies at once and keeps the menu open. */
+    theme: ComponentProps<typeof ThemeModeMenu>;
+    language?: MenuChoiceRowProps<string> & {
+        icon: ReactElement;
+    };
+    choices?: readonly AccountMenuChoice[];
+    commands?: readonly AccountMenuCommand[];
+    signOut: AccountMenuSignOut;
     /**
      * The trigger shows the picture alone, for a navigation rail drawn too narrow
      * for the name; the menu still opens on the whole identity.
      */
     pictureOnly?: boolean;
-    side?: "bottom" | "left" | "right" | "top";
     /** The element the trigger renders as, when a shell has its own button. */
     triggerRender?: ReactElement;
+    align?: "center" | "end" | "start";
+    side?: "bottom" | "left" | "right" | "top";
+    /** Runs when the menu opens or closes, for a shell that records where it was. */
+    onOpenChange?: (open: boolean) => void;
 };
 /**
- * The account menu at the foot of a shell's navigation: press whose account it
- * is, and the menu opens on that same identity with what they can do beneath it.
- * One composition, so the Portal and the desktop read the same.
+ * The account menu at the foot of a shell's navigation: whose account it is,
+ * and the menu opening on that same identity with what they can do beneath it.
+ *
+ * @family Menus
+ * @when The account at the sidebar's foot in the Portal, Nadia and Alveare: the gear to the account's settings, Theme, Language, a product's own settings, its commands, and Sign out.
+ * @instead A record's or a page's commands are an ActionMenu; a setting with more than a few options or one that needs a Save belongs on a SettingsPage.
+ * @behaviour The menu opens upward on the identity. In order: the gear, Theme, Language, the product's choices as submenus, its commands with any reading at their end, and Sign out last in the error colour. Theme and Language apply at once and keep the menu open. While signing out, Sign out says its pending word, the menu stays open and the trigger is locked; a failure shows under it. A Sign out that `confirms` closes the menu instead, for the product's own confirmation.
+ * @words The menu's name ("Account"), the person's name and lines, then each row's noun or verb from the product's catalogue: "Theme", "Language", "Usage", "Sign out" and "Signing out".
+ * @access The trigger and the menu are named "{label}: {name}"; the gear carries its label; the pending sign-out is aria-busy and announced through a status; a failure is an alert.
  */
-export declare function AccountMenu({ align, children, className, disabled, headerAction, identity, label, onOpenChange, pictureOnly, side, triggerRender, }: AccountMenuProps): import("react").JSX.Element;
+export declare function AccountMenu({ align, choices, commands, identity, label, language, onOpenChange, pictureOnly, settings, side, signOut, theme, triggerRender, }: AccountMenuProps): import("react").JSX.Element;
 //# sourceMappingURL=account-menu.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"account-menu.d.ts","sourceRoot":"","sources":["../../src/components/account-menu.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAarD,2FAA2F;AAC3F,MAAM,MAAM,eAAe,GAAG;IAC5B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,eAAe,CAAC;IAC1B,8EAA8E;IAC9E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CACzB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,SAAS,EACT,QAAQ,EACR,WAAmB,EACnB,IAAgB,GACjB,EAAE,wBAAwB,+BA4B1B;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+CAA+C;IAC/C,KAAK,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,OAAO,CAAC;IACnC,oFAAoF;IACpF,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mFAAmF;IACnF,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,QAAQ,EAAE,eAAe,CAAC;IAC1B,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,IAAI,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;IAC3C,2EAA2E;IAC3E,aAAa,CAAC,EAAE,YAAY,CAAC;CAC9B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAe,EACf,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,QAAQ,EACR,KAAK,EACL,YAAY,EACZ,WAAmB,EACnB,IAAY,EACZ,aAAa,GACd,EAAE,gBAAgB,+BA4ClB"}
+{"version":3,"file":"account-menu.d.ts","sourceRoot":"","sources":["../../src/components/account-menu.tsx"],"names":[],"mappings":"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"}

package/dist/components/account-menu.js

@@ -1,8 +1,14 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { ChevronsUpDown, UserRound } from "lucide-react";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ChevronsUpDown, LogOut, Settings, UserRound } from "lucide-react";
 import { Avatar, AvatarFallback, AvatarImage } from "./avatar.js";
-import { DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuSeparator, DropdownMenuTrigger, } from "./dropdown-menu.js";
+import { DropdownMenu, DropdownMenuCommand, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, } from "./dropdown-menu.js";
+import { FieldError } from "./field.js";
+import { MenuChoiceRow } from "./menu-choice-row.js";
+import { PendingLabel } from "./pending-label.js";
+import { bodyBeyondTitle } from "./product-message.js";
+import { ThemeModeMenu } from "./theme-mode-switcher.js";
+import { MenuCommandRow, menuItemAction } from "../internal/record-menu-items.js";
 import { cn } from "../lib/utils.js";
 /**
  * The account's avatar beside its name and lines. The trigger shows it with the
@@ -13,10 +19,28 @@ export function AccountMenuIdentity({ className, identity, pictureOnly = false,
     return (_jsxs("span", { className: cn("flex min-w-0 items-center gap-2 text-left text-sm", className), "data-slot": "account-menu-identity", children: [_jsxs(Avatar, { "aria-hidden": "true", size: size === "lg" ? "default" : "sm", children: [identity.image ? _jsx(AvatarImage, { alt: "", src: identity.image }) : null, _jsx(AvatarFallback, { children: identity.initials || _jsx(UserRound, { "aria-hidden": "true", className: "size-3/5" }) })] }), pictureOnly ? null : (_jsxs("span", { className: "grid min-w-0 flex-1 gap-0.5 leading-tight", children: [_jsx("span", { className: "truncate font-medium text-foreground", children: identity.name }), (size === "lg" ? identity.lines : identity.lines?.slice(0, 1))?.map((line, index) => (_jsx("span", { className: "truncate text-xs font-normal text-muted-foreground", children: line }, index)))] }))] }));
 }
 /**
- * The account menu at the foot of a shell's navigation: press whose account it
- * is, and the menu opens on that same identity with what they can do beneath it.
- * One composition, so the Portal and the desktop read the same.
+ * The account menu at the foot of a shell's navigation: whose account it is,
+ * and the menu opening on that same identity with what they can do beneath it.
+ *
+ * @family Menus
+ * @when The account at the sidebar's foot in the Portal, Nadia and Alveare: the gear to the account's settings, Theme, Language, a product's own settings, its commands, and Sign out.
+ * @instead A record's or a page's commands are an ActionMenu; a setting with more than a few options or one that needs a Save belongs on a SettingsPage.
+ * @behaviour The menu opens upward on the identity. In order: the gear, Theme, Language, the product's choices as submenus, its commands with any reading at their end, and Sign out last in the error colour. Theme and Language apply at once and keep the menu open. While signing out, Sign out says its pending word, the menu stays open and the trigger is locked; a failure shows under it. A Sign out that `confirms` closes the menu instead, for the product's own confirmation.
+ * @words The menu's name ("Account"), the person's name and lines, then each row's noun or verb from the product's catalogue: "Theme", "Language", "Usage", "Sign out" and "Signing out".
+ * @access The trigger and the menu are named "{label}: {name}"; the gear carries its label; the pending sign-out is aria-busy and announced through a status; a failure is an alert.
  */
-export function AccountMenu({ align = "start", children, className, disabled, headerAction, identity, label, onOpenChange, pictureOnly = false, side = "top", triggerRender, }) {
-    return (_jsxs(DropdownMenu, { onOpenChange: onOpenChange, children: [_jsxs(DropdownMenuTrigger, { "aria-label": `${label}: ${identity.name}`, disabled: disabled, render: triggerRender ?? (_jsx("button", { className: "flex w-full min-w-0 items-center gap-2 rounded-sm p-1.5 text-left outline-none hover:bg-accent focus-visible:nc-focus-outline focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 data-[popup-open]:bg-accent", type: "button" })), children: [_jsx(AccountMenuIdentity, { className: pictureOnly ? undefined : "flex-1", identity: identity, pictureOnly: pictureOnly }), pictureOnly ? null : (_jsx(ChevronsUpDown, { "aria-hidden": "true", className: "ml-auto size-4 shrink-0 text-muted-foreground" }))] }), _jsxs(DropdownMenuContent, { align: align, "aria-label": `${label}: ${identity.name}`, className: cn("w-72 max-w-[calc(100vw-2rem)]", className), density: "comfortable", side: side, sideOffset: 8, children: [_jsxs(DropdownMenuGroup, { className: "flex min-w-0 items-center gap-1 pr-1.5", children: [_jsx(AccountMenuIdentity, { className: "min-w-0 flex-1 px-2 py-2", identity: identity, size: "lg" }), headerAction] }), _jsx(DropdownMenuSeparator, {}), children] })] }));
+export function AccountMenu({ align = "start", choices = [], commands = [], identity, label, language, onOpenChange, pictureOnly = false, settings, side = "top", signOut, theme, triggerRender, }) {
+    const name = `${label}: ${identity.name}`;
+    return (_jsxs(DropdownMenu, { onOpenChange: onOpenChange, children: [_jsxs(DropdownMenuTrigger, { "aria-label": name, disabled: signOut.pending, render: triggerRender ?? (_jsx("button", { className: "flex w-full min-w-0 items-center gap-2 rounded-sm p-1.5 text-left outline-none hover:bg-accent focus-visible:nc-focus-outline focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 data-[popup-open]:bg-accent", type: "button" })), children: [_jsx(AccountMenuIdentity, { className: pictureOnly ? undefined : "flex-1", identity: identity, pictureOnly: pictureOnly }), pictureOnly ? null : (_jsx(ChevronsUpDown, { "aria-hidden": "true", className: "ml-auto size-4 shrink-0 text-muted-foreground" }))] }), _jsxs(DropdownMenuContent, { align: align, "aria-label": name, className: "w-72 max-w-[calc(100vw-2rem)]", density: "comfortable", side: side, sideOffset: 8, children: [_jsxs(DropdownMenuGroup, { className: "flex min-w-0 items-center gap-1 pr-1.5", children: [_jsx(AccountMenuIdentity, { className: "min-w-0 flex-1 px-2 py-2", identity: identity, size: "lg" }), settings ? (_jsx(DropdownMenuItem, { "aria-label": settings.label, iconOnly: true, ...menuItemAction(settings), children: _jsx(Settings, { "aria-hidden": "true" }) })) : null] }), _jsx(DropdownMenuSeparator, {}), _jsxs(DropdownMenuGroup, { children: [_jsx(ThemeModeMenu, { ...theme }), language ? _jsx(MenuChoiceRow, { ...language }) : null, choices.map((choice) => (_jsx(AccountMenuChoiceRow, { choice: choice }, choice.label)))] }), commands.length > 0 ? (_jsxs(_Fragment, { children: [_jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuGroup, { children: commands.map(({ value, ...command }) => (_jsx(MenuCommandRow, { command: command, value: value }, command.label))) })] })) : null, _jsx(DropdownMenuSeparator, {}), _jsxs(DropdownMenuGroup, { children: [_jsx(DropdownMenuCommand, { "aria-busy": signOut.pending || undefined, closeOnClick: signOut.confirms === true, disabled: signOut.pending, icon: _jsx(LogOut, {}), onClick: () => {
+                                    if (!signOut.pending)
+                                        signOut.onSignOut();
+                                }, variant: "destructive", children: _jsx(PendingLabel, { pending: signOut.pending, pendingLabel: signOut.pendingLabel, children: signOut.label }) }), signOut.pending ? (_jsx("span", { className: "sr-only", role: "status", children: signOut.pendingLabel })) : null, signOut.failure ? (_jsxs(FieldError, { className: "mx-3 mb-1 break-words", "data-message-code": signOut.failure.code, children: [_jsx("span", { className: "block font-medium", children: signOut.failure.title }), bodyBeyondTitle(signOut.failure) ? (_jsx("span", { className: "block", children: bodyBeyondTitle(signOut.failure) })) : null] })) : null] })] })] }));
+}
+function AccountMenuChoiceRow({ choice }) {
+    const current = choice.options.find((option) => option.value === choice.value);
+    return (_jsxs(DropdownMenuSub, { children: [_jsxs(DropdownMenuSubTrigger, { className: "gap-2.5", children: [_jsx("span", { "aria-hidden": "true", className: "flex shrink-0 items-center text-muted-foreground", children: choice.icon }), _jsx("span", { className: "min-w-0 flex-1 truncate", children: choice.label }), current ? (_jsx(DropdownMenuShortcut, { className: "ml-0", children: current.label })) : null] }), _jsx(DropdownMenuSubContent, { children: _jsx(DropdownMenuRadioGroup, { "aria-label": choice.label, onValueChange: (next) => {
+                        const selected = choice.options.find((option) => option.value === next);
+                        if (selected)
+                            choice.onValueChange(selected.value);
+                    }, value: choice.value, children: choice.options.map((option) => (_jsxs(DropdownMenuRadioItem, { closeOnClick: false, value: option.value, children: [option.mark, option.detail ? (_jsxs("span", { className: "grid min-w-0 flex-1 gap-0.5 leading-tight", children: [_jsx("span", { className: "truncate", children: option.label }), _jsx("span", { className: "truncate text-xs text-muted-foreground", children: option.detail })] })) : (option.label)] }, option.value))) }) })] }));
 }

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

@@ -1,8 +1,64 @@
-import type { ReactNode } from "react";
-export type ActionMenuProps = {
+import type { ComponentProps, ReactElement, ReactNode } from "react";
+import { DropdownMenuContent } from "./dropdown-menu.js";
+import type { PageCommandAction } from "./page-actions.js";
+/** One command in a menu: its icon first, then its label. */
+export type MenuCommand = PageCommandAction & {
     label: string;
-    triggerId?: string;
-    children: ReactNode;
+    icon: ReactElement;
+    /** Read instead of the label when the label alone does not name the target: "Let Sofia use Gmail". */
+    accessibleName?: string | undefined;
+    /** Drawn last, after the divider, in the error colour. */
+    destructive?: boolean | undefined;
+    disabled?: boolean | undefined;
+    /** The value it acts on, in mono under its label: the address Copy address copies. */
+    detail?: string | undefined;
+    /** Why it cannot run now, read under its label; a disabled command keeps it visible. */
+    reason?: ReactNode;
 };
-export declare function ActionMenu({ label, triggerId, children }: ActionMenuProps): import("react").JSX.Element;
+/** A record's menu: whose it is, and what can be done to it. */
+export type RecordMenu = {
+    /** The trigger's accessible name, from the catalogue: "More for pec@acme.it". */
+    label: string;
+    /** The record the menu acts on, its first line: "pec@acme.it". */
+    record: string;
+    commands: readonly MenuCommand[];
+};
+export type ActionMenuProps = RecordMenu & {
+    triggerId?: string | undefined;
+    /** Controlled, for a host that stays visible while the menu is open (a message's hover bar). */
+    open?: boolean | undefined;
+    onOpenChange?: ((open: boolean) => void) | undefined;
+    /** false keeps the page interactive while the menu is open. */
+    modal?: boolean | undefined;
+    side?: "bottom" | "top" | undefined;
+    /** Where focus goes when the menu closes, when not its trigger: Edit hands it to a composer. */
+    finalFocus?: ComponentProps<typeof DropdownMenuContent>["finalFocus"];
+};
+/**
+ * A record's three dots: the menu of its secondary commands, headed by the record's name.
+ *
+ * @family Menus
+ * @when The secondary commands of one record from a visible trigger: the row's three dots, or the page's, which comes last in the title row.
+ * @instead For a record's main task use a visible button (Edit opens the row). For finding across everything use `CommandDialog`. For a value to choose use `Select`. For right-click use the mirror, `ActionContextMenu`.
+ * @behaviour Ghost 36 px trigger that keeps its fill while open. The menu opens aligned to the trigger's end, 6 px below: the record's name, the commands with their icons first and the value one acts on in mono under it, then the destructive ones after a divider in the error colour. Typeahead, arrows, Escape returns focus. A disabled command stays, greyed, with its reason under it. Nothing renders with no command.
+ * @words The trigger reads "More for {record}"; the header is the record's name. Commands are verb and noun in sentence case, "Remove mailbox", never a bare "Delete". About ten at most; rows wrap, never truncate.
+ * @access The trigger is a ghost icon button named by `label`, `aria-expanded` while open. `role="menu"`, items `menuitem` in a group named by the record; the value a command acts on and its reason are the item's description; icons hidden.
+ */
+export declare function ActionMenu({ label, record, commands, triggerId, open, onOpenChange, modal, side, finalFocus, }: ActionMenuProps): import("react").JSX.Element | null;
+/** The same commands on a right-click, Shift+F10 or the Menu key of the record's row. */
+export type ActionContextMenuProps = RecordMenu & {
+    /** The record's row, which keeps its own element and opens the menu. */
+    children: ReactElement;
+};
+/**
+ * A record's menu opened from its row by a right-click: the mirror of its `ActionMenu`.
+ *
+ * @family Menus
+ * @when A right-click or long-press convenience on a record that already has a visible menu with the same commands.
+ * @instead For anything a person must find use the visible three dots or a button: a context menu is never the only way. For global search use `CommandDialog`.
+ * @behaviour The dropdown's surface and rows exactly, opening at the pointer. The same commands in the same order, the same disabled reasons, destructive last after a divider. With no command the row renders alone.
+ * @words Identical to the visible menu's, in the same order; a command reached two ways reads the same both ways.
+ * @access The Menu key and Shift+F10 open it on the focused row. The menu is named by `label`; Escape closes it and returns focus to the row.
+ */
+export declare function ActionContextMenu({ label, record, commands, children }: ActionContextMenuProps): import("react").JSX.Element;
 //# sourceMappingURL=action-menu.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"action-menu.d.ts","sourceRoot":"","sources":["../../src/components/action-menu.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAMvC,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAC;CACrB,CAAC;AAEF,wBAAgB,UAAU,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,eAAe,+BAazE"}
+{"version":3,"file":"action-menu.d.ts","sourceRoot":"","sources":["../../src/components/action-menu.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAKrE,OAAO,EAAgB,mBAAmB,EAAuB,MAAM,4BAA4B,CAAC;AACpG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAGnE,6DAA6D;AAC7D,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,YAAY,CAAC;IACnB,sGAAsG;IACtG,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,wFAAwF;IACxF,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,CAAC;AAEF,gEAAgE;AAChE,MAAM,MAAM,UAAU,GAAG;IACvB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG;IACzC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,gGAAgG;IAChG,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,YAAY,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACrD,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,IAAI,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IACpC,gGAAgG;IAChG,UAAU,CAAC,EAAE,cAAc,CAAC,OAAO,mBAAmB,CAAC,CAAC,YAAY,CAAC,CAAC;CACvE,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,MAAM,EACN,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,IAAe,EACf,UAAU,GACX,EAAE,eAAe,sCAoBjB;AAED,yFAAyF;AACzF,MAAM,MAAM,sBAAsB,GAAG,UAAU,GAAG;IAChD,wEAAwE;IACxE,QAAQ,EAAE,YAAY,CAAC;CACxB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,sBAAsB,+BAU9F"}

package/dist/components/action-menu.js

@@ -2,7 +2,36 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { EllipsisIcon } from "lucide-react";
 import { Button } from "./button.js";
+import { ContextMenu, ContextMenuContent, ContextMenuTrigger } from "./context-menu.js";
 import { DropdownMenu, DropdownMenuContent, DropdownMenuTrigger } from "./dropdown-menu.js";
-export function ActionMenu({ label, triggerId, children }) {
-    return (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { id: triggerId, "aria-label": label, render: _jsx(Button, { variant: "ghost", size: "icon" }), children: _jsx(EllipsisIcon, { "aria-hidden": "true" }) }), _jsx(DropdownMenuContent, { align: "end", children: children })] }));
+import { RecordMenuItems } from "../internal/record-menu-items.js";
+/**
+ * A record's three dots: the menu of its secondary commands, headed by the record's name.
+ *
+ * @family Menus
+ * @when The secondary commands of one record from a visible trigger: the row's three dots, or the page's, which comes last in the title row.
+ * @instead For a record's main task use a visible button (Edit opens the row). For finding across everything use `CommandDialog`. For a value to choose use `Select`. For right-click use the mirror, `ActionContextMenu`.
+ * @behaviour Ghost 36 px trigger that keeps its fill while open. The menu opens aligned to the trigger's end, 6 px below: the record's name, the commands with their icons first and the value one acts on in mono under it, then the destructive ones after a divider in the error colour. Typeahead, arrows, Escape returns focus. A disabled command stays, greyed, with its reason under it. Nothing renders with no command.
+ * @words The trigger reads "More for {record}"; the header is the record's name. Commands are verb and noun in sentence case, "Remove mailbox", never a bare "Delete". About ten at most; rows wrap, never truncate.
+ * @access The trigger is a ghost icon button named by `label`, `aria-expanded` while open. `role="menu"`, items `menuitem` in a group named by the record; the value a command acts on and its reason are the item's description; icons hidden.
+ */
+export function ActionMenu({ label, record, commands, triggerId, open, onOpenChange, modal, side = "bottom", finalFocus, }) {
+    if (commands.length === 0)
+        return null;
+    return (_jsxs(DropdownMenu, { modal: modal, onOpenChange: onOpenChange ? (next) => onOpenChange(next) : undefined, open: open, children: [_jsx(DropdownMenuTrigger, { id: triggerId, "aria-label": label, render: _jsx(Button, { variant: "ghost", size: "icon" }), children: _jsx(EllipsisIcon, { "aria-hidden": "true" }) }), _jsx(DropdownMenuContent, { align: "end", finalFocus: finalFocus, side: side, children: _jsx(RecordMenuItems, { commands: commands, record: record }) })] }));
+}
+/**
+ * A record's menu opened from its row by a right-click: the mirror of its `ActionMenu`.
+ *
+ * @family Menus
+ * @when A right-click or long-press convenience on a record that already has a visible menu with the same commands.
+ * @instead For anything a person must find use the visible three dots or a button: a context menu is never the only way. For global search use `CommandDialog`.
+ * @behaviour The dropdown's surface and rows exactly, opening at the pointer. The same commands in the same order, the same disabled reasons, destructive last after a divider. With no command the row renders alone.
+ * @words Identical to the visible menu's, in the same order; a command reached two ways reads the same both ways.
+ * @access The Menu key and Shift+F10 open it on the focused row. The menu is named by `label`; Escape closes it and returns focus to the row.
+ */
+export function ActionContextMenu({ label, record, commands, children }) {
+    if (commands.length === 0)
+        return children;
+    return (_jsxs(ContextMenu, { children: [_jsx(ContextMenuTrigger, { render: children }), _jsx(ContextMenuContent, { "aria-label": label, children: _jsx(RecordMenuItems, { commands: commands, record: record }) })] }));
 }

package/dist/components/action-status.d.ts

@@ -7,9 +7,19 @@ interface ActionStatusProps {
     idleIcon?: ReactNode;
 }
 /**
- * A control's three words on one action: what it does, what it is doing, what
- * it did. Saving keeps the idle icon and the control's place, and changes only
- * the word; the caller marks the control `disabled` and `aria-busy`.
+ * A control's three words on one action: what it does, what it is doing, what it did.
+ *
+ * @family Status
+ * @when A control that reports its own action: what it does, what it is doing, what it did. Waits
+ * under about a second.
+ * @instead The record's resulting state is a `StatusBadge`. A wait past a second adds one waiting
+ * line beside the work. An Agent's work is her orb.
+ * @behaviour Saving keeps the idle icon, the size and the place; only the word changes. The caller
+ * sets `disabled` and `aria-busy`. Done shows the check.
+ * @words Verb and noun idle (*Save changes*), the verb in progress (*Saving*), the result
+ * (*Saved*). No ellipsis. Italian: *Salva modifiche*, *Salvataggio*, *Salvato*.
+ * @access The button's name is the current word. The result is announced once in a `role="status"`
+ * region; a failure as an alert.
  */
 declare function ActionStatus({ state, idle, busy, done, idleIcon }: ActionStatusProps): import("react").JSX.Element;
 export { ActionStatus };

package/dist/components/action-status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-status.d.ts","sourceRoot":"","sources":["../../src/components/action-status.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,UAAU,iBAAiB;IACzB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AACD;;;;GAIG;AACH,iBAAS,YAAY,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAe,EAAE,EAAE,iBAAiB,+BAOpF;AACD,OAAO,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"action-status.d.ts","sourceRoot":"","sources":["../../src/components/action-status.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,UAAU,iBAAiB;IACzB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AACD;;;;;;;;;;;;;;GAcG;AACH,iBAAS,YAAY,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAe,EAAE,EAAE,iBAAiB,+BAOpF;AACD,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/components/action-status.js

@@ -1,9 +1,19 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { CheckIcon } from "lucide-react";
 /**
- * A control's three words on one action: what it does, what it is doing, what
- * it did. Saving keeps the idle icon and the control's place, and changes only
- * the word; the caller marks the control `disabled` and `aria-busy`.
+ * A control's three words on one action: what it does, what it is doing, what it did.
+ *
+ * @family Status
+ * @when A control that reports its own action: what it does, what it is doing, what it did. Waits
+ * under about a second.
+ * @instead The record's resulting state is a `StatusBadge`. A wait past a second adds one waiting
+ * line beside the work. An Agent's work is her orb.
+ * @behaviour Saving keeps the idle icon, the size and the place; only the word changes. The caller
+ * sets `disabled` and `aria-busy`. Done shows the check.
+ * @words Verb and noun idle (*Save changes*), the verb in progress (*Saving*), the result
+ * (*Saved*). No ellipsis. Italian: *Salva modifiche*, *Salvataggio*, *Salvato*.
+ * @access The button's name is the current word. The result is announced once in a `role="status"`
+ * region; a failure as an alert.
  */
 function ActionStatus({ state, idle, busy, done, idleIcon = null }) {
     return (_jsxs(_Fragment, { children: [state === "done" ? _jsx(CheckIcon, { "aria-hidden": "true", "data-icon": "inline-start" }) : idleIcon, state === "saving" ? busy : state === "done" ? done : idle] }));

package/dist/components/activity-calendar.d.ts

@@ -21,6 +21,20 @@ type ActivityCalendarProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> &
     valueFormatter?: (value: number) => string;
 };
 declare function activityCalendarData(data: readonly ActivityCalendarDatum[], from: string, to: string): Activity[];
+/**
+ * On which days activity happened, as a year of cells.
+ *
+ * @family Charts
+ * @when On which measured days activity happened, over the window the data covers, up to the last
+ * 365 days.
+ * @instead Never added to fill a row. Amounts over time are a bar or area chart. It follows the
+ * selected metric and names its own from-to window.
+ * @behaviour One hue, chart-1, at four steps of opacity over an empty day; a legend from Less to
+ * More. Only measured history: unknown coverage stays unknown, never zero.
+ * @words The window as dates in the description. Each day's label: *8 October 2026: 42 requests*.
+ * @access Every day is a named cell for assistive technology; the legend steps are named too.
+ * Colour is never the only reading: the value is in each label.
+ */
 declare function ActivityCalendar({ data, from, to, locale, labels, valueFormatter, className, ...props }: ActivityCalendarProps): import("react").JSX.Element;
 export { ActivityCalendar, activityCalendarData };
 export type { ActivityCalendarDatum, ActivityCalendarLabels, ActivityCalendarProps };

package/dist/components/activity-calendar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity-calendar.d.ts","sourceRoot":"","sources":["../../src/components/activity-calendar.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAE5C,OAAO,EAML,KAAK,QAAQ,EACd,MAAM,uCAAuC,CAAC;AAG/C,KAAK,qBAAqB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,KAAK,sBAAsB,GAAG;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,KAAK,qBAAqB,GAAG,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC,GAAG;IAC9E,IAAI,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,sBAAsB,CAAC;IAC/B,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CAC5C,CAAC;AAwBF,iBAAS,oBAAoB,CAC3B,IAAI,EAAE,SAAS,qBAAqB,EAAE,EACtC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,QAAQ,EAAE,CAKZ;AAeD,iBAAS,gBAAgB,CAAC,EACxB,IAAI,EACJ,IAAI,EACJ,EAAE,EACF,MAAM,EACN,MAAM,EACN,cAAuE,EACvE,SAAS,EACT,GAAG,KAAK,EACT,EAAE,qBAAqB,+BAwCvB;AAED,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;AAClD,YAAY,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,CAAC"}
+{"version":3,"file":"activity-calendar.d.ts","sourceRoot":"","sources":["../../src/components/activity-calendar.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAE5C,OAAO,EAML,KAAK,QAAQ,EACd,MAAM,uCAAuC,CAAC;AAG/C,KAAK,qBAAqB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,KAAK,sBAAsB,GAAG;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,KAAK,qBAAqB,GAAG,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC,GAAG;IAC9E,IAAI,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,sBAAsB,CAAC;IAC/B,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CAC5C,CAAC;AAwBF,iBAAS,oBAAoB,CAC3B,IAAI,EAAE,SAAS,qBAAqB,EAAE,EACtC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,QAAQ,EAAE,CAKZ;AAeD;;;;;;;;;;;;;GAaG;AACH,iBAAS,gBAAgB,CAAC,EACxB,IAAI,EACJ,IAAI,EACJ,EAAE,EACF,MAAM,EACN,MAAM,EACN,cAAuE,EACvE,SAAS,EACT,GAAG,KAAK,EACT,EAAE,qBAAqB,+BAwCvB;AAED,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;AAClD,YAAY,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/components/activity-calendar.js

@@ -32,6 +32,20 @@ function localizedCalendarLabels(locale) {
         weekdays: Array.from({ length: 7 }, (_, day) => weekdays.format(new Date(Date.UTC(2024, 0, 7 + day)))),
     };
 }
+/**
+ * On which days activity happened, as a year of cells.
+ *
+ * @family Charts
+ * @when On which measured days activity happened, over the window the data covers, up to the last
+ * 365 days.
+ * @instead Never added to fill a row. Amounts over time are a bar or area chart. It follows the
+ * selected metric and names its own from-to window.
+ * @behaviour One hue, chart-1, at four steps of opacity over an empty day; a legend from Less to
+ * More. Only measured history: unknown coverage stays unknown, never zero.
+ * @words The window as dates in the description. Each day's label: *8 October 2026: 42 requests*.
+ * @access Every day is a named cell for assistive technology; the legend steps are named too.
+ * Colour is never the only reading: the value is in each label.
+ */
 function ActivityCalendar({ data, from, to, locale, labels, valueFormatter = (value) => new Intl.NumberFormat(locale).format(value), className, ...props }) {
     const calendarData = activityCalendarData(data, from, to);
     const dateFormatter = new Intl.DateTimeFormat(locale, {

package/dist/components/activity-feed.d.ts

@@ -0,0 +1,62 @@
+import type { ComponentProps, ReactNode } from "react";
+import { DateRangeControl } from "./chart-date-range-control.js";
+import { type CollectionFiltersProps } from "./collection-filters.js";
+import { type CollectionSearchProps } from "./collection-search.js";
+import { type EmptyStateKind } from "./empty-state.js";
+import { type IdentityMarkProps } from "./identity-mark.js";
+import { type PageCommand } from "./page-actions.js";
+import type { RecordStatus } from "./record-list.js";
+export type ActivityEvent = {
+    id: string;
+    /** Shown as the time of day in the viewer's zone; UTC and local on hover. */
+    at: Date | number | string;
+    /** Who did it, at 24: a person's initials, an Agent's orb, an Installation's tile. The system's own work has none. */
+    actor?: IdentityMarkProps;
+    /** The sentence: the actor's name in <strong>, the action, the object as a value link. */
+    summary: ReactNode;
+    /** Only for the exception: a revocation, a failure. */
+    status?: RecordStatus | null;
+    /** One muted line. */
+    detail?: ReactNode;
+};
+export type ActivityDay = {
+    id: string;
+    /** "Today" */
+    title: string;
+    /** "14 October" */
+    date: string;
+    /** Newest first. */
+    events: readonly ActivityEvent[];
+};
+export type ActivityFeedProps = {
+    label: string;
+    /** Newest day first; undefined while they load. */
+    days: readonly ActivityDay[] | undefined;
+    locale?: string;
+    /** The viewer's zone, which a page rendered on a server passes: each event's time of day is written in it. */
+    timeZone?: string;
+    /** Right above the rows; the product keeps them in the URL. */
+    search?: CollectionSearchProps;
+    filters?: CollectionFiltersProps;
+    range?: ComponentProps<typeof DateRangeControl>;
+    /** "Show older events"; never a page count. */
+    older?: PageCommand;
+    loadingLabel: string;
+    empty: EmptyStateKind<"nothingYet">;
+    /** Given only while a search or filter is set: "No events match these filters." with Clear filters. */
+    noMatch?: Omit<EmptyStateKind<"noResults">, "kind">;
+    failed?: EmptyStateKind<"failed">;
+};
+/**
+ * What happened to a record, and when: one row per event under its day,
+ * newest first.
+ *
+ * @family Compositions
+ * @when A record's history: a Customer's, a Partner's or an Installation's Activity tab in the Portal, the company wiki's updates in Nadia. Each answers "what happened, and when?".
+ * @instead The steps of one Agent run, read in order, are a RunTimeline; a list of records a person finds and acts on is a CollectionPage; a single "last changed" fact is a RecordTime.
+ * @behaviour The search, filters and window sit right above the rows, kept in the URL by the product. Days stand newest first, each a title and a muted date over one card of rows; a row is the time of day, the actor's 24 px mark, the sentence with a status badge only for an exception, and one muted line of detail. "Show older events" follows the last day; there is never a page count. States, first that holds: failed, loading (still rows in the row's shape), no match with Clear filters, nothing yet in one line, the days. Under 900 px the time moves under the sentence. It draws no card header: the tab is the title.
+ * @words The sentence names the actor in `<strong>`, the action in the past tense and the object as a link that keeps the text's colour: "Marco Rinaldi created the Agent Acme Quotes". Day titles are "Today", "Yesterday", then the weekday; dates are the product's own ("14 October"). Nothing yet: "No events yet." and what will appear. No match: "No events match these filters.".
+ * @access The toolbar is named by `label`; each day's title is a level-3 heading over a list of its events; while loading, one status named by `loadingLabel` stands for the rows; each time is a `<time>` with its exact moment for assistive technology. A system event has no mark, so nothing empty is announced.
+ */
+export declare function ActivityFeed({ label, days, locale, timeZone, search, filters, range, older, loadingLabel, empty, noMatch, failed, }: ActivityFeedProps): import("react").JSX.Element;
+//# sourceMappingURL=activity-feed.d.ts.map

package/dist/components/activity-feed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-feed.d.ts","sourceRoot":"","sources":["../../src/components/activity-feed.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AACzE,OAAO,EAAqB,KAAK,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACjG,OAAO,EAAoB,KAAK,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAE9F,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAgB,KAAK,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAClF,OAAO,EAAE,KAAK,WAAW,EAAqB,MAAM,2BAA2B,CAAC;AAChF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAK7D,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,6EAA6E;IAC7E,EAAE,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;IAC3B,sHAAsH;IACtH,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,0FAA0F;IAC1F,OAAO,EAAE,SAAS,CAAC;IACnB,uDAAuD;IACvD,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC7B,sBAAsB;IACtB,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,cAAc;IACd,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB;IACpB,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,IAAI,EAAE,SAAS,WAAW,EAAE,GAAG,SAAS,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8GAA8G;IAC9G,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,gBAAgB,CAAC,CAAC;IAChD,+CAA+C;IAC/C,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;IACpC,uGAAuG;IACvG,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC;IACpD,MAAM,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;CACnC,CAAC;AA2FF;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,IAAI,EACJ,MAAM,EACN,QAAQ,EACR,MAAM,EACN,OAAO,EACP,KAAK,EACL,KAAK,EACL,YAAY,EACZ,KAAK,EACL,OAAO,EACP,MAAM,GACP,EAAE,iBAAiB,+BAiCnB"}

package/dist/components/activity-feed.js

@@ -0,0 +1,54 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Card } from "./card.js";
+import { DateRangeControl } from "./chart-date-range-control.js";
+import { CollectionFilters } from "./collection-filters.js";
+import { CollectionSearch } from "./collection-search.js";
+import { CollectionToolbar } from "./collection-toolbar.js";
+import { EmptyState } from "./empty-state.js";
+import { IdentityMark } from "./identity-mark.js";
+import { PageCommandButton } from "./page-actions.js";
+import { RecordTime } from "./record-time.js";
+import { Skeleton } from "./skeleton.js";
+import { StatusBadge } from "./status-badge.js";
+const ROW = "grid grid-cols-[72px_24px_minmax(0,1fr)] items-start gap-3 px-4 py-3 max-[900px]:grid-cols-[24px_minmax(0,1fr)]";
+const UNDER_TEXT = "max-[900px]:col-start-2 max-[900px]:row-start-2";
+const MARK_CELL = "max-[900px]:col-start-1 max-[900px]:row-start-1";
+const TEXT_CELL = "max-[900px]:col-start-2 max-[900px]:row-start-1";
+const LOADING_ROWS = ["first", "second", "third"];
+function EventRow({ event, locale, timeZone }) {
+    return (_jsxs("li", { className: ROW, "data-slot": "activity-event", children: [_jsx("div", { className: `text-label-sm leading-5 ${UNDER_TEXT}`, "data-slot": "activity-event-time", children: _jsx(RecordTime, { at: event.at, locale: locale, mode: "clock", timeZone: timeZone }) }), _jsx("div", { className: `flex h-5 items-center ${MARK_CELL}`, children: event.actor ? _jsx(IdentityMark, { ...event.actor, size: 24 }) : null }), _jsxs("div", { className: `min-w-0 ${TEXT_CELL}`, children: [_jsxs("div", { className: "text-body-sm text-muted-foreground [&_strong]:font-medium [&_strong]:text-foreground", children: [event.summary, event.status ? (_jsx(StatusBadge, { className: "ml-1.5 align-middle", label: event.status.label, tone: event.status.tone })) : null] }), event.detail ? (_jsx("div", { className: "mt-0.5 text-label-sm text-muted-foreground", children: event.detail })) : null] })] }));
+}
+function LoadingRows({ label }) {
+    return (_jsx("div", { "aria-busy": "true", "aria-label": label, role: "status", children: _jsx(Card, { className: "gap-0 divide-y divide-border py-0", surface: "resting", children: LOADING_ROWS.map((row) => (_jsxs("div", { "aria-hidden": "true", className: ROW, children: [_jsx(Skeleton, { className: `mt-1 h-2.5 w-12 ${UNDER_TEXT}` }), _jsx(Skeleton, { className: `size-6 ${MARK_CELL}`, shape: "circle" }), _jsxs("div", { className: `grid gap-2 pt-1 ${TEXT_CELL}`, children: [_jsx(Skeleton, { className: "h-2.5 w-4/5" }), _jsx(Skeleton, { className: "h-2.5 w-3/5" })] })] }, row))) }) }));
+}
+function Days({ days, locale, timeZone, older, }) {
+    return (_jsxs(_Fragment, { children: [days.map((day) => (_jsxs("div", { className: "flex flex-col gap-2", "data-slot": "activity-day", children: [_jsxs("h3", { className: "text-body-sm font-medium text-foreground", children: [day.title, " ", _jsx("span", { className: "text-muted-foreground", children: day.date })] }), _jsx(Card, { className: "gap-0 divide-y divide-border py-0", render: _jsx("ul", {}), surface: "resting", children: day.events.map((event) => (_jsx(EventRow, { event: event, locale: locale, timeZone: timeZone }, event.id))) })] }, day.id))), older ? (_jsx("div", { className: "flex justify-center", children: _jsx(PageCommandButton, { command: older, variant: "outline" }) })) : null] }));
+}
+/**
+ * What happened to a record, and when: one row per event under its day,
+ * newest first.
+ *
+ * @family Compositions
+ * @when A record's history: a Customer's, a Partner's or an Installation's Activity tab in the Portal, the company wiki's updates in Nadia. Each answers "what happened, and when?".
+ * @instead The steps of one Agent run, read in order, are a RunTimeline; a list of records a person finds and acts on is a CollectionPage; a single "last changed" fact is a RecordTime.
+ * @behaviour The search, filters and window sit right above the rows, kept in the URL by the product. Days stand newest first, each a title and a muted date over one card of rows; a row is the time of day, the actor's 24 px mark, the sentence with a status badge only for an exception, and one muted line of detail. "Show older events" follows the last day; there is never a page count. States, first that holds: failed, loading (still rows in the row's shape), no match with Clear filters, nothing yet in one line, the days. Under 900 px the time moves under the sentence. It draws no card header: the tab is the title.
+ * @words The sentence names the actor in `<strong>`, the action in the past tense and the object as a link that keeps the text's colour: "Marco Rinaldi created the Agent Acme Quotes". Day titles are "Today", "Yesterday", then the weekday; dates are the product's own ("14 October"). Nothing yet: "No events yet." and what will appear. No match: "No events match these filters.".
+ * @access The toolbar is named by `label`; each day's title is a level-3 heading over a list of its events; while loading, one status named by `loadingLabel` stands for the rows; each time is a `<time>` with its exact moment for assistive technology. A system event has no mark, so nothing empty is announced.
+ */
+export function ActivityFeed({ label, days, locale, timeZone, search, filters, range, older, loadingLabel, empty, noMatch, failed, }) {
+    const nothingYet = !failed && days?.length === 0 && !noMatch;
+    const toolbar = !nothingYet && (search || filters || range) ? (_jsx(CollectionToolbar, { actions: filters || range ? (_jsxs(_Fragment, { children: [filters ? _jsx(CollectionFilters, { ...filters }) : null, range ? _jsx(DateRangeControl, { ...range }) : null] })) : undefined, label: label, search: search ? _jsx(CollectionSearch, { ...search }) : undefined, surface: "plain" })) : null;
+    let body;
+    if (failed)
+        body = _jsx(EmptyState, { ...failed, scope: "region" });
+    else if (days === undefined)
+        body = _jsx(LoadingRows, { label: loadingLabel });
+    else if (days.length === 0 && noMatch)
+        body = _jsx(EmptyState, { ...noMatch, kind: "noResults", scope: "region" });
+    else if (days.length === 0)
+        body = _jsx(EmptyState, { ...empty, scope: "region" });
+    else
+        body = _jsx(Days, { days: days, locale: locale, older: older, timeZone: timeZone });
+    return (_jsxs("div", { className: "flex min-w-0 flex-col gap-4", "data-slot": "activity-feed", children: [toolbar, body] }));
+}