themelia-ui 2.0.0 → 3.0.0

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

@@ -2,25 +2,43 @@ import { ComponentPropsWithoutRef, ReactNode } from 'react';
 import { ButtonProps } from '../buttons/index.js';
 import { CopyableStrings } from './copyable.strings.js';
 export interface CopyableProps extends Omit<ComponentPropsWithoutRef<"span">, "children" | "onCopy" | "onError"> {
-    /** Value written to the clipboard. */
+    /** What lands on the clipboard. */
     value: string;
-    /** Display content, when it differs from the copied value. */
+    /**
+     * Shown instead of the raw value, when it differs from what is copied. A rich node is
+     * rendered as-is.
+     */
     displayValue?: ReactNode;
-    /** Monospace the display content. For ids, keys, and hashes. */
+    /**
+     * Monospaced, tabular figures for the display content — for an id, a key or a hash, where
+     * one character matters.
+     */
     mono?: boolean;
-    /** Truncates the display content at the width the caller allots. */
+    /** Truncates the display content at the width the caller allots, keeping the button in view. */
     truncate?: boolean;
     /**
-     * Sizes the trigger to the text rather than a control's height, for values inside a list
-     * row. The target keeps its minimum hit area.
+     * Sizes the trigger to the text rather than to a control's height. A control's height is
+     * right beside a field and wrong inside a list row where the value is a description under
+     * a title: there the button is twice the height of the line it belongs to, and the row's
+     * rhythm bends around it. Every behaviour is unchanged, and the target keeps its minimum
+     * hit area; what it gives up is the pointer target a standalone control is entitled to.
      */
     compact?: boolean;
-    /** Overrides this control's own copy. */
+    /**
+     * Overrides this control's own copy. The name changes between `copy` and `copied`, because
+     * the confirmation is the name for a screen reader.
+     */
     strings?: Partial<CopyableStrings>;
-    /** Suppresses the toasts. The copied state on the control is the confirmation then. */
+    /** Suppresses both toasts. The copied state on the control is the confirmation then. */
     silent?: boolean;
+    /** Passed to the copy control, for a tone or a treatment that suits the surface. */
     buttonProps?: Omit<ButtonProps, "children" | "onClick" | "type">;
+    /** Called with the value once it is on the clipboard. */
     onCopy?: (value: string) => void;
+    /**
+     * Called when the clipboard refuses — an insecure origin, a denied permission. A copy that
+     * fails silently is worse than one that never offered.
+     */
     onError?: (error: unknown) => void;
 }
 export declare const Copyable: import('react').ForwardRefExoticComponent<CopyableProps & import('react').RefAttributes<HTMLSpanElement>>;

package/dist/components/base/copyable/use-copy-to-clipboard.d.ts

