themelia-ui 2.0.0 → 3.0.0

package/dist/components/base/forms-numeric/unit-inputs.d.ts

@@ -19,29 +19,50 @@ export interface WeightInputProps extends ClusterFieldWiring {
      * keeps its own `aria-label` for its part.
      */
     id?: string;
-    /** Overrides this field's own copy — the unit selector's name. */
+    /**
+     * Overrides this field's own copy — the unit selector's name. Like every other piece of
+     * copy, each string can be overridden on its own.
+     */
     strings?: Partial<UnitInputStrings>;
-    /** Controlled amount, as a plain string. */
+    /** Controlled amount: the number, as a plain string. */
     value?: string;
+    /** The starting amount, for an uncontrolled field. */
     defaultValue?: string;
+    /** Called with a change event shaped like a native one, carrying the amount. */
     onChange?: (event: ValueChangeEvent) => void;
-    /** Controlled unit. */
+    /**
+     * Controlled unit, apart from the number. Switching unit does not convert — it relabels.
+     */
     unit?: WeightUnit;
+    /** The unit the field starts in. */
     defaultUnit?: WeightUnit;
+    /** Called with the new unit. Switching relabels rather than converting — the number is the caller's. */
     onUnitChange?: (unit: WeightUnit) => void;
+    /** Which units the selector offers. */
     units?: WeightUnit[];
+    /** Digits after the separator. */
     decimalPlaces?: number;
+    /** The lower bound. */
     min?: number;
+    /** The upper bound. */
     max?: number;
+    /** The increment for the − / + controls. */
     step?: number;
+    /** Shows the unit selector. Turn it off for a field with one fixed unit. */
     showUnitSelector?: boolean;
+    /** Shows the unit selector read-only, for a value whose unit is decided elsewhere. */
     disableUnitSelector?: boolean;
     placeholder?: string;
     disabled?: boolean;
+    /** The error surface. The message stays on the `FormField`. */
     invalid?: boolean;
     className?: string;
     "aria-label"?: string;
 }
