themelia-ui 2.0.1 → 3.0.0

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';

package/dist/components/base/alert-dialog/alert-dialog.d.ts

@@ -6,6 +6,12 @@ import { OverlayContentProps } from '../overlay/index.js';
  * answers (`Action`, `Cancel`) and a media slot.
  */
 import * as React from "react";
+/**
+ * A centred surface that demands an answer. It fixes `placement` to centre and announces as
+ * `alertdialog`; both dismissal routes are fixed off and the corner close is off by
+ * default, so the backdrop and Escape never decide for the reader. `modality`, `surface`
+ * and `initialFocusRef` are OverlayContent's props.
+ */
 export declare function AlertDialogContent({ className, ...props }: Omit<OverlayContentProps, "placement" | "dismissal">): React.JSX.Element;
 /** Media slot above the title — an illustration or icon carrying the alert's weight. */
 export declare function AlertDialogMedia({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
@@ -15,5 +21,9 @@ type AnswerProps = React.ComponentProps<"button"> & {
 };
 /** The affirmative answer. Closes on click unless the handler prevents it. */
 export declare function AlertDialogAction({ className, ...props }: AnswerProps): React.JSX.Element;
+/**
+ * The answer that backs out. Both answers close the dialog; `AlertDialogAction` is the one
+ * that commits. With no dismissal and no corner close, they are the only ways out.
+ */
 export declare function AlertDialogCancel({ className, ...props }: AnswerProps): React.JSX.Element;
 export {};

package/dist/components/base/aspect-ratio/aspect-ratio.d.ts

@@ -4,8 +4,9 @@ export interface AspectRatioProps extends ComponentProps<"div"> {
     /** Width divided by height — `16 / 9`, `1`, `4 / 3` — as a number, never parsed. */
     ratio?: ResponsiveValue<number>;
     /**
-     * How a media child fills the box: `cover` crops to fill (the usual frame); `contain` fits
-     * inside, for artwork whose edges matter (a logo, a diagram, a screenshot).
+     * How a media child fills the box: `cover` crops to fill it (the usual frame); `contain`
+     * fits the whole image inside and leaves the rest of the box empty, for artwork whose edges
+     * matter (a logo, a diagram, a screenshot).
      */
     fit?: "cover" | "contain";
 }

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

@@ -3,12 +3,25 @@ import * as React from "react";
 /** An avatar keeps a size prop: it has no content to scale with. */
 export type AvatarSize = "default" | "sm" | "lg";
 export type AvatarProps = AvatarPrimitive.Root.Props & {
+    /** Disc size. One of the kit's few size props: an avatar has no content to scale with. */
     size?: AvatarSize;
 };
+/** A person or an entity as a disc: an image, with initials behind it for when there is none. */
 declare function Avatar({ className, size, ...props }: AvatarProps): React.JSX.Element;
-declare function AvatarImage({ className, ...props }: AvatarPrimitive.Image.Props): React.JSX.Element;
+/**
+ * The picture. An empty `alt` is correct beside a visible name; the name already announces
+ * the person.
+ */
+declare function AvatarImage({ className, ...props }: AvatarPrimitive.Image.Props & Pick<AvatarPrimitive.Image.Props, "src" | "alt">): React.JSX.Element;
+/** Shown when there is no image. Initials, not a placeholder glyph. */
 declare function AvatarFallback({ className, ...props }: AvatarPrimitive.Fallback.Props): React.JSX.Element;
+/** A small status mark on the disc's corner. */
 declare function AvatarBadge({ className, ...props }: React.ComponentProps<"span">): React.JSX.Element;
+/** A row of overlapping avatars. */
 declare function AvatarGroup({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+/**
+ * The "+3" at the end of an `AvatarGroup`. A count rather than another avatar, so a group of
+ * twelve does not need twelve images to say so.
+ */
 declare function AvatarGroupCount({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
 export { Avatar, AvatarImage, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarBadge };

package/dist/components/base/avatar/stacked-avatars.d.ts

@@ -9,14 +9,19 @@ export interface StackedAvatarUser {
     initials?: string;
 }
 export interface StackedAvatarsProps extends Omit<ComponentProps<"div">, "children"> {
+    /** The people in the row, in order. */
     users: StackedAvatarUser[];
     /** Overrides this group's own copy — its accessible name, and the overflow chip. */
     strings?: Partial<StackedAvatarsStrings>;
-    /** How many faces to show before collapsing the rest into a count. */
+    /** How many faces to show. Beyond it, the remainder becomes a count. */
     max?: number;
-    /** Hides the "+N" tile, for a group where the total does not matter. */
+    /** Shows the "+N" tile. Turn it off for a group where the total does not matter. */
     showOverflow?: boolean;
-    /** Formats the overflow tile — "+12", "+12 more". Defaults to `strings.overflow`. */
+    /**
+     * How the remainder reads on the overflow tile — "+12", "+12 more". Defaults to
+     * `strings.overflow`, which reads "+N".
+     */
     overflowFormatter?: (overflow: number) => ReactNode;
 }
+/** People as overlapping avatars, capped with a count of the rest. */
 export declare function StackedAvatars({ users, strings, max, showOverflow, overflowFormatter, className, ...props }: StackedAvatarsProps): import("react").JSX.Element;

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

@@ -9,17 +9,21 @@ export type BadgeTone = "neutral" | "primary" | "secondary" | "success" | "info"
 /** Structural presentation. The tone supplies the hue; this decides how it is applied. */
 export type BadgeVariant = "soft" | "solid" | "outline";
 export interface BadgeProps extends React.ComponentProps<"span">, VariantProps<typeof badgeVariants> {
-    /**
-     * The element this becomes — an anchor, a router link, a label (docs/adr/0005).
-     * `children` stays the content.
-     */
-    render?: React.ReactElement;
+    /** Semantic colour: what the badge means. `variant` decides how much of it is applied. */
+    tone?: BadgeTone;
+    /** How much of the tone is applied. Structural, not semantic. */
+    variant?: BadgeVariant;
     /** A leading status dot in the badge's own tone. */
     dot?: boolean;
-    /** Draws the dot hollow, for a state that hasn't happened yet ("queued", not "failed"). */
+    /** Draws the dot hollow, for a state that has not happened yet: "queued", not "failed". */
     pending?: boolean;
     /** Animates the dot, for a state that is actively changing. */
     pulse?: boolean;
+    /**
+     * The element the badge becomes — an anchor or a router link, for a badge that links.
+     * The dot and `children` go inside it.
+     */
+    render?: React.ReactElement;
 }
 declare function Badge({ className, tone, variant, render, dot, pending, pulse, children, ...props }: BadgeProps): React.JSX.Element;
 export { Badge };

package/dist/components/base/batch-action-bar/batch-action-bar.d.ts

@@ -7,10 +7,11 @@ export interface BatchActionBarProps {
     selectedCount: number;
     /** Optional denominator for the summary. Omit when the total is unknown or unbounded. */
     totalCount?: number;
-    /** Omit to render no clear control — a selection the user cannot drop needs a reason. */
+    /** Drops the selection. Omit to render no clear control — a selection the user cannot drop needs a reason. */
     onClear?: () => void;
     /** `floating` docks to the bottom centre of the viewport; `inline` sits in flow. */
     placement?: BatchActionBarPlacement;
+    /** Overrides this bar's own copy: `summary(selected, total)`, `clear`, and the region's accessible `label`. */
     strings?: StringsProp<BatchActionBarStrings>;
     /** The bulk actions. Buttons, a menu, whatever the surface needs. */
     children?: ReactNode;

package/dist/components/base/buttons/button-group.d.ts

@@ -1,15 +1,24 @@
 /** ButtonGroup — adjacent buttons read as one control: one hairline seam, squared inner corners. */
 import * as React from "react";
 export interface ButtonGroupProps extends React.ComponentProps<"div"> {
+    /** The direction the buttons run in. */
     orientation?: "horizontal" | "vertical";
 }
+/** Adjacent buttons that read as one control: one hairline seam, squared inner corners. */
 export declare function ButtonGroup({ orientation, className, ...props }: ButtonGroupProps): React.JSX.Element;
 export interface ButtonGroupTextProps extends React.ComponentProps<"span"> {
 }
-/** A non-interactive segment — a unit, a prefix, a count. A span, so it adds no tab stop. */
+/**
+ * A label that sits in the run without becoming pressable — a unit, a prefix, a count. A
+ * span, so it adds no tab stop.
+ */
 export declare function ButtonGroupText({ className, ...props }: ButtonGroupTextProps): React.JSX.Element;
 export interface ButtonGroupSeparatorProps extends React.ComponentProps<"div"> {
+    /** The orientation of the group it sits in; the seam runs across it. */
     orientation?: "horizontal" | "vertical";
 }
-/** A rule between segments, where the collapsed border alone is not enough. */
+/**
+ * The seam between welded buttons, where the collapsed border alone is not enough. A plain
+ * `Separator` here would draw a full-height rule against the group's own border.
+ */
 export declare function ButtonGroupSeparator({ orientation, className, ...props }: ButtonGroupSeparatorProps): React.JSX.Element;

package/dist/components/base/buttons/button.d.ts

@@ -6,12 +6,20 @@ import { ButtonStyle, ButtonTone } from './button.types.js';
  */
 import * as React from "react";
 export interface ButtonProps extends Omit<React.ComponentProps<"button">, "children"> {
-    /** Semantic colour intent. */
+    /**
+     * Semantic colour intent. Resolves through the provider when omitted, so `UIProvider`
+     * defaults can change it.
+     * @default "primary"
+     */
     tone?: ButtonTone;
-    /** Fill treatment. */
+    /**
+     * Fill treatment, independent of `tone`. `UIProvider` defaults can change it.
+     * @default "solid"
+     */
     buttonStyle?: ButtonStyle;
     /** Square button sized to its height. The label becomes the accessible name. */
     iconOnly?: boolean;
+    /** Stretches the button to its container's width. */
     fullWidth?: boolean;
     /**
      * Shows a spinner and blocks interaction. The label keeps its space so the button does
@@ -19,8 +27,10 @@ export interface ButtonProps extends Omit<React.ComponentProps<"button">, "child
      */
     loading?: boolean;
     /**
-     * The element this button becomes — an anchor, a router link, a label (docs/adr/0005).
-     * `children` stay the content and keep the button's label wrapper.
+     * The element this button becomes — an anchor, a router link, a label. `children` stay
+     * the content and keep the button's label wrapper, so a link still sizes like a button.
+     * `render` is how every kit component changes its element, the contract Base UI's parts
+     * already take.
      *
      *   <Button render={<a href="/settings" />}>Settings</Button>
      */
@@ -28,7 +38,7 @@ export interface ButtonProps extends Omit<React.ComponentProps<"button">, "child
     children?: React.ReactNode;
 }
 /**
- * No `size` prop by design: geometry follows the scale factors, so a denser region is a
- * scope (styles/FACTORS.md).
+ * The kit's action primitive. No `size` prop by design: geometry follows the scale factors,
+ * so a denser region is a scope (styles/FACTORS.md).
  */
 export declare function Button({ tone, buttonStyle, iconOnly, fullWidth, loading, render, className, disabled, children, onClick, ...props }: ButtonProps): React.JSX.Element;

package/dist/components/base/buttons/loader-button.d.ts

@@ -7,15 +7,23 @@ import { ButtonLoadingStrings } from './button.strings.js';
  */
 import * as React from "react";
 export interface LoaderButtonProps extends Omit<ButtonProps, "onClick"> {
-    /** Controlled pending state. Omit to let the button manage it from `onClick`. */
+    /**
+     * Controlled pending state. Omit it and the button holds the state itself, from the
+     * promise `onClick` returns.
+     */
     loading?: boolean;
     /**
-     * Accepted for source-kit compatibility; inert. Choosing `LoaderButton` is already that
-     * decision. Swallowed rather than spread, so ported call sites don't leak it to the DOM.
+     * Accepted so call sites that pass it keep compiling; inert. Choosing `LoaderButton` is
+     * already that decision. Swallowed rather than spread, so it never reaches the DOM.
      */
     handlesLoading?: boolean;
     /** May return a promise; the button then stays pending until it settles. */
     onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void | Promise<unknown>;
+    /** Overrides the button's own copy: what it announces while it works. */
     strings?: StringsProp<ButtonLoadingStrings>;
 }
+/**
+ * A `Button` that can run its handler and hold the pending state itself. It also announces
+ * the wait, which `Button`'s own `loading` prop does not.
+ */
 export declare const LoaderButton: React.ForwardRefExoticComponent<Omit<LoaderButtonProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/base/buttons/text-button.d.ts

@@ -1,8 +1,21 @@
 import { ButtonProps } from './button.js';
+import { ButtonTone } from './button.types.js';
 /**
  * TextButton — a button styled as a link, for actions on this page (announced as a
  * button, activated by Space). Anything that navigates should be a real anchor.
  */
 import * as React from "react";
-export type TextButtonProps = Omit<ButtonProps, "buttonStyle" | "iconOnly" | "fullWidth">;
+export type TextButtonProps = Omit<ButtonProps, "tone" | "buttonStyle" | "iconOnly" | "fullWidth"> & {
+    /**
+     * Semantic colour intent. A text button always sets it, so the provider's button defaults
+     * do not reach it.
+     */
+    tone?: ButtonTone;
+};
+/**
+ * A button that reads as a link, for actions on this page: announced as a button and
+ * activated by Space. Anything that navigates should be a real anchor. It carries its own
+ * `data-slot`, so nothing downstream mistakes it for a ghost button that should line up
+ * with controls — it is inline prose.
+ */
 export declare const TextButton: React.ForwardRefExoticComponent<Omit<TextButtonProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/base/buttons/tooltip-button.d.ts

@@ -7,11 +7,17 @@ import { ButtonProps } from './button.js';
 import * as React from "react";
 export interface TooltipButtonProps extends ButtonProps {
     /**
-     * Shown on hover and focus. It is the accessible name only when the button has no text of
-     * its own; beside a visible label it is the description.
+     * Shown on hover and focus. It is also the accessible name when the button has no text
+     * of its own, and that pairing is the point: an icon button with a tooltip and no
+     * `aria-label` is unnamed to everyone not using a mouse. Beside a visible label it is the
+     * description.
      */
     tooltip: string;
     /** Where the tooltip opens. */
     side?: React.ComponentProps<typeof TooltipContent>["side"];
 }
+/**
+ * A button with a tooltip. For an icon-only button the tooltip text is also the accessible
+ * name, so it is not unnamed to anyone not using a mouse.
+ */
 export declare const TooltipButton: React.ForwardRefExoticComponent<Omit<TooltipButtonProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/base/cards/card-actions.d.ts

@@ -1,22 +1,39 @@
 import { ComponentProps } from 'react';
-import { ActionDefinition, ActionLinkRenderer } from '../action-menu/index.js';
+import { ActionDefinition } from '../action-menu/index.js';
+import { LinkRenderer } from '../../../lib/navigation.js';
 export interface CardActionStripProps extends Omit<ComponentProps<"div">, "children"> {
+    /**
+     * The commands, as the overflow menu takes them. The first is the primary action; the rest
+     * follow in outline unless an entry sets its own `buttonStyle`.
+     */
     actions: ActionDefinition[];
-    /** A rule above the strip, for a card whose content runs right into it. */
+    /** A rule above the strip, ruling it off from content that runs right into it. */
     separator?: boolean;
+    /** Where the buttons sit along the strip. */
     align?: "start" | "end" | "between";
-    /** Stretches the first action, for a narrow card where two buttons will not fit. */
+    /**
+     * Stretches the first action, for a card whose action is the point, or a narrow card where
+     * two buttons will not fit.
+     */
     fullWidthPrimary?: boolean;
     /** Routes `href` actions through the app's router. */
-    renderLink?: ActionLinkRenderer;
+    renderLink?: LinkRenderer;
 }
+/**
+ * A card's commands as buttons. One array decides which action is primary and how the rest
+ * follow, so a page of cards cannot disagree about it.
+ */
 export declare function CardActionStrip({ actions, separator, align, fullWidthPrimary, renderLink, className, ...props }: CardActionStripProps): import("react").JSX.Element | null;
-export interface CardPrimaryActionProps extends ComponentProps<"a"> {
-    /** Names the target. The card's own title is not enough — many cards share one. */
+export interface CardPrimaryActionProps extends ComponentProps<"a">, Pick<ComponentProps<"a">, "href"> {
+    /**
+     * The link's accessible name. The visible title is not necessarily the destination, and
+     * many cards share one.
+     */
     label: string;
 }
 /**
- * Makes a whole card one target with a covering link (wrapping the card would nest its
- * controls inside an anchor). Interactive children are lifted above it in CSS.
+ * Stretches an anchor across the whole card, so the card is one tab stop rather than a grid
+ * of them (wrapping the card would nest its controls inside an anchor). Interactive children
+ * are lifted above it in CSS.
  */
 export declare function CardPrimaryAction({ label, className, ...props }: CardPrimaryActionProps): import("react").JSX.Element;

package/dist/components/base/cards/card-skeleton.d.ts

@@ -4,11 +4,19 @@ export interface CardSkeletonProps extends Omit<ComponentProps<"div">, "title">
     /**
      * Match the real card's surface. Unset, it takes the card's default (the provider's
      * `defaults.card.surface`, framed out of the box).
+     * @default "framed"
      */
     surface?: CardSurface;
     /** Reserves the header's height. */
     showHeader?: boolean;
+    /** Lines of content to reserve. Match the real card's. */
     lines?: number;
+    /** What the placeholder announces while it waits. Unset, the skeleton's own loading copy. */
     label?: string;
 }
+/**
+ * A placeholder that reserves the real card's box, so the page doesn't reflow when content
+ * lands. Matching the surface and the line count is the whole job: a placeholder of the wrong
+ * shape moves the page twice.
+ */
 export declare function CardSkeleton({ surface, showHeader, lines, label, className, ...props }: CardSkeletonProps): import("react").JSX.Element;