@@ -1,8 +1,4 @@
-/**
- * Copy a value, confirm it, and reset — the shared implementation for every copy surface.
- * The window is keyed off a counter, not a boolean: re-setting `true` is a no-op, so a
- * second copy would inherit the first one's remaining window.
- */
+/** What `useCopyToClipboard` takes. */
 export interface UseCopyToClipboardOptions {
     /** How long the confirmation stands, in ms. Defaults to 2000, Copyable's window. */
     confirmMs?: number;
@@ -20,4 +16,10 @@ export interface UseCopyToClipboardResult {
     /** Resolves `true` when the value was written, `false` when it was not. */
     copy: (value: string) => Promise<boolean>;
 }
+/**
+ * Copy a value, confirm it, and reset — the hook `Copyable` is built on, and the shared
+ * implementation for every copy surface. `copy(value)` resolves `true` or `false` rather than
+ * rejecting. Takes `confirmMs`, `onCopy`, `onError`, and `write` — a destination for where
+ * `navigator.clipboard` is absent.
+ */
 export declare function useCopyToClipboard({ confirmMs, write, onCopy, onError, }?: UseCopyToClipboardOptions): UseCopyToClipboardResult;

package/dist/components/base/date-pickers/calendar.d.ts

@@ -1,18 +1,35 @@
 import { CalendarStrings } from './date-pickers.strings.js';
 import { CalendarConstraints, DateRangeValue, DateSelectionMode } from './calendar.types.js';
 export interface CalendarProps extends CalendarConstraints {
-    /** Overrides this calendar's own copy — the three caption controls. */
+    /**
+     * Overrides this calendar's own copy — the caption controls, which are icon-only and have
+     * no other name. `DatePicker` passes its own strings straight through, so one override
+     * names both.
+     */
     strings?: Partial<CalendarStrings>;
+    /** Selection behaviour, as on `DatePicker`: one date, a range, or several dates. */
     mode?: DateSelectionMode;
     /** The selection, in the shape the mode uses. */
     value?: Date | Date[] | DateRangeValue;
+    /** Called with the new selection, in the shape the mode uses. */
     onValueChange?: (value: Date | Date[] | DateRangeValue | undefined) => void;
-    /** The month shown. Uncontrolled unless supplied. */
+    /**
+     * The month shown, for a calendar whose position is driven from outside. Uncontrolled
+     * unless supplied.
+     */
     month?: Date;
+    /** Called with the first day of the month the calendar moves to. */
     onMonthChange?: (month: Date) => void;
-    /** How many months to show side by side. Two is the usual range picker. */
+    /**
+     * How many months to show side by side. Two is the usual range picker; each grid keeps its
+     * own caption, so the second month is not anonymous.
+     */
     numberOfMonths?: number;
-    /** 0 is Sunday. Falls back to the provider's formatting config. */
+    /**
+     * Which day begins the week; `0` is Sunday. Falls back to the provider's dates setting
+     * rather than a hard-coded Monday, so `UIProvider` defaults can change it.
+     * @default 1
+     */
     weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
     className?: string;
 }

package/dist/components/base/date-pickers/date-picker-bands.d.ts

@@ -6,6 +6,10 @@ export interface DatePickerHeaderProps extends Omit<ComponentProps<"div">, "titl
     /** A control at the trailing edge — a mode switch, a clear. */
     action?: ReactNode;
 }
