themelia-ui 2.0.0 → 3.0.0

package/dist/components/admin/patterns/access/credential-list.d.ts

@@ -12,6 +12,7 @@ export interface Credential {
     disabled?: boolean;
 }
 export interface CredentialListProps extends Omit<ComponentProps<"div">, "children" | "title" | "onCopy"> {
+    /** id, name, value, and `displayValue` for the masked form shown in the row. */
     items: Credential[];
     title?: ReactNode;
     /** Uncontrolled. */
@@ -21,7 +22,7 @@ export interface CredentialListProps extends Omit<ComponentProps<"div">, "childr
     onOpenChange?: (open: boolean) => void;
     /** Omit to hide the add action. */
     onAdd?: () => void;
-    /** Omit to hide the delete entry. The confirmation belongs to the caller. */
+    /** Omit to hide the delete action. The delete confirmation belongs to the caller. */
     onDelete?: (id: string, item: Credential) => void;
     /** Fires after the value reaches the clipboard — for analytics. */
     onCopy?: (id: string, item: Credential) => void;

package/dist/components/admin/patterns/access/role-permissions.d.ts

@@ -14,6 +14,7 @@ export interface RolePermissionsProps extends Omit<ComponentProps<"div">, "child
     roleName: ReactNode;
     description?: ReactNode;
     memberCount?: number;
+    /** Each group names an area and lists its permissions with a granted flag. */
     groups: PermissionGroup[];
     /** Omit to hide the edit action. */
     onEdit?: () => void;

package/dist/components/admin/patterns/access/sensitive-action.d.ts

@@ -3,7 +3,10 @@ import { ContentBlock, IconBadge } from '../../../base/display/index.js';
 export interface SensitiveActionProps extends Omit<ComponentProps<typeof ContentBlock>, "children" | "icon"> {
     /** The control that performs it — usually a destructive Button. */
     action?: ReactNode;
-    /** What will happen, stated before it does. Rendered as a note, not an error. */
+    /**
+     * What will happen, stated before it does. Rendered `role="note"`, not as an error —
+     * nothing has gone wrong yet.
+     */
     confirmation?: ReactNode;
     icon?: ComponentProps<typeof IconBadge>["icon"];
 }

package/dist/components/admin/patterns/commerce/account.d.ts

@@ -58,8 +58,9 @@ export interface InventoryLevelProps extends Omit<ComponentProps<typeof ContentB
     productName: string;
     /** The chosen option, when the product has any. */
     variant?: string;
+    /** Units on hand. Zero reads as out, which is checked before low. */
     stock: number;
-    /** Below this, the level reads as low rather than healthy. */
+    /** At or below this, the level reads as low rather than healthy. */
     reorderLevel: number;
     /** The gauge's upper bound. */
     maxStock: number;

package/dist/components/admin/patterns/commerce/booking.d.ts

@@ -29,6 +29,10 @@ export interface BookingDetail {
 export interface BookingCardProps extends Omit<ComponentProps<typeof ContentBlock>, "children"> {
     /** A chip, usually — the booking's state. */
     status?: ReactNode;
+    /**
+     * Rendered as a real `<dl>`, so a screen reader pairs each value with its own label. A
+     * `fullWidth` detail spans the row and gets its own ground.
+     */
     details: BookingDetail[];
     actionLabel?: ReactNode;
     onAction?: () => void;

package/dist/components/admin/patterns/commerce/cart.d.ts

@@ -47,9 +47,9 @@ export interface Discount {
     /**
      * What kind of discount it is — "Code", "Automatic", "Volume".
      *
-     * Rendered as a quiet qualifier beside the label, not as a chip. A Badge here was the
-     * first thing tried and it failed contrast at 3.45:1 in the dark theme: a chip is drawn
-     * to sit on a card, and the ledger it lands in has its own tinted ground under it.
+     * Rendered as a quiet qualifier beside the label, not as a chip. A chip is drawn to sit on
+     * a card, and the ledger it would land in has its own tinted ground: a Badge here fails
+     * contrast in the dark theme (3.45:1).
      */
     kind?: ReactNode;
     amount: string;
@@ -61,25 +61,22 @@ export interface DiscountStackProps extends Omit<ComponentProps<typeof ContentBl
     strings?: Partial<DiscountStackStrings>;
 }
 export declare function DiscountStack({ discounts, totalSavings, strings, className, ...props }: DiscountStackProps): import("react").JSX.Element;
-/**
- * CodeEntry — a discount code or a gift card.
- *
- * These were two components, and they were the same component twice: a title, a field, a
- * button, and an applied state. The only real difference is that a gift card holds a
- * BALANCE — money that may outlast this order — where a discount either applies or does
- * not. That is one optional prop, not a second component.
- *
- * `kind` picks the preset: the icon, the default copy, and whether the code is upper-cased
- * on submit. Gift card codes are printed in capitals and nobody types them that way.
- */
+/** Which preset a CodeEntry takes: a discount code or a gift card. */
 export type CodeEntryKind = "discount" | "gift";
 export interface CodeEntryProps extends Omit<ComponentProps<typeof ContentBlock>, "children" | "onSubmit"> {
+    /**
+     * Picks the preset: the icon, the default copy, and whether the code is upper-cased on
+     * submit. Gift card codes are printed in capitals and nobody types them that way.
+     */
     kind?: CodeEntryKind;
     /** The code in force. Present switches the card to its applied state. */
     appliedCode?: string;
     /** What it took off, already formatted. */
     appliedDiscount?: string;
-    /** What is left on the card, already formatted. Gift cards only. */
+    /**
+     * What is left on the card, already formatted — money that may outlast this order, and
+     * the one real difference between the two kinds. Gift cards only.
+     */
     balance?: string;
     /** A rejection message, shown under the field. */
     error?: string;
@@ -88,4 +85,10 @@ export interface CodeEntryProps extends Omit<ComponentProps<typeof ContentBlock>
     onRemove?: () => void;
     strings?: Partial<CodeEntryStrings>;
 }
+/**
+ * A discount code or a gift card. One component for both: a title, a field, a button, and
+ * an applied state. The only real difference is that a gift card holds a BALANCE — money
+ * that may outlast this order — where a discount either applies or does not. That is one
+ * optional prop, not a second component.
+ */
 export declare function CodeEntry({ kind, appliedCode, appliedDiscount, balance, error, loading, onApply, onRemove, strings, className, ...props }: CodeEntryProps): import("react").JSX.Element;

package/dist/components/admin/patterns/commerce/commerce.types.d.ts

@@ -12,8 +12,8 @@ export declare const SHIPMENT_STATUS_TONE: Record<ShipmentStatus, BadgeTone>;
 export type RefundStage = "requested" | "approved" | "processing" | "completed";
 export declare const REFUND_STAGES: readonly RefundStage[];
 /**
- * Card networks and wallets. The brand is named, never painted: trademark colours would
- * need literals `verify composition` forbids. Pass a logo as `icon`.
+ * Card networks and wallets. The brand is named, never painted: the kit draws no trademark
+ * colours. Pass a logo as `icon`.
  */
 export type PaymentBrand = "visa" | "mastercard" | "amex" | "paypal" | "applePay" | "googlePay" | "unknown";
 /** What an address is for. */

package/dist/components/admin/patterns/commerce/inventory-section.d.ts

@@ -24,13 +24,25 @@ export type InventorySectionField = keyof InventorySectionValue;
 /** Which groups to draw. Omit for all of them. */
 export type InventorySectionName = "summary" | "identity" | "tracking" | "location" | "shipping" | "customs" | "tags";
 export interface InventorySectionProps extends Omit<ComponentProps<typeof ContentBlock>, "children" | "onChange"> {
+    /**
+     * The record: sku, barcode, trackQuantity, available, committed, incoming,
+     * lowStockThreshold, inventoryPolicy, binLocation, requiresShipping, weight,
+     * countryOfOrigin, hsCode, tags.
+     */
     value: InventorySectionValue;
-    /** Reports the field, its new value, and what it replaced. Omit for a read-only record. */
+    /**
+     * Reports the field, its new value, and what it replaced — an undo stack that has to
+     * remember that itself is one that gets it wrong once. Omit for a read-only record.
+     */
     onFieldChange?: (change: {
         field: InventorySectionField;
         value: InventorySectionValue[InventorySectionField];
         previousValue: InventorySectionValue[InventorySectionField];
     }) => void;
+    /**
+     * Narrows what is drawn, so one surface serves a simple product, a variant and a location
+     * record without forking. Every section by default.
+     */
     sections?: InventorySectionName[];
     strings?: Partial<InventorySectionStrings>;
 }

package/dist/components/admin/patterns/commerce/loyalty.d.ts

@@ -15,8 +15,12 @@ export interface LoyaltyMovement {
 export interface LoyaltyPointsProps extends Omit<ComponentProps<typeof ContentBlock>, "children"> {
     /** A number gets locale grouping; a string is taken as already formatted. */
     balance: number | string;
-    /** The tier's name. A caller's word, so there is no English default to leak. */
+    /**
+     * The tier's name. There is no default: it is a caller's word, and an English literal
+     * here is one no strings override could reach.
+     */
     tier?: ReactNode;
+    /** The tier badge's tone. */
     tierTone?: BadgeTone;
     movements?: LoyaltyMovement[];
     onRedeem?: () => void;

package/dist/components/admin/patterns/commerce/order-detail.d.ts

@@ -7,9 +7,12 @@ import { FulfillmentStatus, PaymentStatus } from './commerce.types.js';
 import { OrderLine } from './order-line-item.js';
 export interface OrderHeaderProps extends Omit<ComponentProps<"div">, "children"> {
     orderNumber: string;
-    /** Where the goods are. */
+    /** Where the goods are. Independent of payment. */
     fulfillmentStatus?: FulfillmentStatus;
-    /** Where the money is. */
+    /**
+     * Where the money is. Both statuses, one, or neither reads correctly — an order with
+     * nothing to ship has no fulfillment state to state.
+     */
     paymentStatus?: PaymentStatus;
     /** Already formatted. */
     placedAt?: string;
@@ -17,6 +20,7 @@ export interface OrderHeaderProps extends Omit<ComponentProps<"div">, "children"
     source?: string;
     actions?: ActionDefinition[];
     strings?: Partial<OrderHeaderStrings>;
+    /** Overrides the words for either axis without touching the tones, which stay derived. */
     vocabulary?: Partial<OrderStatusVocabulary>;
 }
 export declare function OrderHeader({ orderNumber, fulfillmentStatus, paymentStatus, placedAt, source, actions, strings, vocabulary, className, ...props }: OrderHeaderProps): import("react").JSX.Element;
@@ -26,12 +30,23 @@ export interface FulfillmentGroupProps extends Omit<ComponentProps<"div">, "chil
     location?: ReactNode;
     /** A standing fact about the group — "Shipping not required". */
     notice?: ReactNode;
-    /** The glyph beside the notice. A component, so the group sizes it. */
+    /**
+     * The glyph beside the notice. A component rather than a node, so the group sizes it:
+     * one passed as a child arrives at lucide's own 24px default — three lines tall against
+     * the text it annotates.
+     */
     noticeIcon?: LucideIcon;
+    /** The rows, as data. */
     items?: OrderLine[];
-    /** Overrides `items` entirely, for a caller who needs the rows themselves. */
+    /**
+     * Replaces `items` wholesale, for a caller who needs control of a row — the same seam
+     * Accordion offers.
+     */
     children?: ReactNode;
-    /** The first renders as a button; the rest collapse into an overflow menu. */
+    /**
+     * The first renders as a button; the rest collapse into an overflow menu. One array, so
+     * the menu cannot duplicate the button.
+     */
     actions?: ActionDefinition[];
     strings?: Partial<FulfillmentGroupStrings>;
     vocabulary?: Partial<OrderStatusVocabulary>;
@@ -40,7 +55,7 @@ export declare function FulfillmentGroup({ status, location, notice, noticeIcon:
 export interface SummaryLine {
     id?: string;
     label: ReactNode;
-    /** A middle column — "3 items", "20%". */
+    /** A middle column — "3 items", "20%" — so counts and rates align down a stack. */
     note?: ReactNode;
     /** Already formatted, including its currency. */
     amount: string;
@@ -48,14 +63,21 @@ export interface SummaryLine {
     deduction?: boolean;
 }
 export interface OrderSummaryProps extends Omit<ComponentProps<typeof ContentBlock>, "children"> {
-    /** What was ordered — subtotal, discount, shipping, tax. */
+    /**
+     * What was ordered — subtotal, discount, shipping, tax. Goods and payments render as
+     * separate panels, and a line's `note` is a middle column, so counts and rates align down
+     * a stack.
+     */
     goods: SummaryLine[];
     /** The line the eye should land on. */
     total: SummaryLine;
-    /** What has actually moved — paid, refunded, balance. */
+    /** What has actually moved — paid, refunded, balance. A separate panel from the goods. */
     payments?: SummaryLine[];
     paymentStatus?: PaymentStatus;
-    /** A standing caveat about the balance, not an error. */
+    /**
+     * Standing information about the balance, rendered `role="note"` — a caveat, not an
+     * error: nothing has gone wrong yet.
+     */
     alert?: ReactNode;
     strings?: Partial<OrderSummaryStrings>;
     vocabulary?: Partial<OrderStatusVocabulary>;

package/dist/components/admin/patterns/commerce/order-line-item.d.ts

@@ -18,7 +18,10 @@ export interface OrderLine {
     quantity: number;
     /** Already formatted. Passed, never multiplied. */
     total: string;
-    /** Rendered as label/value rows under the title, so every consumer's extras match. */
+    /**
+     * Per-line custom data, rendered as label/value rows under the title and styled once, so
+     * every consumer's extras match.
+     */
     properties?: OrderLineProperty[];
     /** Whatever `properties` cannot express. */
     children?: ReactNode;

package/dist/components/admin/patterns/commerce/order-transactions.d.ts

@@ -17,6 +17,10 @@ export interface Transaction {
     gateway?: string;
 }
 export interface OrderTransactionsProps extends Omit<ComponentProps<typeof ContentBlock>, "children"> {
+    /**
+     * `kind` drives the sign; a failed attempt stays in the list, because an order showing
+     * only what worked cannot answer why it was never captured.
+     */
     transactions: Transaction[];
     strings?: Partial<TransactionStrings>;
 }

package/dist/components/admin/patterns/commerce/order.d.ts

@@ -12,14 +12,16 @@ export interface OrderEvent {
 }
 export interface OrderStatusCardProps extends Omit<ComponentProps<typeof ContentBlock>, "children"> {
     orderNumber: string;
+    /** Drives the chip's tone. There is no tone override. */
     status: OrderStatus;
     /** Oldest first, so "latest complete" and "next" are found by position. */
     events: OrderEvent[];
     /** Already formatted. */
     eta?: string;
     /**
-     * Opens the full event list on first render. Closed by default: the panel above
-     * already summarises it.
+     * Opens the full event list on first render. Closed by default: the panel above already
+     * says what just happened, what is next and when it lands, and the list repeats two of
+     * the three.
      */
     defaultHistoryOpen?: boolean;
     strings?: Partial<OrderStatusStrings>;
@@ -36,6 +38,10 @@ export interface OrderTimelineEvent {
 export interface OrderTimelineProps extends Omit<ComponentProps<typeof ContentBlock>, "children"> {
     events: OrderTimelineEvent[];
 }
+/**
+ * An order’s events on the shared rail, for a surface that wants the history without
+ * OrderStatusCard’s facts panel around it.
+ */
 export declare function OrderTimeline({ events, className, ...props }: OrderTimelineProps): import("react").JSX.Element;
 export interface PaymentEvent {
     id: string;

package/dist/components/admin/patterns/commerce/seo-listing.d.ts

@@ -3,9 +3,15 @@ import { ContentBlock } from '../../../base/display/index.js';
 import { SeoStrings } from './commerce.strings.js';
 import { SeoScore, SeoScoreInput } from './seo-score.js';
 export interface SeoListingProps extends Omit<ComponentProps<typeof ContentBlock>, "children" | "title"> {
-    /** What the result will read as. */
+    /**
+     * What the result will read as: title, description, permalink, baseUrl, keyword, and
+     * optional limits. Scored on render unless a `score` is supplied.
+     */
     listing: SeoScoreInput;
-    /** A score computed elsewhere (e.g. per keystroke by an editor). Without it, the listing is scored here. */
+    /**
+     * A score computed elsewhere — by an editor scoring as the user types. Without it the
+     * card scores the listing itself.
+     */
     score?: SeoScore;
     onEdit?: () => void;
     strings?: Partial<SeoStrings>;

package/dist/components/admin/patterns/commerce/seo-score.d.ts

@@ -53,4 +53,8 @@ export interface SeoScore {
 export declare function seoPermalinkPath(permalink?: string): string;
 /** The last segment of the path — the part a human reads. */
 export declare function seoPermalinkSlug(permalink?: string): string;
+/**
+ * Plain function, no React. Returns the total, a status, and a per-check breakdown with the
+ * measured lengths.
+ */
 export declare function calculateSeoScore(input: SeoScoreInput): SeoScore;

package/dist/components/admin/patterns/commerce/summary-panel.d.ts

@@ -1,18 +1,33 @@
 import { ComponentProps, ReactNode } from 'react';
 export interface AmountRowProps extends Omit<ComponentProps<"div">, "children"> {
+    /** What the amount is — "Subtotal", "Shipping". */
     label: ReactNode;
     /** Already formatted, including its currency. */
     amount: string;
     /** Marks the row the eye should land on — a total, an amount due. */
     total?: boolean;
-    /** Money coming off the total. Rewrites the sign rather than trusting the caller's, and tints the figure. */
+    /**
+     * Money coming off the total. Rewrites the sign to U+2212 whatever the caller passed,
+     * and tints the figure.
+     */
     deduction?: boolean;
     /** A rate, a qualifier — sits quietly beside the label. */
     note?: ReactNode;
 }
+/**
+ * The ledger row every money surface is built from, inside a `SummaryPanel`. Not
+ * InlineStat: this one knows about money — deductions and totals — and InlineStat displays
+ * any value.
+ */
 export declare function AmountRow({ label, amount, total, deduction, note, className, ...props }: AmountRowProps): import("react").JSX.Element;
 export interface SummaryPanelProps extends ComponentProps<"div"> {
     /** A quieter ground than the card it sits in, so the rows read as a sub-total block. */
     children: ReactNode;
 }
+/**
+ * The money ledger — the shape almost every commerce surface is made of: a tinted block of
+ * label/amount rows, a rule, and one row that matters more than the rest. A cart, a tax
+ * breakdown, an invoice and a subscription all draw it, and each rebuilding it inline is how
+ * one of them ends up emphasising its total differently from the others.
+ */
 export declare function SummaryPanel({ children, className, ...props }: SummaryPanelProps): import("react").JSX.Element;

package/dist/components/admin/patterns/commerce/vendor-profile.d.ts

@@ -26,10 +26,19 @@ export interface VendorProfileProps extends Omit<ComponentProps<typeof ContentBl
     verified?: boolean;
     /** Already formatted, including its currency. */
     earnings?: string;
+    /**
+     * Operating facts, for the overview. Supplying both this and `stats` gives tabs;
+     * supplying either alone renders that view bare.
+     */
     metrics?: VendorMetric[];
+    /**
+     * Performance tiles, for the stats view. Supplying both this and `metrics` gives tabs;
+     * supplying either alone renders that view bare.
+     */
     stats?: VendorStat[];
-    /** Controlled. */
+    /** Controlled. Uncontrolled, the profile opens on whichever view has data. */
     view?: VendorView;
+    /** Reports the view a reader switches to. */
     onViewChange?: (view: VendorView) => void;
     onMessage?: () => void;
     onHire?: () => void;

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

@@ -1,14 +1,22 @@
 import { Accordion as AccordionPrimitive } from '@base-ui/react/accordion';
 import { AccordionItemData, AccordionMedia, AccordionSurface } from './accordion.types.js';
-export interface AccordionProps extends AccordionPrimitive.Root.Props<string> {
-    /** Outer chrome. Resolves through the provider when omitted. */
+export interface AccordionProps extends AccordionPrimitive.Root.Props<string>, Pick<AccordionPrimitive.Root.Props<string>, "multiple" | "defaultValue" | "value"> {
+    /**
+     * The group's chrome: one bordered shell with dividers, a panel per section, or none.
+     * Resolves through the provider when omitted, so `UIProvider` defaults can change it.
+     * @default "bordered"
+     */
     surface?: AccordionSurface;
     /**
      * Bounded sections, each rendered as the canonical icon/title/badge/description row.
      * Ignored when `children` are supplied.
      */
     items?: AccordionItemData[];
-    /** How leading media is framed. Only meaningful alongside `items`. */
+    /**
+     * How leading icons are framed. Only meaningful alongside `items`; the column is dropped
+     * entirely when no item has one. `UIProvider` defaults can change it.
+     * @default "inline"
+     */
     media?: AccordionMedia;
 }
 export type AccordionItemProps = AccordionPrimitive.Item.Props;

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

@@ -1,53 +1,95 @@
 import { ComponentProps } from 'react';
 import { Button } from '../buttons/index.js';
 import { DropdownMenuTrigger } from '../dropdown-menu/index.js';
+import { LinkRenderer } from '../../../lib/navigation.js';
 import { ActionMenuStrings } from './action-menu.strings.js';
-import { ActionDefinition, ActionIcon, ActionLinkRenderer, ActionMenuLabelVisibility } from './action-menu.types.js';
+import { ActionDefinition, ActionIcon, ActionMenuLabelVisibility } from './action-menu.types.js';
 export interface ActionMenuProps {
-    /** Commands to offer. Destructive entries move last unless `preserveOrder` is set. */
+    /**
+     * Commands to offer; `visible: false` omits one entirely. Destructive entries move last
+     * unless `preserveOrder` is set.
+     */
     actions: readonly ActionDefinition[];
     /** Trigger text. Omit for an icon-only trigger — `strings.trigger` names it then. */
     label?: string;
     /** Trigger glyph. Defaults to the vertical ellipsis. */
     icon?: ActionIcon;
-    /** Overrides this menu's own copy. */
+    /**
+     * Overrides this menu's own copy: `trigger` names an icon-only trigger, which without a
+     * visible label has no other name.
+     */
     strings?: Partial<ActionMenuStrings>;
+    /** Props for the default trigger button. Ignored when `renderTrigger` replaces it. */
     buttonProps?: Omit<ComponentProps<typeof Button>, "children">;
+    /**
+     * How the surface lines up with the trigger along the side it opens on.
+     * `UIProvider` defaults can change it.
+     * @default "end"
+     */
     align?: "start" | "center" | "end";
+    /** Where the surface opens relative to the trigger. */
     side?: "top" | "right" | "bottom" | "left";
+    /** Class for the menu surface itself: the escape hatch for styling it. */
     contentClassName?: string;
     /**
-     * Fixed surface width, any CSS length, or `"trigger"` to match the trigger. Left
-     * unset the menu sizes to its widest row.
+     * Fixed surface width: any CSS length, or `"trigger"` to match the trigger, for a menu that
+     * reads as the field's own list. Left unset the menu sizes to its widest row.
      */
     width?: string | number | "trigger";
+    /** A floor under the content-sized width. */
     minWidth?: string | number;
-    /** Ceiling for the content-sized default: a reading measure, so one long label doesn't widen every row. */
+    /**
+     * Ceiling for the content-sized default: a reading measure rather than the viewport, so one
+     * long label doesn't widen every row. Unset, the surface also stops at the space available.
+     * @default "20rem"
+     */
     maxWidth?: string | number;
+    /**
+     * Closes the menu when an entry is chosen. Turn it off for a menu of checkbox rows, where
+     * the reader is setting several things at once; an entry's own `closeOnSelect` overrides
+     * it. `UIProvider` defaults can change it.
+     * @default true
+     */
     closeOnSelect?: boolean;
+    /**
+     * Where the trigger's `label` shows. `responsive` hides it below `sm`, leaving the glyph,
+     * for a toolbar that has to survive a phone; `hidden` hides it at every width.
+     * `UIProvider` defaults can change it.
+     * @default "visible"
+     */
     labelVisibility?: ActionMenuLabelVisibility;
-    /** Keeps the incoming order instead of moving destructive entries last. */
+    /** Keeps the declared order instead of moving destructive entries last. */
     preserveOrder?: boolean;
-    /** Routes `href` actions through the app's router, keeping this framework-agnostic. */
-    renderLink?: ActionLinkRenderer;
     /**
-     * Replaces the trigger entirely — an account block, a sidebar row, a tab. For different
-     * words on a plain button, use `label` and `icon`.
+     * Routes `href` actions through the app's router, keeping this framework-agnostic. Return
+     * an element, not a function that spreads props: the menu merges its own props onto the
+     * element, so the row keeps its menu item role.
+     */
+    renderLink?: LinkRenderer;
+    /**
+     * Replaces the trigger entirely, for a menu hanging off something that is not a button:
+     * an account block, a sidebar row, a tab. For different words on a plain button, use
+     * `label` and `icon`.
      */
     renderTrigger?: ComponentProps<typeof DropdownMenuTrigger>["render"];
 }
 export interface ActionButtonsProps {
-    /** The same definitions, side by side rather than collapsed into a menu. */
+    /**
+     * The same definitions `ActionMenu` takes, side by side rather than collapsed into a menu:
+     * that is the point of the shape. Each entry's `tone` and `buttonStyle` carry through to
+     * its button.
+     */
     actions: readonly ActionDefinition[];
     /**
      * How many render as buttons before the rest collapse into an overflow menu built from
      * the same array. Unset, every definition is a button.
      */
     max?: number;
-    /** Overrides this toolbar's own copy — the overflow trigger's name. */
+    /** Overrides this toolbar's own copy: `strings.overflow` names the overflow menu's trigger. */
     strings?: Partial<ActionMenuStrings>;
     className?: string;
-    renderLink?: ActionLinkRenderer;
+    /** Routes `href` actions through the app's router, as `ActionMenu`'s `renderLink` does. */
+    renderLink?: LinkRenderer;
 }
 /**
  * Overflow commands for a page, a card, a table or a row — one component so grouping,

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

@@ -1,24 +1,24 @@
-import { ComponentType, ReactElement, ReactNode } from 'react';
+import { ComponentType, ReactNode } from 'react';
 import { ButtonStyle, ButtonTone } from '../buttons/index.js';
 /** A Lucide icon, any component taking a className, or an already-rendered node. */
 export type ActionIcon = ComponentType<{
     className?: string;
 }> | ReactNode;
 export type ActionMenuLabelVisibility = "visible" | "responsive" | "hidden";
-export interface ActionLinkRenderProps {
-    href: string;
-    children?: ReactNode;
-    target?: string;
-    rel?: string;
-    external?: boolean;
-    disabled?: boolean;
-}
+/** One command, in the shape `ActionMenu`, `ActionButtons` and a card's `actions` all take. */
 export interface ActionDefinition {
     /** Stable key. Falls back to a string `label`, then the index. */
     id?: string;
+    /**
+     * What the entry says. The only part of the row that gives way: a long label truncates
+     * instead of pushing the shortcut or trailing content off.
+     */
     label: ReactNode;
     icon?: ActionIcon;
-    /** `checkbox` renders a toggle driven by `checked` / `onCheckedChange`. */
+    /**
+     * `checkbox` renders a toggle driven by `checked` / `onCheckedChange`.
+     * @default "item"
+     */
     type?: "item" | "checkbox";
     /**
      * Renders the entry as a link. A native `<a href>` by default, which is a full page
@@ -46,7 +46,10 @@ export interface ActionDefinition {
     tone?: ButtonTone;
     /** Treatment when the action renders as a button. `link` is a ghost that underlines. */
     buttonStyle?: ButtonStyle | "link";
-    /** `false` omits the action entirely. */
+    /**
+     * `false` omits the action entirely.
+     * @default true
+     */
     visible?: boolean;
     disabled?: boolean;
     /** Overrides the menu's `closeOnSelect` for this entry. */
@@ -55,7 +58,6 @@ export interface ActionDefinition {
     /** Replaces the rendered entry — a framework `<Link>`, for instance. */
     render?: ReactNode;
 }
-export type ActionLinkRenderer = (props: ActionLinkRenderProps) => ReactElement;
 /** Where an action renders when a set is split between buttons and a menu. */
 export type ActionPlacement = "auto" | "inline" | "menu";
 /** A flag, or a question asked of the subject the action is bound to. */
@@ -66,13 +68,23 @@ export type ActionPredicate<TContext> = boolean | ((context: TContext) => boolea
  * activity actions extend it, and `resolveContextActions` resolves them.
  */
 export interface ContextAction<TContext> extends Omit<ActionDefinition, "onClick" | "visible" | "disabled"> {
+    /** Receives the subject the set was resolved against. */
     onClick?: (context: TContext) => void;
-    /** `false`, or a predicate returning false, omits the action for that subject. */
+    /**
+     * `false`, or a predicate returning false, omits the action for that subject.
+     * @default true
+     */
     visible?: ActionPredicate<TContext>;
+    /**
+     * Worked out per subject, so a locked row shows the action greyed rather than missing.
+     * @default false
+     */
     disabled?: ActionPredicate<TContext>;
     /**
-     * Forces this entry to one side when the set is split between buttons and a menu: `menu`
-     * keeps it out of the button row, `inline` pins it there, `auto` lets the renderer decide.
+     * Forces this entry to one side when the set is split between buttons and a menu:
+     * `inline` stays a button whatever `max` is, `menu` always overflows, and `auto` fills
+     * the buttons in order up to `max`.
+     * @default "auto"
      */
     placement?: ActionPlacement;
 }

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

@@ -1,5 +1,6 @@
 export { ActionButtons, ActionMenu } from './action-menu.js';
 export type { ActionButtonsProps, ActionMenuProps } from './action-menu.js';
-export type { ActionDefinition, ActionIcon, ActionLinkRenderer, ActionLinkRenderProps, ActionMenuLabelVisibility, ActionPlacement, ActionPredicate, ContextAction, ContextActionSource, ResolvedAction, } from './action-menu.types.js';
+export type { ActionDefinition, ActionIcon, ActionMenuLabelVisibility, ActionPlacement, ActionPredicate, ContextAction, ContextActionSource, ResolvedAction, } from './action-menu.types.js';
+export type { LinkRenderer, LinkRenderProps } from '../../../lib/navigation.js';
 export { resolveContextActions, splitActions, type ResolveContextActionsOptions, } from './context-actions.js';
 export { defaultActionMenuStrings, type ActionMenuStrings } from './action-menu.strings.js';