+/**
+ * A weight: the number and its unit in separate channels, as `CurrencyInput` keeps the
+ * currency — "1.5 kg" in one string is ambiguous to parse.
+ */
 export declare const WeightInput: import('react').ForwardRefExoticComponent<WeightInputProps & import('react').RefAttributes<HTMLInputElement>>;
 export type DimensionUnit = "mm" | "cm" | "m" | "in" | "ft" | "px";
 export interface DimensionsValue {
@@ -55,22 +76,41 @@ export interface DimensionsInputProps extends ClusterFieldWiring {
      * keeps its own `aria-label` for its part.
      */
     id?: string;
+    /**
+     * `{ length, width, height }`: three strings, one field. Each part is independently
+     * editable.
+     */
     value?: DimensionsValue;
+    /** Called with the whole value when any part changes. */
     onValueChange?: (value: DimensionsValue) => void;
+    /** Controlled unit. Switching unit does not convert — it relabels. */
     unit?: DimensionUnit;
+    /** The unit the field starts in. */
     defaultUnit?: DimensionUnit;
+    /** Called with the new unit. Switching relabels rather than converting — the number is the caller's. */
     onUnitChange?: (unit: DimensionUnit) => void;
+    /** Which units the selector offers. */
     units?: DimensionUnit[];
+    /** Digits after the separator, applied to every part of the field. */
     decimalPlaces?: number;
-    /** Drops the height field, for a two-dimensional measurement. */
+    /**
+     * Shows the third dimension box. Turn it off for a value that is a plane rather than a
+     * solid: a two-dimensional measurement.
+     */
     showHeight?: boolean;
+    /** Shows the unit selector. Turn it off for a field with one fixed unit. */
     showUnitSelector?: boolean;
-    /** Overrides this field's own copy — the three axis names and the unit selector. */
+    /**
+     * Overrides this field's own copy — the three axis names and the unit selector. Like every
+     * other piece of copy, each string can be overridden on its own.
+     */
     strings?: Partial<DimensionsInputStrings>;
     disabled?: boolean;
+    /** The error surface. The message stays on the `FormField`. */
     invalid?: boolean;
     className?: string;
 }
+/** Length, width and height as one field, with one unit for all three. */
 export declare const DimensionsInput: import('react').ForwardRefExoticComponent<DimensionsInputProps & import('react').RefAttributes<HTMLDivElement>>;
 export interface CoordinatesValue {
     latitude?: string;
@@ -82,14 +122,24 @@ export interface CoordinatesInputProps extends ClusterFieldWiring {
      * keeps its own `aria-label` for its part.
      */
     id?: string;
+    /**
+     * `{ latitude, longitude }`: two strings, kept apart so a half-typed latitude cannot
+     * corrupt the longitude.
+     */
     value?: CoordinatesValue;
+    /** Called with the whole value when either part changes. */
     onValueChange?: (value: CoordinatesValue) => void;
     /** Six places is roughly 0.1 m — past the precision of consumer GPS. */
     decimalPlaces?: number;
-    /** Overrides this field's own copy — the two axis names. */
+    /**
+     * Overrides this field's own copy — the two axis names. Like every other piece of copy,
+     * each string can be overridden on its own.
+     */
     strings?: Partial<CoordinatesInputStrings>;
     disabled?: boolean;
+    /** The error surface. The message stays on the `FormField`. */
     invalid?: boolean;
     className?: string;
 }
+/** A latitude and a longitude as one field, each with its own bounds. */
 export declare const CoordinatesInput: import('react').ForwardRefExoticComponent<CoordinatesInputProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/components/base/hover-card/hover-card.d.ts

@@ -6,8 +6,12 @@ export declare function HoverCard(props: HoverCardProps): import("react").JSX.El
 export interface HoverCardTriggerProps extends PreviewCard.Trigger.Props {
 }
 /**
- * Trigger with default delays. `closeDelay` keeps the card open while the pointer crosses
- * the gap to it.
+ * What opens the card. Hover and focus both open it, because a card reachable only by
+ * pointer is unreachable to a keyboard.
+ *
+ * The delays live here, on the trigger. `closeDelay` is the load-bearing one: it keeps the
+ * card open while the pointer crosses the gap to it, and without it the card closes as the
+ * pointer leaves the trigger.
  */
 export declare function HoverCardTrigger({ delay, closeDelay, ...props }: HoverCardTriggerProps): import("react").JSX.Element;
 export interface HoverCardContentProps extends PreviewCard.Popup.Props {
@@ -16,8 +20,15 @@ export interface HoverCardContentProps extends PreviewCard.Popup.Props {
      * own target.
      */
     container?: UIPortalContainer;
+    /** How the card lines up along the side it opens on: `start`, `center` or `end`. */
     align?: PreviewCard.Positioner.Props["align"];
+    /**
+     * Where the card opens relative to its trigger: `top`, `right`, `bottom` or `left`, or
+     * the logical `inline-start` or `inline-end`.
+     */
     side?: PreviewCard.Positioner.Props["side"];
+    /** The gap between the trigger and the card, in pixels. */
     sideOffset?: PreviewCard.Positioner.Props["sideOffset"];
 }
+/** What the card shows: the preview itself, placed against its trigger. */
 export declare function HoverCardContent({ container, align, side, sideOffset, className, ...props }: HoverCardContentProps): import("react").JSX.Element;

package/dist/components/base/input-group/input-group.d.ts

@@ -1,29 +1,52 @@
 import { Button } from '../buttons/index.js';
 import { TextareaProps } from '../text-inputs/index.js';
-import { VariantProps } from '../../../lib/cvm.js';
 import * as React from "react";
+/**
+ * The shell, with `role="group"`. It owns the border and the focus ring for whatever is
+ * inside, so the control strips its own.
+ */
 declare function InputGroup({ className, id, "aria-labelledby": labelledBy, "aria-describedby": describedBy, "aria-invalid": invalid, "aria-required": required, ...props }: React.ComponentProps<"div">): React.JSX.Element;
-declare const inputGroupAddonVariants: (props?: ({
-    align?: ("inline-end" | "inline-start" | "block-end" | "block-start") | null | undefined;
-} & {
-    className?: import('clsx').ClassValue;
-}) | undefined) => string;
-declare function InputGroupAddon({ className, align, ...props }: React.ComponentProps<"div"> & VariantProps<typeof inputGroupAddonVariants>): React.JSX.Element;
-declare const inputGroupButtonVariants: (props?: ({
-    size?: ("sm" | "xs" | "icon-xs" | "icon-sm") | null | undefined;
-} & {
-    className?: import('clsx').ClassValue;
-}) | undefined) => string;
-declare function InputGroupButton({ className, type, tone, buttonStyle, size, ...props }: Omit<React.ComponentProps<typeof Button>, "size" | "type"> & VariantProps<typeof inputGroupButtonVariants> & {
+export interface InputGroupAddonProps extends React.ComponentProps<"div"> {
+    /**
+     * Where the addon attaches. The inline edges sit on the control's line; the block edges
+     * take a row of their own, for a toolbar above a textarea or a hint below one.
+     */
+    align?: "inline-start" | "inline-end" | "block-start" | "block-end";
+}
+/**
+ * Something attached to the field — a unit, a prefix, a submit. Clicking it focuses the
+ * control, as a label does, unless the click lands on a button.
+ */
+declare function InputGroupAddon({ className, align, ...props }: InputGroupAddonProps): React.JSX.Element;
+export interface InputGroupButtonProps extends Omit<React.ComponentProps<typeof Button>, "size" | "type"> {
+    /**
+     * The sizes that fit inside a field: two text sizes and their icon-only twins. A
+     * full-height Button would set the field's height rather than fit in it, which is why
+     * this is the one place the kit keeps a size prop on a control.
+     */
+    size?: "xs" | "sm" | "icon-xs" | "icon-sm";
+    /** The native button type: `button` unless set, so pressing it never submits the form around the field. */
     type?: "button" | "submit" | "reset";
-}): React.JSX.Element;
+}
+/** A quiet Button sized to sit inside the field rather than beside it. */
+declare function InputGroupButton({ className, type, tone, buttonStyle, size, ...props }: InputGroupButtonProps): React.JSX.Element;
+/**
+ * Secondary text at the group's own size — a unit, a domain suffix, a counter. It inherits
+ * the size, so it cannot drift from the input beside it.
+ */
 declare function InputGroupText({ className, ...props }: React.ComponentProps<"span">): React.JSX.Element;
+/**
+ * The kit's Input with its chrome removed, because the group is drawing it. Every other
+ * prop passes through.
+ */
 declare function InputGroupInput({ className, ...props }: React.ComponentProps<"input">): React.JSX.Element;
+/**
+ * The kit's Textarea with its chrome removed, because the group is drawing it. Every other
+ * prop passes through.
+ */
 declare function InputGroupTextarea({ className, ...props }: TextareaProps): React.JSX.Element;
 export { InputGroup, InputGroupAddon, InputGroupButton, InputGroupText, InputGroupInput, InputGroupTextarea, };
 export type InputGroupProps = React.ComponentProps<"div">;
-export type InputGroupAddonProps = React.ComponentProps<"div">;
 export type InputGroupTextProps = React.ComponentProps<"span">;
 export type InputGroupInputProps = React.ComponentProps<"input">;
 export type InputGroupTextareaProps = React.ComponentProps<"textarea">;
-export type InputGroupButtonProps = React.ComponentProps<typeof Button>;

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

@@ -1,37 +1,58 @@
 import { useRender } from '@base-ui/react/use-render';
 import { Separator } from '../display/index.js';
-import { VariantProps } from '../../../lib/cvm.js';
 import * as React from "react";
 export interface ItemGroupProps extends React.ComponentProps<"div"> {
     /**
-     * Draws rules between rows instead of gaps, and neutral rows drop their inline padding.
-     * Use for a run of rows inside one card.
+     * Draws hairlines between rows instead of gaps, and neutral rows drop their inline
+     * padding and go flush. For a run of rows inside one card, where a rem of air between
+     * each reads as unrelated blocks. Bordered and muted rows keep their inset, because they
+     * do draw a surface.
      */
     ruled?: boolean;
 }
+/** Stacks rows and owns the dividers, so a row never draws its own. */
 declare function ItemGroup({ className, ruled, ...props }: ItemGroupProps): React.JSX.Element;
+/**
+ * A rule between items, for a group that wants one only in places. `ItemGroup ruled` is the
+ * answer when every row needs one.
+ */
 declare function ItemSeparator({ className, ...props }: React.ComponentProps<typeof Separator>): React.JSX.Element;
-declare const itemVariants: (props?: ({
-    surface?: ("neutral" | "bordered" | "muted") | null | undefined;
-} & {
-    className?: import('clsx').ClassValue;
-}) | undefined) => string;
 export type ItemSurface = "neutral" | "bordered" | "muted";
+interface ItemProps extends useRender.ComponentProps<"div"> {
+    /** The row's chrome. Never `default`: the vocabulary is fixed. */
+    surface?: "neutral" | "bordered" | "muted";
+}
+/**
+ * A row — a list row, a menu row, a table row. No size prop: row height follows
+ * `--density-scale`, so use a denser scope for a denser list.
+ */
+declare function Item({ className, surface, render, ...props }: ItemProps): React.JSX.Element;
+interface ItemMediaProps extends React.ComponentProps<"div"> {
+    /**
+     * Sizes the leading slot. `icon` fits a glyph; `image` gets the larger box an avatar or
+     * thumbnail needs; `plain` leaves the slot to its content.
+     */
+    variant?: "plain" | "icon" | "image";
+}
+/** The leading slot: a glyph, an avatar or a thumbnail, aligned to the first line. */
+declare function ItemMedia({ className, variant, ...props }: ItemMediaProps): React.JSX.Element;
 /**
- * Item — a row. No size prop: row height follows `--density-scale`, so use a denser
- * scope for a denser list.
+ * The title and description. Takes the remaining width and truncates rather than pushing
+ * the actions off the row.
  */
-declare function Item({ className, surface, render, ...props }: useRender.ComponentProps<"div"> & VariantProps<typeof itemVariants>): React.JSX.Element;
-declare const itemMediaVariants: (props?: ({
-    variant?: ("image" | "icon" | "plain") | null | undefined;
-} & {
-    className?: import('clsx').ClassValue;
-}) | undefined) => string;
-declare function ItemMedia({ className, variant, ...props }: React.ComponentProps<"div"> & VariantProps<typeof itemMediaVariants>): React.JSX.Element;
 declare function ItemContent({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
 declare function ItemTitle({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
 declare function ItemDescription({ className, ...props }: React.ComponentProps<"p">): React.JSX.Element;
+/** Trailing controls. Kept out of the content flow, so a long title cannot displace them. */
 declare function ItemActions({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+/**
+ * A full-width row above the row's own content, for an item that carries an eyebrow
+ * without it competing with the title line.
+ */
 declare function ItemHeader({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+/**
+ * A full-width row below the row's own content, for an item that carries a footnote
+ * without it competing with the title line.
+ */
 declare function ItemFooter({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
 export { Item, ItemMedia, ItemContent, ItemActions, ItemGroup, ItemSeparator, ItemTitle, ItemDescription, ItemHeader, ItemFooter, };

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

@@ -1,3 +1,14 @@
 import * as React from "react";
-declare function Label({ className, ...props }: React.ComponentProps<"label">): React.JSX.Element;
+interface LabelProps extends React.ComponentProps<"label"> {
+    /**
+     * The control's id. Without it the label is decoration: clicking it does nothing and
+     * nothing is announced.
+     */
+    htmlFor?: string;
+}
+/**
+ * A form label: a real `<label>`, so clicking it focuses the control it names. Takes
+ * everything a native label takes.
+ */
+declare function Label({ className, ...props }: LabelProps): React.JSX.Element;
 export { Label };

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

@@ -2,6 +2,18 @@ import { Menubar as MenubarPrimitive } from '@base-ui/react/menubar';
 import { Menu as MenuPrimitive } from '@base-ui/react/menu';
 export interface MenubarProps extends MenubarPrimitive.Props {
 }
+/**
+ * The bar. Its menus are `DropdownMenu` roots, each holding a `MenubarTrigger` and a
+ * `DropdownMenuContent` with every row the dropdown menu offers.
+ *
+ * The menu itself is the dropdown menu module's, not a copy under a second name — so
+ * groups, labels, checkbox and radio items, submenus and the portal are the dropdown
+ * menu's parts too, and a reader who has learned one has learned the other.
+ */
 export declare function Menubar({ className, ...props }: MenubarProps): import("react").JSX.Element;
-/** One menu's word in the bar. Place it inside a `DropdownMenu`, beside its content. */
+/**
+ * One menu's word in the bar, placed inside a `DropdownMenu` beside its
+ * `DropdownMenuContent`. Once a menu is open, moving along the bar opens the next without
+ * a second click — which is what makes a menubar a menubar rather than a row of dropdowns.
+ */
 export declare function MenubarTrigger({ className, ...props }: MenuPrimitive.Trigger.Props): import("react").JSX.Element;

package/dist/components/base/navigation/breadcrumbs.d.ts

@@ -4,21 +4,36 @@ import { BreadcrumbsStrings } from './navigation.strings.js';
  * are `aria-hidden`.
  */
 import * as React from "react";
+/** One entry in a `Breadcrumbs` trail. */
 export type Crumb = {
+    /** What the crumb reads as. */
     label: React.ReactNode;
+    /** Where the crumb goes, as a plain anchor. */
     href?: string;
-    /** Router link element, so the library never imports a router. */
+    /**
+     * A router link element, so the library never imports a router. It replaces the plain
+     * anchor, and `label` becomes its content.
+     */
     render?: React.ReactElement<{
         className?: string;
         children?: React.ReactNode;
     }>;
 };
 export interface BreadcrumbsProps extends Omit<React.ComponentProps<"nav">, "children"> {
+    /** The trail. The last entry renders as the current page. */
     items: Crumb[];
+    /**
+     * Replaces the chevron between crumbs. It is decorative either way — the trail's meaning
+     * is in the links.
+     */
     separator?: React.ReactNode;
     /** Names this one trail. Overrides the strings default. */
     label?: string;
     /** Overrides the default name for every trail. */
     strings?: Partial<BreadcrumbsStrings>;
 }
+/**
+ * The trail to the current page, in a `<nav>`. The current page is a span marked
+ * `aria-current="page"`, not a link: a link to the page you are on is a dead control.
+ */
 export declare function Breadcrumbs({ items, separator, label, strings, className, ...props }: BreadcrumbsProps): React.JSX.Element;

package/dist/components/base/navigation/index.d.ts

@@ -8,3 +8,4 @@ export { NavigationTabs, type NavigationTabItem, type NavigationTabsProps } from
 export { LanguageSwitcher, type LanguageSwitcherProps, type LanguageSwitcherVariant, type LocaleOption, } from './language-switcher.js';
 export { defaultPaginationStrings, defaultBreadcrumbsStrings, defaultTabListStrings, type PaginationStrings, type BreadcrumbsStrings, type TabListStrings, } from './navigation.strings.js';
 export { defaultNavigationTabsStrings, defaultOverflowTabBarStrings, type NavigationTabsStrings, type OverflowTabBarStrings, } from './navigation-tabs.strings.js';
+export type { LinkRenderer, LinkRenderProps } from '../../../lib/navigation.js';

package/dist/components/base/navigation/language-switcher.d.ts

@@ -8,13 +8,24 @@ export interface LocaleOption {
 }
 export type LanguageSwitcherVariant = "menu" | "pills";
 export interface LanguageSwitcherProps extends Omit<ComponentProps<"div">, "onSelect"> {
+    /** The languages offered, each named in its own language. */
     locales: LocaleOption[];
+    /** The current locale's `value`. */
     value?: string;
+    /** Called with the chosen locale's `value`. */
     onSelect?: (value: string) => void;
-    /** `pills` for two or three languages; `menu` once there are more. */
+    /**
+     * `pills` for two or three languages, where every option is worth showing; `menu` once
+     * there are more, where a row of pills becomes a second navigation.
+     */
     variant?: LanguageSwitcherVariant;
+    /** Names this one switcher. Overrides the strings default. */
     label?: string;
     /** Overrides the default name for every switcher. */
     strings?: Partial<LanguageSwitcherStrings>;
 }
+/**
+ * The locale control. Each option is named in its own language and carries `lang`, so a
+ * screen reader pronounces it correctly.
+ */
 export declare function LanguageSwitcher({ locales, value, onSelect, variant, label, strings, className, ...props }: LanguageSwitcherProps): import("react").JSX.Element;

package/dist/components/base/navigation/navigation-tabs.d.ts

@@ -1,5 +1,5 @@
 import { ComponentProps, ReactNode } from 'react';
-import { LayoutLinkRenderer } from '../../../lib/navigation.js';
+import { LinkRenderer } from '../../../lib/navigation.js';
 import { NavigationTabsStrings } from './navigation-tabs.strings.js';
 export interface NavigationTabItem {
     label: ReactNode;
@@ -10,14 +10,20 @@ export interface NavigationTabItem {
     disabled?: boolean;
 }
 export interface NavigationTabsProps extends Omit<ComponentProps<"nav">, "children"> {
+    /** The routes: each a `label` and an `href`, with an optional `icon`, `badge` or `disabled`. */
     items: NavigationTabItem[];
     /** The current route. The active tab follows from this. */
     currentPath?: string;
     /** Routes entries through the app's router. Without it they are plain anchors. */
-    renderLink?: LayoutLinkRenderer;
+    renderLink?: LinkRenderer;
     /** `pill` draws the current route as a filled chip, as `TabList variant="pill"` does. */
     variant?: "underline" | "pill";
     /** Overrides this row's own copy — the region name. */
     strings?: Partial<NavigationTabsStrings>;
 }
+/**
+ * Tabs that navigate, so they render anchors in a `<nav>`, and the active one follows from
+ * the current path. `Tabs` and `TabPanel` are for panels in one page; this is for routes,
+ * and mixing the two is how a browser back button stops working.
+ */
 export declare function NavigationTabs({ items, currentPath, renderLink, variant, strings, className, ...props }: NavigationTabsProps): import("react").JSX.Element;

package/dist/components/base/navigation/navigation-tabs.strings.d.ts

@@ -4,6 +4,10 @@ export interface NavigationTabsStrings {
 }
 export declare const defaultNavigationTabsStrings: NavigationTabsStrings;
 export interface OverflowTabBarStrings {
+    /**
+     * Accessible name for the row.
+     * @default "Sections"
+     */
     label: string;
 }
 export declare const defaultOverflowTabBarStrings: OverflowTabBarStrings;

package/dist/components/base/navigation/overflow-tab-bar.d.ts

@@ -14,10 +14,24 @@ export interface OverflowTabItem {
     badge?: ReactNode;
 }
 export interface OverflowTabBarProps extends Omit<ComponentProps<"div">, "children" | "onChange" | "defaultValue"> {
+    /**
+     * The tabs: an `id`, a `label`, and optionally an `icon`, a `badge`, an `href`, or
+     * `disabled`. A tab with an `href` is a link; without one it is a button.
+     */
     items: OverflowTabItem[];
+    /**
+     * The active section's `id`. The bar owns no panels — the caller renders what the id
+     * selects.
+     */
     value?: string;
+    /** Called with the `id` of the section the reader picks. */
     onValueChange?: (id: string) => void;
     /** Overrides this row's own copy — the region name. */
     strings?: Partial<OverflowTabBarStrings>;
 }
+/**
+ * Tabs as data, in a row that scrolls rather than wrapping: wrapping onto a second line
+ * changes the page's height as the reader switches. Renders through `Tabs`, or through
+ * `NavigationTabs` — a `<nav>` of links — when every item has an `href`.
+ */
 export declare function OverflowTabBar({ items, value, onValueChange, strings, className, ...props }: OverflowTabBarProps): import("react").JSX.Element;

package/dist/components/base/navigation/page-heading.d.ts

@@ -13,7 +13,10 @@ export interface PageHeadingProps extends Omit<ComponentProps<"header">, "title"
     title: ReactNode;
     /** One sentence under the title, capped at a reading measure. */
     description?: ReactNode;
-    /** Heading level for a plain-text title; set it so the document outline is right. */
+    /**
+     * Heading level for a plain-text title; set it so the document outline is right. It is
+     * not the type size.
+     */
     level?: HeadingLevel;
     /** Convenience for a single badge. Ignored when `badges` is set. */
     badge?: PageHeadingBadge;
@@ -21,7 +24,7 @@ export interface PageHeadingProps extends Omit<ComponentProps<"header">, "title"
     badges?: PageHeadingBadge[];
     /** Trail above the block. */
     breadcrumbs?: ReactNode;
-    /** Left of the whole column — an avatar, a back control. Top-aligned. */
+    /** Left of the whole column — an avatar, a back control. Top-aligned; the description indents with it. */
     leading?: ReactNode;
     /** Between the eyebrow and the title row — a banner or status strip. */
     beforeTitle?: ReactNode;

package/dist/components/base/navigation/pagination.d.ts

@@ -1,37 +1,51 @@
+import { LinkRenderer } from '../../../lib/navigation.js';
 import { PaginationStrings } from './navigation.strings.js';
 /** Pagination: a window around the current page with ellipses, so the width stays constant. */
 import * as React from "react";
 export interface PaginationProps extends Omit<React.ComponentProps<"nav">, "onChange"> {
+    /** The current page, 1-indexed. */
     page: number;
+    /** Total pages. */
     total: number;
+    /** Called with the page a control goes to. */
     onPageChange: (page: number) => void;
-    /** Disables every page control, including links, while navigation is unavailable. */
+    /**
+     * Disables every page control while navigation is unavailable. Linked controls become
+     * disabled buttons until it is available again.
+     */
     disabled?: boolean;
-    /** Pages either side of the current one. */
+    /** Pages shown either side of the current one. */
     siblings?: number;
     /**
      * Whether the arrows carry their words: `icon` (chevrons only), `text` (Previous/Next),
-     * or `responsive` (the default: words from `sm` up). The words, from `strings`, are also
-     * the accessible names.
+     * or `responsive`, words from `sm` up and chevrons below — the words are what a pager
+     * under a wide table wants, and the width is what a phone has not got. The words come
+     * from `strings`, so they are the accessible names too.
      */
     labels?: "icon" | "text" | "responsive";
-    /** Drops the numbers, leaving the two arrows. For a cursor pager with no page count. */
+    /**
+     * `false` drops the numbers and leaves the two arrows alone — a cursor pager, where there
+     * is no page count to show.
+     */
     numbers?: boolean;
     /**
-     * Renders each control as the caller's own link, so pages work as `<a href>` without JS.
-     * `onPageChange` still fires. Disabled arrows stay buttons.
+     * The address of a page. With it, every control is a link: a pager is navigation, and on
+     * a server-rendered list each page should be an `<a href>` that works without JavaScript
+     * and opens in a new tab. `onPageChange` still fires. A disabled arrow stays a button,
+     * because there is no href for a page that does not exist.
      *
-     *   renderLink={(page, props) => <Link href={`?page=${page}`} {...props} />}
+     *   pageHref={(page) => `?page=${page}`}
+     */
+    pageHref?: (page: number) => string;
+    /**
+     * Renders those links through the application's router, as every component's
+     * `renderLink` does; without it, plain anchors. Only used with `pageHref`.
+     */
+    renderLink?: LinkRenderer;
+    /**
+     * Overrides this pager's own copy — the region name, the two arrows, the ellipsis, and
+     * each page control, named by the page it goes to.
      */
-    renderLink?: (page: number, props: PaginationLinkProps) => React.ReactNode;
-    /** Overrides this pager's own copy — the region, the two arrows, each page. */
     strings?: Partial<PaginationStrings>;
 }
-/** What a `renderLink` element must spread to be the control it replaces. */
-export interface PaginationLinkProps {
-    "aria-label": string;
-    "aria-current"?: "page";
-    onClick: (event: React.MouseEvent) => void;
-    children: React.ReactNode;
-}
-export declare function Pagination({ page, total, onPageChange, disabled: pagerDisabled, siblings, labels, numbers, renderLink, strings, className, ...props }: PaginationProps): React.JSX.Element;
+export declare function Pagination({ page, total, onPageChange, disabled: pagerDisabled, siblings, labels, numbers, pageHref, renderLink, strings, className, ...props }: PaginationProps): React.JSX.Element;

package/dist/components/base/navigation/pagination.range.d.ts

@@ -1,2 +1,5 @@
-/** Page numbers to render, with `null` marking a gap. Always includes the first and last page. */
+/**
+ * The page numbers a pager renders, with `null` marking a gap: the arithmetic on its own,
+ * for a custom control. Always includes the first and last page.
+ */
 export declare function paginationRange(page: number, total: number, siblings?: number): (number | null)[];

package/dist/components/base/navigation/tabs.d.ts

@@ -5,30 +5,49 @@ import { TabListStrings } from './navigation.strings.js';
  */
 import * as React from "react";
 export interface TabsProps extends Omit<React.ComponentProps<"div">, "onChange"> {
+    /** Controlled selection: the `value` of the selected tab. Pair with `onValueChange`. */
     value?: string;
+    /** The tab selected first, when uncontrolled. */
     defaultValue?: string;
+    /** Called with the `value` of the tab the reader selects. */
     onValueChange?: (value: string) => void;
 }
+/** The root: holds which tab is selected, for the list and the panels inside it. */
 export declare function Tabs({ value, defaultValue, onValueChange, className, children, ...props }: TabsProps): React.JSX.Element;
 export interface TabListProps extends React.ComponentProps<"div"> {
     /**
-     * Structural presentation: a rule with an indicator, a tinted rail, or — for a row that
-     * picks what one list shows rather than switching panels — filled chips with no rule.
+     * Structural presentation: a rule with an indicator, a tinted rail, or filled chips with
+     * no rule. `pill` is for a row that picks what one list shows rather than switching
+     * panels — saved views, result types — and is what OverflowTabBar draws.
      */
     variant?: "underline" | "enclosed" | "pill";
     /** Accessible name for the tab set. */
     label?: string;
-    /** Fade edges with hidden tabs. Defaults to false; follows scroll position and direction. */
+    /**
+     * Fades only the edges that have hidden tabs beyond them. Updates while scrolling and
+     * follows the writing direction, so it works in RTL.
+     */
     edgeFade?: boolean;
-    /** Accessible names for the automatic overflow scroll controls. */
+    /**
+     * Accessible names for the previous and next scroll controls that appear when the tabs
+     * overflow.
+     */
     strings?: Partial<TabListStrings>;
 }
+/**
+ * The row of tabs. It scrolls rather than wrapping, because a second row of tabs reads as a
+ * second level of navigation, which it is not.
+ */
 export declare function TabList({ variant, label, edgeFade, strings, className, children, ref, onKeyDown: onKeyDownProp, onScroll, id, ...props }: TabListProps): React.JSX.Element;
 export interface TabProps extends Omit<React.ComponentProps<"button">, "value"> {
+    /** Names the tab: the value `Tabs` selects, and the one its `TabPanel` shares. */
     value: string;
 }
+/** One tab. Only the selected tab is in the tab sequence; the arrows move between the rest. */
 export declare function Tab({ value, className, onClick, ...props }: TabProps): React.JSX.Element;
 export interface TabPanelProps extends React.ComponentProps<"div"> {
+    /** Which tab the panel belongs to: that tab's `value`. */
     value: string;
 }
+/** The content for one tab, rendered while that tab is selected. */
 export declare function TabPanel({ value, className, children, ...props }: TabPanelProps): React.JSX.Element | null;