themelia-ui 2.0.0 → 3.0.0

package/dist/components/base/repeaters/localized-fields.d.ts

@@ -8,6 +8,7 @@ export interface LocaleDescriptor {
 /** `{ en: "Name", nl: "Naam" }`. Missing keys are simply untranslated. */
 export type LocalizedValue = Record<string, string>;
 export interface LocalizedStringFieldProps {
+    /** Which locales the switcher offers, in order. The first is the default. */
     locales: (string | LocaleDescriptor)[];
     value?: LocalizedValue;
     onValueChange?: (value: LocalizedValue) => void;
@@ -25,6 +26,11 @@ export interface LocalizedStringFieldProps {
     "aria-describedby"?: string;
     "aria-invalid"?: boolean | "true" | "false";
 }
+/**
+ * One value per locale behind a single field with a locale switcher, so a translated field
+ * costs one row instead of one row per language. The active locale is view state, not part
+ * of the value.
+ */
 export declare function LocalizedStringField({ locales, value, onValueChange, multiline, placeholder, disabled, invalid, requiredLocales, className, "aria-label": ariaLabel, "aria-labelledby": labelledBy, "aria-describedby": describedBy, "aria-invalid": ariaInvalid, }: LocalizedStringFieldProps): import("react").JSX.Element;
 export interface LocalizedObjectFieldDefinition {
     /** Key in each locale's object. */
@@ -45,5 +51,9 @@ export interface LocalizedObjectFieldProps {
     invalid?: boolean;
     className?: string;
 }
-/** Several fields per locale — a title and a body, say — behind one switcher. */
+/**
+ * Several fields per locale — a title and a body, say — behind one switcher, with the
+ * active locale switchable in place. A translation UI built out of plain repeaters loses
+ * which language a row belongs to the moment rows reorder.
+ */
 export declare function LocalizedObjectField({ locales, fields, value, onValueChange, disabled, invalid, className, }: LocalizedObjectFieldProps): import("react").JSX.Element;

package/dist/components/base/repeaters/localized-string-repeater.d.ts

@@ -9,6 +9,7 @@ export interface LocalizedStringRepeaterProps {
     strings?: Partial<RepeaterStrings>;
     emptyState?: React.ReactNode;
     maxItems?: number;
+    /** Adds the drag handle and arrow-key reordering. */
     sortable?: boolean;
     multiline?: boolean;
     requiredLocales?: string[];
@@ -17,4 +18,9 @@ export interface LocalizedStringRepeaterProps {
     className?: string;
     "aria-label"?: string;
 }
+/**
+ * An ordered list of localized strings, each row a `LocalizedStringField`: one value per
+ * language, with the active locale switchable in place. A translation UI built out of plain
+ * repeaters loses which language a row belongs to the moment rows reorder.
+ */
 export declare function LocalizedStringRepeater({ locales, value, onValueChange, placeholder, strings, emptyState, maxItems, sortable, multiline, requiredLocales, disabled, invalid, className, "aria-label": ariaLabel, }: LocalizedStringRepeaterProps): import("react").JSX.Element;

package/dist/components/base/repeaters/object-repeater.d.ts

@@ -24,19 +24,30 @@ export interface ObjectRepeaterFieldContext {
 }
 export type ObjectRow = Record<string, string>;
 export interface ObjectRepeaterProps {
+    /** The rows, one object per row, keyed by field name. */
     value: ObjectRow[];
     onValueChange: (value: ObjectRow[]) => void;
+    /** The fields every row carries, described once as data rather than assembled per row. */
     fields: ObjectFieldDef[];
     /** Prefixes the generated field paths (`items.2.email`) to match a form library. Naming only. */
     name?: string;
     emptyState?: ReactNode;
     maxItems?: number;
+    /** Adds the drag handle and arrow-key reordering. */
     sortable?: boolean;
     disabled?: boolean;
     invalid?: boolean;
-    /** Replaces one field's control, keeping the row and array behaviour. */
+    /**
+     * Replaces one field's control, keeping the row and array behaviour — how a caller
+     * connects individual fields to a form library.
+     */
     renderField?: (field: ObjectFieldDef, context: ObjectRepeaterFieldContext) => ReactNode;
     strings?: Partial<ObjectRepeaterStrings>;
     className?: string;
 }
+/**
+ * A repeating row of several fields, described once as data rather than assembled per row
+ * — contacts, line items, addresses. It reads and writes the array it is given and imports
+ * no form library, so any can drive it.
+ */
 export declare function ObjectRepeater({ value, onValueChange, fields, name, emptyState, maxItems, sortable, disabled, invalid, renderField, strings, className, }: ObjectRepeaterProps): import("react").JSX.Element;

package/dist/components/base/repeaters/repeater.d.ts

@@ -6,24 +6,47 @@ export interface RepeaterRowContext {
     dragging: boolean;
 }
 export interface RepeaterProps<T> {
+    /** The rows. The repeater renders what it is given and nothing else. */
     items: T[];
-    /** Stable key for a row. An index is a poor key while rows reorder. */
+    /**
+     * Stable identity per row. An index alone would re-key every row after a reorder and
+     * lose focus.
+     */
     getKey: (item: T, index: number) => string;
+    /** Renders one row. `context` carries the row's `index` and whether it is `dragging`. */
     children: (item: T, context: RepeaterRowContext) => ReactNode;
+    /** Supplying it renders the add button. */
     onAdd?: () => void;
+    /** Supplying it renders each row's remove button. */
     onRemove?: (index: number) => void;
-    /** Enables reordering. Without it, no handle is rendered. */
+    /**
+     * Supplying it enables reordering and renders the drag handle; without it, no handle is
+     * rendered. The handle is the drag source, not the row.
+     */
     onMove?: (from: number, to: number) => void;
     /** `card` wraps each row in a bordered surface, for multi-field rows. */
     rowVariant?: "inline" | "card";
-    /** Overrides this list's own copy — the add control and each row's remove. */
+    /**
+     * Overrides this list's own copy — the add control and each row's remove. `remove` is a
+     * function of the row index: every remove button in a list saying the same thing is a
+     * column of controls a screen reader cannot tell apart.
+     */
     strings?: Partial<RepeaterStrings>;
+    /** Shown in place of the rows when `items` is empty. Replaces `strings.emptyState`. */
     emptyState?: ReactNode;
-    /** Hides the add button, for a list with a fixed set of rows. */
+    /**
+     * Hides the add button while keeping the rows — for a list at its cap, a fixed set of
+     * rows, or one whose entries come from elsewhere.
+     */
     showAdd?: boolean;
     /** Caps the list. The add button disables at the limit. */
     maxItems?: number;
     disabled?: boolean;
     className?: string;
 }
+/**
+ * The chrome every list-style field shares: rows with an optional drag handle and remove
+ * control, an empty state, and an add button. It never owns the array — you pass `items`
+ * and the handlers, which keeps it usable with a form library or with plain state.
+ */
 export declare function Repeater<T>({ items, getKey, children, onAdd, onRemove, onMove, rowVariant, strings, emptyState, showAdd, maxItems, disabled, className, }: RepeaterProps<T>): import("react").JSX.Element;

package/dist/components/base/repeaters/string-repeater.d.ts

@@ -7,10 +7,12 @@ export interface StringRepeaterProps {
     strings?: Partial<RepeaterStrings>;
     emptyState?: React.ReactNode;
     maxItems?: number;
+    /** Adds the drag handle and arrow-key reordering. */
     sortable?: boolean;
     disabled?: boolean;
     invalid?: boolean;
     className?: string;
     "aria-label"?: string;
 }
+/** An ordered list of plain strings — alternate names, allowed domains, recipients. */
 export declare function StringRepeater({ value, onValueChange, placeholder, strings, emptyState, maxItems, sortable, disabled, invalid, className, "aria-label": ariaLabel, }: StringRepeaterProps): import("react").JSX.Element;

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

@@ -3,14 +3,27 @@
  * `role="separator"`. Persist sizes with `onLayoutChanged` and restore via `defaultLayout`.
  */
 import * as ResizablePrimitive from "react-resizable-panels";
-export interface ResizablePanelGroupProps extends ResizablePrimitive.GroupProps {
+export interface ResizablePanelGroupProps extends ResizablePrimitive.GroupProps, Pick<ResizablePrimitive.GroupProps, "orientation"> {
 }
+/**
+ * The split. `orientation` is its axis. Own the persistence: keep the layout in your state
+ * with `onLayoutChanged` and hand it back through `defaultLayout`, so a reader who widened a
+ * panel finds it wide next time.
+ */
 export declare function ResizablePanelGroup({ className, ...props }: ResizablePanelGroupProps): import("react").JSX.Element;
 export interface ResizablePanelProps extends ResizablePrimitive.PanelProps {
 }
+/** A panel inside a `ResizablePanelGroup`. */
 export declare function ResizablePanel({ className, ...props }: ResizablePanelProps): import("react").JSX.Element;
 export interface ResizableHandleProps extends ResizablePrimitive.SeparatorProps {
-    /** Draws a grip on the line, for a split with no other cue that it moves. Defaults to false. */
+    /**
+     * Draws a grip on the line, for a split with no other cue that it moves. The hit area is
+     * wider than the 1px rule either way.
+     */
     withHandle?: boolean;
 }
+/**
+ * The grip between two panels: a real `role="separator"`. It is focusable and takes arrow
+ * keys, so the split is adjustable without a pointer.
+ */
 export declare function ResizableHandle({ withHandle, className, ...props }: ResizableHandleProps): import("react").JSX.Element;

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

@@ -8,7 +8,20 @@ import { SheetSide } from './sheet.types.js';
 import * as React from "react";
 export type { SheetSide };
 export interface SheetContentProps extends Omit<OverlayContentProps, "placement">, Omit<React.ComponentProps<"dialog">, "children" | "className" | "title"> {
-    /** The edge it enters from. */
+    /**
+     * The edge it enters from, as a logical side. `UIProvider` defaults can change it.
+     * @default "inline-end"
+     */
     side?: SheetSide;
 }
+/**
+ * OverlayContent at an edge. `side` is OverlayContent's `placement` minus centre — logical,
+ * so it follows the writing mode — and the sheet adds a default shape: `side="inline-end"`,
+ * `size="md"`, `length="full"` and `inset={false}`. `UIProvider`'s `defaults.sheet` takes
+ * the same four, for a product that decides the shape once.
+ *
+ * `modality`, `surface`, `dismissal`, `initialFocusRef` and `showCloseButton` pass through
+ * unchanged, with the Overlay defaults. A sheet is where `non-modal` earns its place: an
+ * inspector you keep working beside.
+ */
 export declare function SheetContent({ side, size, length, inset, className, ...props }: SheetContentProps): React.JSX.Element;

package/dist/components/base/sidebar/sidebar-context.d.ts

@@ -4,16 +4,30 @@ export interface SidebarProviderProps extends Omit<React.ComponentProps<"div">,
     strings?: Partial<SidebarStrings>;
     /** Initial expanded state when uncontrolled. */
     defaultOpen?: boolean;
+    /**
+     * Controlled expanded state. It is held here, above both the trigger and the rail, so the
+     * two cannot disagree.
+     */
     open?: boolean;
+    /** Called with the next expanded state. */
     onOpenChange?: (open: boolean) => void;
-    /** Remembers the expanded state across reloads, in `localStorage`. Defaults to true. */
+    /**
+     * Remembers the expanded state across reloads, in `localStorage`. It is read during the
+     * first render, so the shell does not flash open and then snap shut.
+     */
     persist?: boolean;
-    /** Enables the ⌘B / Ctrl-B toggle shortcut. Defaults to true. */
+    /** Enables the ⌘B / Ctrl-B toggle shortcut. */
     keyboardShortcut?: boolean;
     /**
      * Bounds the shell to this element instead of the viewport — for a shell that does not
-     * own the screen (inside a tab, a preview, a nested editor).
+     * own the screen (inside a tab, a preview, a nested editor). The panel is
+     * `position: fixed` by default, which is correct for a real shell and the reason a demo
+     * of one has to opt out.
      */
     contained?: boolean;
 }
+/**
+ * Holds the panel's state above both the trigger and the rail, so the two cannot disagree,
+ * and shares it with every part inside.
+ */
 export declare function SidebarProvider({ defaultOpen, open: openProp, onOpenChange, persist, keyboardShortcut, contained, strings, className, style, children, ref, ...props }: SidebarProviderProps): import("react").JSX.Element;

package/dist/components/base/sidebar/sidebar-store.d.ts

@@ -11,9 +11,11 @@ export interface SidebarContextValue {
     strings: SidebarStrings;
 }
 export declare const SidebarContext: import('react').Context<SidebarContextValue | null>;
+/** The panel's state from anywhere inside `SidebarProvider`. Throws outside one. */
 export declare function useSidebar(): SidebarContextValue;
 /**
- * The context, or `null` outside a provider — for shell parts that render with or without
- * a sidebar (a header above a plain page).
+ * The panel's state, or `null` outside a provider — for the parts a shell renders whether
+ * or not it has a sidebar. A header above a plain page still wants its breadcrumbs, and
+ * throwing there takes the page down over a toggle that has nothing to toggle.
  */
 export declare function useOptionalSidebar(): SidebarContextValue | null;

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

@@ -15,8 +15,19 @@ export type SidebarVariant = "sidebar" | "floating" | "inset";
 /** `icon` collapses to a glyph rail; `offcanvas` slides away; `none` never collapses. */
 export type SidebarCollapsible = "offcanvas" | "icon" | "none";
 export interface SidebarProps extends ComponentProps<"div"> {
+    /** Which edge the panel occupies, for the rail and the mobile sheet alike. */
     side?: SidebarSide;
+    /**
+     * `sidebar` sits against the shell's edge with a border. `floating` and `inset` detach it,
+     * so the panel reads as a card inside the page rather than as the page's own edge;
+     * `inset` also lifts the page into a card of its own.
+     */
     variant?: SidebarVariant;
+    /**
+     * How it gets out of the way: slid away entirely (`offcanvas`), reduced to a rail of
+     * glyphs (`icon`), or pinned open, never collapsing (`none`). On a narrow viewport a
+     * collapsible panel becomes a sheet.
+     */
     collapsible?: SidebarCollapsible;
     /** Class for the visible panel surface, separate from the positioning container. */
     surfaceClassName?: string;
@@ -26,26 +37,52 @@ export interface SidebarProps extends ComponentProps<"div"> {
     /** Overrides this sidebar's own copy, including the two above. */
     strings?: Partial<SidebarStrings>;
 }
+/** The panel: a header, scrolling content and a footer, against one edge of the shell. */
 export declare function Sidebar({ side, variant, collapsible, className, surfaceClassName, mobileTitle, mobileDescription, strings, children, ...props }: SidebarProps): React.JSX.Element;
-/** The toggle. Pair it with the rail, which does the same job from the panel's edge. */
-export declare function SidebarTrigger({ className, onClick, ...props }: ComponentProps<typeof Button>): React.JSX.Element;
-/** The strip on the panel's edge. Not a tab stop: it duplicates the trigger. */
+/**
+ * The button that toggles the panel. It reads the provider, so it works from anywhere
+ * inside it; pair it with the rail, which does the same job from the panel's edge.
+ */
+export declare function SidebarTrigger({ className, onClick, tone, buttonStyle, iconOnly, ...props }: ComponentProps<typeof Button>): React.JSX.Element;
+/**
+ * The strip along the panel's edge, which toggles it too. It reads the provider, so it works
+ * from anywhere inside it. Not a tab stop: it duplicates the trigger.
+ */
 export declare function SidebarRail({ className, ...props }: ComponentProps<"button">): React.JSX.Element;
 /**
- * The page beside the panel. Renders `<main>`; a shell embedded in a host page that already
- * has one should pass `render={<div />}`.
+ * The page beside the panel. Renders `<main>`, so it is the document's main landmark rather
+ * than another div; a shell embedded in a host page that already has one should pass
+ * `render={<div />}`.
  */
 export declare function SidebarInset({ className, render, ...props }: useRender.ComponentProps<"main">): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+/**
+ * The panel's top region. It holds its edge while the content scrolls, so a long navigation
+ * never scrolls its own search box away.
+ */
 export declare function SidebarHeader({ className, ...props }: ComponentProps<"div">): React.JSX.Element;
+/** The panel's bottom region. It holds its edge while the content scrolls. */
 export declare function SidebarFooter({ className, ...props }: ComponentProps<"div">): React.JSX.Element;
+/** The scrolling region between the header and the footer. */
 export declare function SidebarContent({ className, ...props }: ComponentProps<"div">): React.JSX.Element;
 export declare function SidebarSeparator({ className, ...props }: ComponentProps<typeof Separator>): React.JSX.Element;
 export declare function SidebarInput({ className, ...props }: ComponentProps<typeof Input>): React.JSX.Element;
+/**
+ * A titled section of the panel, with an optional control on the label's line — an add, a
+ * filter.
+ */
 export declare function SidebarGroup({ className, ...props }: ComponentProps<"div">): React.JSX.Element;
+/** The section's title. */
 export declare function SidebarGroupLabel({ className, ...props }: ComponentProps<"div">): React.JSX.Element;
+/** A control on the section title's line — an add, a filter. */
 export declare function SidebarGroupAction({ className, ...props }: ComponentProps<"button">): React.JSX.Element;
+/** The section's body, under its label. */
 export declare function SidebarGroupContent({ className, ...props }: ComponentProps<"div">): React.JSX.Element;
+/**
+ * The rows: a real `<ul>`, so the navigation announces as a list and its length is
+ * spoken.
+ */
 export declare function SidebarMenu({ className, ...props }: ComponentProps<"ul">): React.JSX.Element;
+/** One row: a real `<li>`, holding the row's button and anything beside it. */
 export declare function SidebarMenuItem({ className, ...props }: ComponentProps<"li">): React.JSX.Element;
 /**
  * Row shape, not density: `lg` is an account or workspace switcher (avatar over two lines),
@@ -53,53 +90,83 @@ export declare function SidebarMenuItem({ className, ...props }: ComponentProps<
  */
 export type SidebarMenuButtonSize = "sm" | "md" | "lg";
 export interface SidebarMenuButtonProps extends Omit<ComponentProps<"button">, "size"> {
+    /**
+     * The row's height, as a shape rather than a density: `lg` is the workspace switcher, `sm`
+     * a secondary row. A size prop here, because a navigation row is not on the control
+     * ladder that density scales.
+     */
     size?: SidebarMenuButtonSize;
     /** Marks the row as the current page. */
     active?: boolean;
     /** `outline` gives the row its own frame — for a switcher that must read as a control. */
     variant?: "default" | "outline";
     /**
-     * The element this row becomes instead of a `button` — usually a router link
-     * (docs/adr/0005); `children` stays the row's content.
+     * The element this row becomes instead of a `button` — usually a router link, so the row
+     * navigates the app's own way. `children` stays the row's content.
      */
     render?: React.ReactElement;
     /**
-     * Dismisses the mobile sheet when the row is activated. Defaults to true; turn it off for
-     * a row that opens something else (a switcher, a submenu toggle).
+     * Dismisses the mobile sheet when the row is activated. Turn it off for a row that opens
+     * something else (a switcher, a submenu toggle).
      */
     closeOnSelectMobile?: boolean;
     /**
-     * Shown beside the row while the sidebar is collapsed to its icon rail, usually the row's
-     * label. Ignored while expanded and on phones.
+     * The row's name, shown beside it while the sidebar is collapsed to its icon rail, where
+     * the label is clipped away. Ignored while expanded and on phones.
      */
     tooltip?: React.ReactNode;
 }
+/** The row's control: a button, or through `render` a router link. */
 export declare function SidebarMenuButton({ size, active, variant, render, closeOnSelectMobile, tooltip, className, children, onClick, ...props }: SidebarMenuButtonProps): React.JSX.Element;
 export interface SidebarMenuActionProps extends ComponentProps<"button"> {
-    /** Reveals the action on hover or keyboard focus rather than showing it always. */
+    /**
+     * Reveals the action on hover or keyboard focus rather than showing it always. Focus
+     * counts through `focus-within`, so the action stays reachable without a pointer.
+     */
     showOnHover?: boolean;
 }
+/**
+ * A secondary control on a row, positioned so it neither displaces the label nor steals the
+ * row's press target.
+ */
 export declare function SidebarMenuAction({ showOnHover, className, ...props }: SidebarMenuActionProps): React.JSX.Element;
 export interface SidebarMenuBadgeProps extends ComponentProps<"div"> {
     /** Renders in normal flow instead of over the row — for a button laying out its own parts. */
     inline?: boolean;
 }
+/**
+ * A count on a row, positioned so it neither displaces the label nor steals the row's press
+ * target.
+ */
 export declare function SidebarMenuBadge({ inline, className, ...props }: SidebarMenuBadgeProps): React.JSX.Element;
 export interface SidebarMenuSkeletonProps extends ComponentProps<"div"> {
+    /** Reserves the row's icon as well as its label. */
     showIcon?: boolean;
 }
+/**
+ * Reserves a row's exact box while the navigation loads, so the panel does not reflow when
+ * it lands.
+ */
 export declare function SidebarMenuSkeleton({ showIcon, className, style, ...props }: SidebarMenuSkeletonProps): React.JSX.Element;
+/** A nested level under a row, indented against the parent's rail. */
 export declare function SidebarMenuSub({ className, ...props }: ComponentProps<"ul">): React.JSX.Element;
+/** One row of a nested level. */
 export declare function SidebarMenuSubItem({ className, ...props }: ComponentProps<"li">): React.JSX.Element;
 export interface SidebarMenuSubButtonProps extends ComponentProps<"a"> {
+    /** The nested row's height. */
     size?: "sm" | "md";
+    /** Marks the row as the current page. */
     active?: boolean;
     /** Dismisses the mobile sheet when the row is activated. See SidebarMenuButton. */
     closeOnSelectMobile?: boolean;
     /**
-     * The element this row becomes instead of an `a` or `button` — usually a router link
-     * (docs/adr/0005); `children` stays the row's content.
+     * The element this row becomes instead of an `a` or `button` — usually a router link, so
+     * the row navigates the app's own way. `children` stays the row's content.
      */
     render?: React.ReactElement;
 }
+/**
+ * A nested row's control: a link when it has an `href`, otherwise a button, or through
+ * `render` a router link.
+ */
 export declare function SidebarMenuSubButton({ size, active, closeOnSelectMobile, render, className, onClick, children, ...props }: SidebarMenuSubButtonProps): React.JSX.Element;

package/dist/components/base/skeleton/composed-skeletons.d.ts

@@ -5,38 +5,52 @@ export interface ContentSkeletonProps extends ComponentProps<"div"> {
     lines?: number;
     /** A heading above the lines. */
     showTitle?: boolean;
-    /** Announced in place of the shapes. */
+    /** Announced while loading, in place of the shapes. */
     label?: string;
     /** Overrides the default announcement. `label` still wins for one instance. */
     strings?: Partial<SkeletonStrings>;
 }
+/** A paragraph of prose, optionally under a title bar. */
 export declare function ContentSkeleton({ lines, showTitle, label, strings, className, ...props }: ContentSkeletonProps): import("react").JSX.Element;
 export interface PageSkeletonProps extends ComponentProps<"div"> {
     /** The page header: a title, its description, and the actions at the end of the row. */
     showHeader?: boolean;
     /** Content panels below the header. */
     blocks?: number;
+    /** Announced while loading, in place of the shapes. */
     label?: string;
     /** Overrides the default announcement. `label` still wins for one instance. */
     strings?: Partial<SkeletonStrings>;
 }
+/** PageHeader's row — title, description, actions — over card-shaped panels. */
 export declare function PageSkeleton({ showHeader, blocks, label, strings, className, ...props }: PageSkeletonProps): import("react").JSX.Element;
 export interface TwoColumnPageSkeletonProps extends ComponentProps<"div"> {
+    /** Announced while loading, in place of the shapes. */
     label?: string;
     /** Overrides the default announcement. `label` still wins for one instance. */
     strings?: Partial<SkeletonStrings>;
 }
-/** A detail page: a title over the record's panel, beside its owner and facts. */
+/** A detail page: a title over the record's panel, and beside it its owner and facts. */
 export declare function TwoColumnPageSkeleton({ label, strings, className, ...props }: TwoColumnPageSkeletonProps): import("react").JSX.Element;
 export interface TableSkeletonProps extends ComponentProps<"div"> {
+    /** Body rows, at the real row height. */
     rows?: number;
     /** Match the real table, or the placeholder reflows when the data lands. */
     columns?: number;
+    /** A head row above the body, at the real head height. */
     showHeader?: boolean;
-    /** Draws the table's own edge, as DataView does. Turn off inside a card that has one. */
+    /**
+     * Draws the table's own edge and corner, as DataView does. Off when it stands in for a
+     * table inside a card that already draws one.
+     */
     framed?: boolean;
+    /** Announced while loading, in place of the shapes. */
     label?: string;
     /** Overrides the default announcement. `label` still wins for one instance. */
     strings?: Partial<SkeletonStrings>;
 }
+/**
+ * A table's geometry before the data lands: the real row and head heights, a wide first
+ * column, a right-aligned last one.
+ */
 export declare function TableSkeleton({ rows, columns, showHeader, framed, label, strings, className, ...props }: TableSkeletonProps): import("react").JSX.Element;

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

@@ -1,3 +1,4 @@
 import * as React from "react";
+/** The primitive box. Size it with `style` or a class; the composed skeletons are built from it. */
 declare function Skeleton({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
 export { Skeleton };

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

@@ -4,10 +4,11 @@ type SlotProps = {
     children: React.ReactElement;
 } & AnyProps;
 /**
- * Minimal Slot: merges its props onto the single child element and composes refs. The
- * child's props win, except that classes join, both handlers run (the child's first) and
- * styles merge (the child's over the slot's). Returns null unless given exactly one element.
- * Internal mechanism behind `render` (docs/adr/0005), not a consumer API.
+ * Merges its props onto its single child element and composes refs. The child's props win,
+ * except that classes join, both handlers run (the child's first) and styles merge (the
+ * child's over the slot's). Renders nothing unless given exactly one element. The kit's own
+ * components take `render`, which is built on this merge; `Slot` is for composing components
+ * of your own.
  */
 export declare const Slot: React.ForwardRefExoticComponent<Omit<SlotProps, "ref"> & React.RefAttributes<unknown>>;
 export {};

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

@@ -5,9 +5,20 @@ import { ComponentScale, SemanticTone } from '../../../lib/component-vocabulary.
  */
 import * as React from "react";
 export interface SpinnerProps extends Omit<React.ComponentProps<"span">, "children"> {
+    /**
+     * The ring's size: `sm`, `md` or `lg`. The one place a size prop survives: a spinner has
+     * no content to scale with.
+     */
     size?: ComponentScale;
+    /**
+     * Borrows the button tone contract, so a spinner inside or beside an action matches it
+     * rather than sitting on it in the primary hue.
+     */
     tone?: SemanticTone;
-    /** Visible label beside the ring. Also becomes the announced status. */
+    /**
+     * Visible label beside the ring, and the announced status. Without one the spinner is
+     * decorative and hidden from assistive technology.
+     */
     label?: React.ReactNode;
 }
 export declare function Spinner({ size, tone, label, className, ...props }: SpinnerProps): React.JSX.Element;

package/dist/components/base/structure/bleed.d.ts

@@ -5,9 +5,16 @@ import { BleedAxis, ResponsiveValue, StructureGap } from './structure.types.js';
  */
 import * as React from "react";
 export interface BleedProps extends React.ComponentProps<"div"> {
-    /** How far to escape, on the spacing scale; match the padding being cancelled. */
+    /**
+     * How far to escape, on the spacing scale. Match it to the padding being cancelled — a
+     * surface at `--space-md` bleeds `md` — so the two move together under a density change.
+     * @default "none"
+     */
     amount?: ResponsiveValue<StructureGap>;
-    /** Which way (`both` covers every direction). Defaults to `inline`. */
+    /**
+     * Which way to escape; `both` covers every direction. Sideways is the common case: an
+     * image bleeds across and keeps its vertical rhythm.
+     */
     axis?: BleedAxis;
 }
 export declare const Bleed: React.ForwardRefExoticComponent<Omit<BleedProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/components/base/structure/split.d.ts

@@ -7,18 +7,27 @@ import { ResponsiveValue, SplitSide, StructureGap, StructureWidth } from './stru
 import * as React from "react";
 export interface SplitProps extends React.ComponentProps<"div"> {
     /**
-     * Which visual column is the fixed one. Defaults to `end`. DOM order never changes: the
-     * first child is the main content, the second the side.
+     * Which visual column is the fixed one. The DOM order never changes with it: the first
+     * child is the main content and the second the side on both settings, so a reader
+     * tabbing through reaches the content first either way.
      */
     side?: SplitSide;
     /**
-     * The fixed column's width — a step or any CSS length. A maximum, so it never squeezes
-     * the fluid column to nothing.
+     * The fixed column's width — a step or any CSS length. A maximum rather than an exact
+     * size, so a narrow viewport shrinks the rail instead of squeezing the content beside it
+     * to nothing.
+     * @default "18rem"
      */
     sideWidth?: ResponsiveValue<StructureWidth | (string & {})>;
-    /** Space between the two columns. */
+    /**
+     * Space between the two columns.
+     * @default "md"
+     */
     gap?: ResponsiveValue<StructureGap>;
-    /** Below this breakpoint the columns stack. Defaults to `md`; `never` keeps them side by side. */
+    /**
+     * Below this breakpoint the two columns become one. `never` keeps them side by side at
+     * every width.
+     */
     collapseBelow?: "sm" | "md" | "lg" | "xl" | "never";
 }
 export declare const Split: React.ForwardRefExoticComponent<Omit<SplitProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/components/base/structure/stack.d.ts

@@ -5,15 +5,36 @@ import { ResponsiveValue, StructureAlign, StructureDirection, StructureGap, Stru
  */
 import * as React from "react";
 export interface StackProps extends Omit<React.ComponentProps<"div">, "dir"> {
-    /** Main axis. Defaults to vertical. */
+    /**
+     * Main axis.
+     * @default "vertical"
+     */
     direction?: ResponsiveValue<StructureDirection>;
-    /** Space between children, on the semantic spacing scale. */
+    /**
+     * Space between children, on the semantic spacing scale.
+     * @default "md"
+     */
     gap?: ResponsiveValue<StructureGap>;
+    /**
+     * Cross-axis alignment.
+     * @default "stretch"
+     */
     align?: ResponsiveValue<StructureAlign>;
+    /**
+     * Main-axis distribution.
+     * @default "start"
+     */
     justify?: ResponsiveValue<StructureJustify>;
-    /** Allows children to flow onto more than one line. */
+    /**
+     * Allows children to flow onto more than one line.
+     * @default false
+     */
     wrap?: ResponsiveValue<boolean>;
-    /** Caps the box's width — a content step, or any CSS length (e.g. a form's `26rem`). */
+    /**
+     * Caps the box's width — a content step (`sm` to `2xl`, `full`, `none`) or any CSS
+     * length, such as a form's `26rem`. A field measure is a control decision rather than a
+     * content one, which is why a raw length is allowed beside the scale.
+     */
     maxWidth?: ResponsiveValue<StructureWidth | (string & {})>;
 }
 export declare const Stack: React.ForwardRefExoticComponent<Omit<StackProps, "ref"> & React.RefAttributes<HTMLDivElement>>;