+/**
+ * The region above the calendar inside the popup, for the picker's `header` slot — a title,
+ * a mode switch. Exported so a caller can supply their own without rebuilding the calendar.
+ */
 export declare function DatePickerHeader({ title, description, action, className, children, ...props }: DatePickerHeaderProps): import("react").JSX.Element | null;
 export interface DatePickerFooterProps extends ComponentProps<"div"> {
     /** A summary of what is chosen — "3 – 7 March, 5 days". */
@@ -13,4 +17,9 @@ export interface DatePickerFooterProps extends ComponentProps<"div"> {
     /** Controls at the trailing edge. */
     actions?: ReactNode;
 }
+/**
+ * The region below the calendar inside the popup, for the picker's `footer` slot: the row
+ * that holds a summary and controls such as Clear and Apply. Exported so a caller can supply
+ * their own without rebuilding the calendar.
+ */
 export declare function DatePickerFooter({ summary, actions, className, children, ...props }: DatePickerFooterProps): import("react").JSX.Element | null;

package/dist/components/base/date-pickers/date-picker.d.ts

@@ -9,28 +9,51 @@ export interface DatePickerProps extends CalendarConstraints {
      * so the field's label must reach it.
      */
     id?: string;
+    /** What a click selects: one date, a range, or several dates. */
     mode?: DateSelectionMode;
+    /** The chosen value. Its shape follows `mode`: a `Date`, a `{ from, to }`, or an array. */
     value?: Date | Date[] | DateRangeValue;
+    /** Called with the new value, in the shape `mode` gives it. */
     onValueChange?: (value: Date | Date[] | DateRangeValue | undefined) => void;
-    /** How the chosen value is written in the trigger. */
+    /** How the chosen value is written in the trigger: a date-fns pattern. The popup is unaffected. */
     displayFormat?: string;
     placeholder?: string;
     disabled?: boolean;
+    /** The error surface. The message stays on the `FormField`. */
     invalid?: boolean;
-    /** Adds a clear control to the trigger once something is chosen. */
+    /**
+     * Adds a clear control to the trigger once something is chosen: a real button beside the
+     * calendar glyph, named through `strings` — not an icon with a click handler.
+     */
     clearable?: boolean;
-    /** Overrides this picker's own copy — the clear control and the calendar's captions. */
+    /**
+     * Overrides this picker's own copy — the clear control and the calendar's captions. The
+     * same object reaches the calendar inside the popup, so one override names the month
+     * controls too.
+     */
     strings?: Partial<DatePickerStrings>;
-    /** Shortcuts down the side — "Last 30 days", "This month". */
+    /**
+     * Shortcuts down the side — "Last 30 days", "This month": the rail beside a range
+     * calendar. `createRangePresets({ strings, weekStartsOn })` builds the built-in set in your
+     * language and week.
+     */
     presets?: DatePreset[];
+    /**
+     * How many months are shown side by side: two for a range, one otherwise. The header
+     * becomes a range when more than one.
+     */
     numberOfMonths?: number;
-    /** Closes the popup as soon as a complete value is chosen. */
+    /**
+     * Closes the popup as soon as a complete value is chosen. On by default for a single date
+     * and off for a range, because a range is not chosen until both ends are.
+     */
     closeOnSelect?: boolean;
     /** A band above the calendar — a title, a mode switch. Use `DatePickerHeader`. */
     header?: ReactNode;
     /** A band below it — a summary, Clear and Apply. Use `DatePickerFooter`. */
     footer?: ReactNode;
     className?: string;
+    /** Styles the popup surface. `className` stays on the trigger. */
     contentClassName?: string;
     "aria-label"?: string;
     "aria-labelledby"?: string;

package/dist/components/base/date-pickers/month-year-picker.d.ts

@@ -15,4 +15,8 @@ export interface MonthYearPickerProps extends Omit<ComponentProps<"div">, "onCha
     /** Overrides this picker's own copy — the two year controls. */
     strings?: Partial<CalendarStrings>;
 }
+/**
+ * Month and year without a day grid, for a period rather than a date — a billing month, a
+ * report window, an expiry. A day grid would imply a precision the value lacks.
+ */
 export declare function MonthYearPicker({ value, onValueChange, minYear, maxYear, disabledMonths, strings, className, ...props }: MonthYearPickerProps): import("react").JSX.Element;

package/dist/components/base/date-pickers/presets-pickers.d.ts

@@ -5,15 +5,22 @@ export interface SingleDatePickerProps extends Base {
     value?: Date;
     onValueChange?: (value: Date | undefined) => void;
 }
+/**
+ * `DatePicker` with `mode="single"` fixed, so the value type is fixed with it: a `Date`. The
+ * generic picker has to widen its callback to cover every mode, which pushes a cast into
+ * every call site.
+ */
 export declare const SingleDatePicker: import('react').ForwardRefExoticComponent<Omit<SingleDatePickerProps, "ref"> & import('react').RefAttributes<HTMLButtonElement>>;
 export interface MultipleDatePickerProps extends Base {
     value?: Date[];
     onValueChange?: (value: Date[]) => void;
 }
+/** `DatePicker` with `mode="multiple"` fixed, so the value is always an array of dates. */
 export declare const MultipleDatePicker: import('react').ForwardRefExoticComponent<Omit<MultipleDatePickerProps, "ref"> & import('react').RefAttributes<HTMLButtonElement>>;
 export interface RangeDatePickerProps extends Base {
     value?: DateRangeValue;
     onValueChange?: (value: DateRangeValue) => void;
 }
+/** `DatePicker` with `mode="range"` fixed, so the value is always a `{ from, to }`. */
 export declare const RangeDatePicker: import('react').ForwardRefExoticComponent<Omit<RangeDatePickerProps, "ref"> & import('react').RefAttributes<HTMLButtonElement>>;
 export {};

package/dist/components/base/date-pickers/time-picker.d.ts

@@ -1,4 +1,5 @@
 import { TimePickerStrings } from './time-picker.strings.js';
+/** A time of day: `{ hours, minutes }`, not a `Date`, because a time of day has no date. */
 export interface TimeValue {
     hours: number;
     minutes: number;
@@ -10,13 +11,19 @@ export interface TimePickerProps {
      * its own part name.
      */
     id?: string;
+    /** The time: `{ hours, minutes }`, not a `Date`, because a time of day has no date. */
     value?: TimeValue;
+    /** Called with the new time. */
     onValueChange?: (value: TimeValue) => void;
-    /** Adds a seconds segment. */
+    /**
+     * Adds a third segment, for seconds. Most times of day do not have one, and an empty
+     * seconds box invites a value nobody wanted.
+     */
     withSeconds?: boolean;
-    /** Minutes snap to this. 15 gives a quarter-hour picker. */
+    /** The minute increment: minutes snap to it. 15 gives a quarter-hour picker. */
     minuteStep?: number;
     disabled?: boolean;
+    /** The error surface. The message stays on the `FormField`. */
     invalid?: boolean;
     className?: string;
     /** Overrides this picker's own copy — the group and the three segments. */

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

@@ -5,4 +5,12 @@ import { OverlayContentProps } from '../overlay/index.js';
  */
 import * as React from "react";
 export type DialogContentProps = Omit<OverlayContentProps, "placement"> & Omit<React.ComponentProps<"dialog">, "children" | "className" | "title">;
+/**
+ * OverlayContent with `placement` fixed to centre, and that is the whole of the dialog.
+ * `modality`, `surface`, `dismissal`, `initialFocusRef` and `showCloseButton` are
+ * OverlayContent's props, with the same defaults.
+ *
+ * The rest of a dialog is Overlay's own parts, imported from `base/overlay` under their own
+ * names. There is no second name for them, so nothing about them can drift.
+ */
 export declare function DialogContent({ className, ...props }: DialogContentProps): React.JSX.Element;

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

@@ -1,6 +1,16 @@
 import type * as React from "react";
 export interface DirectionProviderProps {
+    /**
+     * The reading direction for a subtree, as the menus, popovers and other script-positioned
+     * parts inside it read it. The kit's CSS is logical and follows the `dir` attribute, so
+     * set `dir` on the region as well for its layout to mirror.
+     */
     direction?: "ltr" | "rtl";
     children?: React.ReactNode;
 }
+/**
+ * Tells script-positioned UI — menus, popovers — the writing direction of a subtree. Set
+ * `dir` on `<html>` or the region as well, so the browser handles selection, caret and
+ * scroll, and the kit's logical CSS mirrors.
+ */
 export declare function DirectionProvider({ direction, children }: DirectionProviderProps): React.JSX.Element;

package/dist/components/base/display/boolean-indicator.d.ts

@@ -2,8 +2,13 @@ import { BooleanIndicatorStrings } from './boolean-indicator.strings.js';
 /** BooleanIndicator — a yes/no state as a dot and a word; the word is required, since colour alone fails. */
 import * as React from "react";
 export interface BooleanIndicatorProps extends Omit<React.ComponentProps<"span">, "children"> {
+    /** The state, drawn as a dot and a word so it does not rely on colour alone. */
     value?: boolean | null;
-    /** Overrides what each state is called. Yes/No, Enabled/Disabled, Paid/Unpaid. */
+    /**
+     * Overrides what each state is called: `strings.true` and `strings.false`, the two words.
+     * Yes/No, Enabled/Disabled, Paid/Unpaid — "Active"/"Paused" beats "true"/"false".
+     */
     strings?: Partial<BooleanIndicatorStrings>;
 }
+/** A yes/no state as a dot and a word. The word is required, since colour alone fails. */
 export declare function BooleanIndicator({ value, strings, className, ...props }: BooleanIndicatorProps): React.JSX.Element;

package/dist/components/base/display/collapsible.d.ts

@@ -1,10 +1,19 @@
 /** Collapsible — a disclosure that animates to its content's natural height, CSS-only (`grid-template-rows: 0fr → 1fr`). */
 import * as React from "react";
 export interface CollapsibleProps extends Omit<React.ComponentProps<"div">, "onToggle"> {
+    /** Whether the content is shown, for controlled state. */
     open?: boolean;
+    /** Whether the content starts shown, for uncontrolled state. */
     defaultOpen?: boolean;
+    /** Fires on every toggle, from the pointer or the keyboard. */
     onOpenChange?: (open: boolean) => void;
 }
+/** A disclosure that animates to its content's natural height, in CSS alone. */
 export declare function Collapsible({ open, defaultOpen, onOpenChange, className, children, ...props }: CollapsibleProps): React.JSX.Element;
+/** The control. Carries `aria-expanded` and points at the content. */
 export declare function CollapsibleTrigger({ className, children, onClick, ...props }: React.ComponentProps<"button">): React.JSX.Element;
+/**
+ * The disclosed region. It stays mounted while collapsed, to animate, and is inert then, so
+ * its controls leave the tab order.
+ */
 export declare function CollapsibleContent({ className, children, ...props }: React.ComponentProps<"div">): React.JSX.Element;

package/dist/components/base/display/content-block.d.ts

@@ -5,20 +5,31 @@ import { ComponentProps, ReactNode } from 'react';
  */
 export type ContentBlockSurface = "plain" | "bordered" | "muted" | "card";
 export interface ContentBlockProps extends Omit<ComponentProps<"div">, "title"> {
+    /**
+     * The heading. Either it or `description` renders the header; neither, and the block is a
+     * bare surface.
+     */
     title?: ReactNode;
+    /** Supporting copy on its own row, so a long one wraps under the whole header. */
     description?: ReactNode;
-    /** Glyph on the title line. */
+    /** Leading glyph on the title line. */
     icon?: ReactNode;
     /** Content immediately after the title — a badge, a count. */
     titleSuffix?: ReactNode;
     /** Controls at the end of the title line. */
     headerEnd?: ReactNode;
+    /**
+     * Outer chrome. What separates `bordered` from `card` is the ground: a bordered block is a
+     * ruled region and the page shows through it; a card block lifts off it.
+     */
     surface?: ContentBlockSurface;
     /**
      * Drops the surface's inset and clips to its radius, for content that runs to the edge
-     * (divided cells, ruled rows); children pay their own inset. Only meaningful on a surface.
+     * (divided cells, ruled rows); children pay their own inset. Only meaningful on a surface
+     * that has an inset to drop.
      */
     flush?: boolean;
     children?: ReactNode;
 }
+/** A titled region inside a panel, not a panel itself: use it instead of nesting Cards. */
 export declare function ContentBlock({ title, description, icon, titleSuffix, headerEnd, surface, flush, className, children, ...props }: ContentBlockProps): import("react").JSX.Element;

package/dist/components/base/display/date-block.d.ts

@@ -1,26 +1,46 @@
 import { ComponentProps, ReactNode } from 'react';
 export type DateBlockLayout = "stacked" | "inline";
 export interface DateBlockProps extends Omit<ComponentProps<"time">, "children" | "dateTime"> {
-    /** A Date, an ISO string, or a timestamp. */
+    /**
+     * A Date, an ISO string, or a timestamp. Nothing parseable renders nothing — an empty leaf
+     * would be a claim.
+     */
     date?: Date | string | number | null;
-    /** Already-formatted time or range — "09:00 – 10:30". */
+    /**
+     * An already-formatted time or range — "09:00 – 10:30" — under the weekday in the stacked
+     * layout.
+     */
     time?: ReactNode;
-    /** Overrides the machine-readable value. */
+    /** Overrides the machine-readable value, which is otherwise the date's ISO string. */
     dateTime?: string;
+    /** A calendar leaf, or a phrase at the size of the line it sits in. */
     layout?: DateBlockLayout;
-    /** A bounded surface. Defaults on for stacked, off for inline. */
+    /**
+     * The leaf's box and month band: a bounded surface. Defaults on for stacked and off for
+     * inline; turn it off for a surface that already frames the leaf.
+     * @default true
+     */
     boxed?: boolean;
+    /** Shows the weekday. */
     showWeekday?: boolean;
+    /** Shows the month. Without it there is no band. */
     showMonth?: boolean;
     /** Adds the year under the month, for a date outside the current one. */
     showYear?: boolean;
     /**
-     * date-fns patterns for the fragments. Names come from the scope's date-fns locale, so
-     * these are patterns, not strings.
+     * date-fns pattern for the weekday. Names come from the `UIProvider`'s date-fns locale, so
+     * these are patterns, not strings: a Greek scope reads "Κυρ" without a strings object.
      */
     weekdayFormat?: string;
+    /** date-fns pattern for the day. */
     dayFormat?: string;
+    /** date-fns pattern for the month, named in the scope's locale. */
     monthFormat?: string;
+    /** date-fns pattern for the year. */
     yearFormat?: string;
 }
+/**
+ * A date as a calendar leaf, rendered as `<time>` with a machine-readable `dateTime`, so the
+ * stacked fragments stay one parseable value.
+ */
 export declare function DateBlock({ date, time, dateTime, layout, boxed, showWeekday, showMonth, showYear, weekdayFormat, dayFormat, monthFormat, yearFormat, className, ...props }: DateBlockProps): import("react").JSX.Element | null;

package/dist/components/base/display/icon-badge.d.ts

@@ -2,16 +2,25 @@ import { ComponentProps, ComponentType, ReactNode } from 'react';
 export type IconBadgeTone = "neutral" | "primary" | "success" | "warning" | "destructive" | "info";
 export type IconBadgeShape = "rounded" | "circle";
 export interface IconBadgeProps extends Omit<ComponentProps<"span">, "children"> {
-    /** A component or a rendered node. */
+    /**
+     * A component or a rendered node. A component is called with `aria-hidden`, because the
+     * badge is a mark beside a name that already says it.
+     */
     icon?: ComponentType<{
         className?: string;
     }> | ReactNode;
     children?: ReactNode;
+    /** Sets the fill and the glyph together, so the two cannot come from different tones. */
     tone?: IconBadgeTone;
+    /** A rounded square, or a circle. */
     shape?: IconBadgeShape;
     /** Fills with the tone and inverts the glyph — for the one badge that must stand out. */
     solid?: boolean;
     /** A hairline outline, for a badge on a surface it would otherwise blend into. */
     bordered?: boolean;
 }
+/**
+ * A glyph in a tinted medallion. Its size comes from `--icon-badge-size`, so a caller
+ * needing a smaller mark re-points the token instead of redrawing the badge.
+ */
 export declare function IconBadge({ icon, children, tone, shape, solid, bordered, className, ...props }: IconBadgeProps): import("react").JSX.Element;

package/dist/components/base/display/inline-stat.d.ts

@@ -5,12 +5,19 @@ import { ReactNode, ComponentProps } from 'react';
  */
 export type InlineStatLayout = "between" | "inline" | "stacked";
 export interface InlineStatProps extends Omit<ComponentProps<"div">, "children"> {
-    /** Names the fact. */
+    /** Names the fact. Rendered as a `DisplayLabel`, which has one style everywhere. */
     label: ReactNode;
-    /** The fact itself. Absent renders the empty marker. */
+    /**
+     * The fact itself. Absent renders the empty marker rather than collapsing the row to its
+     * label — a dash says the fact was looked for.
+     */
     value?: ReactNode;
+    /** How the free space between label and value is spent — the only thing the three change. */
     layout?: InlineStatLayout;
-    /** Tabular figures, for amounts and counters, so a column of these compares cleanly. */
+    /**
+     * Tabular figures, for an amount or a counter — what makes a column of these compare down
+     * the page instead of jittering with each digit's width.
+     */
     mono?: boolean;
 }
 export declare function InlineStat({ label, value, layout, mono, className, ...props }: InlineStatProps): import("react").JSX.Element;

package/dist/components/base/display/kbd.d.ts

@@ -1,4 +1,13 @@
 import { ComponentProps } from 'react';
+/**
+ * One key, or one chord pressed together written as a single string — "⌘K", not three caps,
+ * because nested `Kbd`s are announced element by element. A native `<kbd>`: every native
+ * attribute passes through.
+ */
 export declare function Kbd({ className, ...props }: ComponentProps<"kbd">): import("react").JSX.Element;
-/** Several caps as a sequence ("⌘ then K"); the gap between caps marks it as a sequence, not a chord. */
+/**
+ * Several `Kbd` in a row, for a sequence pressed one after another — "G then I". The caps sit
+ * further apart than the characters inside one, and that gap is what tells a reader the keys
+ * are pressed in turn rather than together.
+ */
 export declare function KbdGroup({ className, ...props }: ComponentProps<"span">): import("react").JSX.Element;

package/dist/components/base/display/metadata-list.d.ts

@@ -6,19 +6,27 @@ export type MetadataColumns = 1 | 2 | 3 | 4;
 export type MetadataLayout = "grid" | "rows" | "inline";
 /** `compact` tightens the rhythm for a dense panel. */
 export type MetadataDensity = "default" | "compact";
+/** One fact: a label and a value, and optionally a description, a tooltip and an icon. */
 export interface MetadataListItem {
     /** Stable identity. Without one the label and index stand in. */
     id?: string;
+    /** Names the fact. */
     label: ReactNode;
     /** A node, or a descriptor that names the fact's kind. */
     value?: ReactNode | MetadataValueDescriptor | null;
     /** Supporting copy under the value. */
     description?: ReactNode | null;
-    /** Shown from an info trigger beside the label — for a fact that needs explaining. */
+    /**
+     * Shown from an info trigger beside the label — for a fact that needs explaining. The
+     * trigger is named after the label through `strings.formatInfoLabel` ("Amount info"), a
+     * function rather than a suffix because word order differs by language.
+     */
     tooltip?: ReactNode;
+    /** A glyph before the label. */
     icon?: ComponentType<{
         className?: string;
     }>;
+    /** Shown when this fact's value is absent, in place of the list's `emptyLabel`. */
     emptyLabel?: ReactNode;
     /** Takes over the value entirely, for one fact that none of the kinds cover. */
     render?: (item: MetadataListItem) => ReactNode;
@@ -29,31 +37,59 @@ export type MetadataInlineListItem = Omit<MetadataListItem, "description"> & {
 };
 interface MetadataListSharedProps {
     /**
-     * How many columns the grid uses. A plain number picks a responsive recipe; an object
-     * sets the breakpoints itself.
+     * How many columns the grid uses — a ceiling for the grid layout. A plain number picks a
+     * responsive recipe; an object sets the breakpoints itself.
      */
     columns?: ResponsiveValue<MetadataColumns>;
+    /**
+     * `compact` tightens the rhythm — the gaps and the row inset — for a dense panel. The value
+     * keeps its size.
+     */
     density?: MetadataDensity;
-    /** Shown for a fact whose value is absent. Defaults to an em dash. */
+    /**
+     * Shown for a fact whose value is absent. A dash says "we looked"; an omitted row does
+     * not.
+     */
     emptyLabel?: ReactNode;
+    /** A label above the facts. */
     title?: ReactNode;
     /** Draws a rule between the title and the first fact. */
     titleSeparator?: boolean;
     className?: string;
     /** Between a label and its value, inline. Defaults to a colon. */
     separator?: string;
-    /** Between facts — `true` for the default rule, or a character for the inline layout. */
+    /**
+     * Between facts: `true` for a rule in the rows layout, or a character for the inline
+     * one.
+     */
     itemSeparator?: boolean | string;
+    /** Overrides this list's own copy — the info triggers' names. */
     strings?: Partial<MetadataListStrings>;
 }
 interface MetadataGridRowsProps extends MetadataListSharedProps {
+    /**
+     * The facts: a label and a value each, and optionally a description, a tooltip, an icon,
+     * an empty label and a renderer.
+     */
     items: MetadataListItem[];
+    /**
+     * How the facts are laid out: `grid` (label above value, in columns, for detail panels),
+     * `rows` (a ruled list, for labels of varied length), or `inline` ("Created 4 Jan · By
+     * Alice · v3.2"), whose items take no description. One component, because the three carry
+     * the same data — a screen that switches between them changes a prop, not its items.
+     */
     layout?: "grid" | "rows";
 }
 interface MetadataInlineProps extends MetadataListSharedProps {
+    /** The facts, without descriptions: the inline layout has no second line for one. */
     items: MetadataInlineListItem[];
+    /** The inline layout: "Created 4 Jan · By Alice · v3.2". */
     layout: "inline";
 }
 export type MetadataListProps = MetadataGridRowsProps | MetadataInlineProps;
+/**
+ * Label/value facts about one thing, in three layouts over the same data. Returns `null`
+ * when the list is empty, so a caller can render it unconditionally.
+ */
 export declare function MetadataList({ items, columns, density, emptyLabel, title, titleSeparator, className, layout, separator, itemSeparator, strings, }: MetadataListProps): import("react").JSX.Element | null;
 export {};

package/dist/components/base/display/placeholder-pattern.d.ts

@@ -1,3 +1,8 @@
 import { ComponentProps } from 'react';
 export type PlaceholderPatternProps = ComponentProps<"div">;
+/**
+ * Diagonal hatching for a region with nothing in it yet — a chart with no data, a slot
+ * awaiting an upload. It reads as deliberately empty; a blank box reads as broken. Not a
+ * Skeleton, which says "loading".
+ */
 export declare function PlaceholderPattern({ className, ...props }: PlaceholderPatternProps): import("react").JSX.Element;

package/dist/components/base/display/scroll-area.d.ts

@@ -3,4 +3,8 @@
  * `overscroll-behavior: contain`, so reaching the end doesn't scroll the page behind.
  */
 import * as React from "react";
+/**
+ * A scroll container with the kit's scrollbar treatment, contained so reaching the end
+ * doesn't scroll the page behind. Give it a max height; it does not impose one.
+ */
 export declare function ScrollArea({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;

package/dist/components/base/display/separator.d.ts

@@ -2,14 +2,26 @@ import { Separator as SeparatorPrimitive } from '@base-ui/react/separator';
 import * as React from "react";
 /** How the rule is drawn — structural, so a `variant`. Dashed and dotted read as provisional. */
 export type SeparatorVariant = "solid" | "dashed" | "dotted";
-export interface SeparatorProps extends SeparatorPrimitive.Props {
+export interface SeparatorProps extends SeparatorPrimitive.Props, Pick<SeparatorPrimitive.Props, "aria-hidden"> {
+    /**
+     * How the rule is drawn. Structural, not semantic — a dashed rule is the same divider,
+     * drawn as provisional.
+     */
     variant?: SeparatorVariant;
     /**
      * The rule's thickness: a CSS length, or a number in pixels. Overrides
      * `--separator-thickness` for this rule, e.g. a seam between panels.
      */
     thickness?: string | number;
-    /** Text set into a gap in the rule — "OR", "More options". Horizontal only. */
+    /**
+     * Text set into a gap in the rule — "OR", "More options". Horizontal only. It drops the
+     * separator role, because the rule is then decoration around real text.
+     */
     label?: React.ReactNode;
 }
+/**
+ * A rule between content, horizontal or vertical; a vertical separator needs a height from
+ * its container. An unlabelled separator exposes separator semantics: set `aria-hidden` to
+ * hide a decorative rule from assistive technology.
+ */
 export declare function Separator({ className, orientation, variant, thickness, label, style, ...props }: SeparatorProps): React.JSX.Element;

package/dist/components/base/display/visually-hidden.d.ts

@@ -9,4 +9,8 @@ export interface VisuallyHiddenProps extends React.ComponentProps<"span"> {
         className?: string;
     }>;
 }
+/**
+ * Present to assistive technology, absent on screen. Not `display: none`, which removes it
+ * from both.
+ */
 export declare function VisuallyHidden({ className, render, ...props }: VisuallyHiddenProps): React.JSX.Element;