themelia-ui 2.0.1 → 3.1.0

package/dist/components/layout/navigation/section-nav.d.ts

@@ -13,6 +13,7 @@ export interface SectionNavItem {
     depth?: number;
 }
 export interface SectionNavProps extends Omit<React.ComponentProps<"nav">, "children" | "onSelect"> {
+    /** The headings: an id, a label, and an optional depth for nesting. */
     items: SectionNavItem[];
     /**
      * Which part of the viewport counts as "here". The default makes a heading current once

package/dist/components/layout/navigation/side-nav.d.ts

@@ -1,4 +1,5 @@
 import { LucideIcon } from 'lucide-react';
+import { LinkRenderer } from '../../../lib/navigation.js';
 import { StringsProp } from '../../../lib/strings.js';
 import { SideNavStrings } from './navigation.strings.js';
 import * as React from "react";
@@ -26,24 +27,22 @@ export interface SideNavGroup {
 export interface SideNavProps extends Omit<React.ComponentProps<"nav">, "children"> {
     /** Flat entries. Mutually exclusive with `groups`. */
     items?: SideNavItem[];
-    /** Captioned blocks of entries. Mutually exclusive with `items`. */
+    /**
+     * Captioned blocks of entries, each of which can be collapsible. Mutually exclusive with
+     * `items`.
+     */
     groups?: SideNavGroup[];
     /**
-     * The path considered current. Matched by longest prefix, so `/settings/members` marks
-     * the members entry, not the `/settings` index.
+     * The path considered current. Matched by longest prefix, so exactly one entry is
+     * current: `/settings/members` marks the members entry, not the `/settings` index.
      */
     currentPath?: string;
     /**
-     * Renders each entry: receives the link props and returns the router's link element.
-     * Without it, entries are plain anchors.
+     * Routes entries through the app's router, as every component's `renderLink` does.
+     * Without it, entries are plain anchors — the kit never imports a router.
      */
-    renderLink?: (props: {
-        href: string;
-        className: string;
-        children: React.ReactNode;
-        "aria-current"?: "page";
-        "aria-disabled"?: boolean;
-    }) => React.ReactElement;
+    renderLink?: LinkRenderer;
+    /** Overrides the rail's own copy — the collapse control's name. */
     strings?: StringsProp<SideNavStrings>;
 }
 export declare function SideNav({ items, groups, currentPath, renderLink, strings, className, ...props }: SideNavProps): React.JSX.Element;

package/dist/components/layout/page/index.d.ts

@@ -3,3 +3,4 @@ export { PageHeader, type PageHeaderProps, type PageHeaderSlots } from './page-h
 export { PageActions, type PageActionsProps, type PageAction, type PageActionsDisplay, } from './page-actions.js';
 export { defaultPageHeaderStrings, type PageHeaderStrings } from './page-header.strings.js';
 export { defaultPageActionsStrings, type PageActionsStrings } from './page-actions.strings.js';
+export type { LinkRenderer, LinkRenderProps } from '../../../lib/navigation.js';

package/dist/components/layout/page/page-actions.d.ts

@@ -11,13 +11,17 @@ export interface PageAction extends ActionDefinition {
     placement?: ActionPlacement;
 }
 export interface PageActionsProps extends LayoutNavigationAdapter {
+    /** The entries: `ActionDefinition` data plus a `placement`. */
     actions?: readonly PageAction[];
     /**
      * `auto` watches the width and collapses everything into a menu below `breakpoint`;
      * `inline` and `menu` are the two fixed ends.
      */
     display?: PageActionsDisplay;
-    /** Viewport width, in px, below which `auto` collapses to a menu. Defaults to the `lg` breakpoint. */
+    /**
+     * Viewport width, in px, below which `auto` collapses to a menu. Defaults to the `lg`
+     * breakpoint, 1024px.
+     */
     breakpoint?: number;
     /** How many entries render as buttons before the rest overflow. */
     maxInlineActions?: number;

package/dist/components/layout/page/page-header.d.ts

@@ -14,7 +14,10 @@ export interface PageHeaderSlots {
 }
 export interface PageHeaderProps extends LayoutNavigationAdapter, Pick<PageHeadingProps, "eyebrow" | "description" | "level" | "breadcrumbs" | "withSeparator" | "className"> {
     title: ReactNode;
-    /** Decorative glyph before the title. Centred on the title line, never on the block. */
+    /**
+     * Glyph before the title, centred on the title line, never on the block. Decorative by
+     * default; `titleIconHref` or `onTitleIconClick` makes it a control with a name.
+     */
     titleIcon?: ComponentType<{
         className?: string;
     }>;
@@ -24,12 +27,24 @@ export interface PageHeaderProps extends LayoutNavigationAdapter, Pick<PageHeadi
     onTitleIconClick?: () => void;
     /** Overrides this header's own copy: the back control's and the title icon's accessible names. */
     strings?: Partial<PageHeaderStrings>;
-    /** Destination for the back control. Either this or `onBack` makes it appear. */
+    /**
+     * Destination for the back control, which is then a real link routed through
+     * `renderLink` — middle-clickable, and openable in a new tab. Either this or `onBack`
+     * makes it appear.
+     */
     backHref?: string;
+    /**
+     * Makes the back control a button, which wins over `backHref`. Either this or `backHref`
+     * makes it appear.
+     */
     onBack?: () => void;
-    /** Status marks beside the title, as data — the tone comes from the kit's vocabulary. */
+    /**
+     * Status marks beside the title, as data, passed through to the heading — the tone comes
+     * from the kit's vocabulary.
+     */
     titleBadges?: PageHeadingBadge[];
     actions?: ReactNode;
+    /** Replaces a structural region without forking the header. */
     slots?: PageHeaderSlots;
     children?: ReactNode;
 }

package/dist/components/layout/page/page.d.ts

@@ -8,7 +8,9 @@ import * as React from "react";
 export interface PageProps extends Omit<React.ComponentProps<"div">, "title"> {
     /** The title block, as `PageHeader` props. Omit for a page that supplies its own header. */
     header?: PageHeaderProps;
+    /** The reading measure, handed to the Container underneath. */
     maxWidth?: ContainerMaxWidth;
+    /** The inline gutter, handed to the Container underneath. */
     gutter?: ContainerGutter;
     /** Attributes for the body region, for a page that needs to address it. */
     bodyProps?: React.ComponentProps<"div">;

package/dist/components/layout/settings/index.d.ts

@@ -1,2 +1,3 @@
 export { AsideNavShell, type AsideNavShellProps } from './settings.js';
 export type { SideNavGroup as AsideNavGroup, SideNavItem as AsideNavItem } from '../navigation/index.js';
+export type { LinkRenderer, LinkRenderProps } from '../../../lib/navigation.js';

package/dist/components/layout/settings/settings.d.ts

@@ -1,4 +1,5 @@
-import { SideNav, SideNavGroup, SideNavItem } from '../navigation/index.js';
+import { LinkRenderer } from '../../../lib/navigation.js';
+import { SideNavGroup, SideNavItem } from '../navigation/index.js';
 /**
  * AsideNavShell: a section with its own navigation beside the content (settings, an
  * account area, docs). Composes TwoColumnLayout and SideNav: nav on the start side, a
@@ -6,18 +7,29 @@ import { SideNav, SideNavGroup, SideNavItem } from '../navigation/index.js';
  */
 import * as React from "react";
 export interface AsideNavShellProps extends Omit<React.ComponentProps<"div">, "title"> {
+    /** The section heading, above both columns. */
     title?: React.ReactNode;
+    /** A line under the title, in the section heading above both columns. */
     description?: React.ReactNode;
-    /** Flat entries, or captioned groups. Passed straight to SideNav. */
+    /**
+     * Flat entries, passed straight to the SideNav the shell draws — the same entries,
+     * current-path matching and router hook as SideNav's own.
+     */
     items?: SideNavItem[];
+    /** Captioned groups of entries, passed straight to the SideNav. */
     groups?: SideNavGroup[];
-    /** The path considered current. Matched by longest prefix. */
+    /** The current path, passed straight to the SideNav. Matched by longest prefix. */
     currentPath?: string;
     /** Replaces the built-in SideNav entirely. */
     aside?: React.ReactNode;
-    renderLink?: React.ComponentProps<typeof SideNav>["renderLink"];
+    /** The router hook, passed straight to the SideNav. */
+    renderLink?: LinkRenderer;
     /** Actions for the heading row. */
     actions?: React.ReactNode;
+    /**
+     * Keeps the rail in view while the content scrolls. A settings rail is short and the
+     * content beside it usually is not.
+     */
     stickyAside?: boolean;
 }
 export declare function AsideNavShell({ title, description, items, groups, currentPath, aside, renderLink, actions, stickyAside, className, children, ...props }: AsideNavShellProps): React.JSX.Element;

package/dist/components/layout/sidebar/app-sidebar.d.ts

@@ -5,17 +5,23 @@ import { WorkspaceLink } from './partials/sidebar-workspace.js';
 import { SidebarUserStrings, SidebarWorkspaceStrings } from './sidebar.strings.js';
 import { SidebarFlatNavItem, SidebarItemContext, SidebarNavItem } from './nav.types.js';
 export interface AppSidebarProps extends LayoutNavigationAdapter {
-    /** Navigation grouped by section heading. An empty key renders an untitled group. */
+    /**
+     * Navigation as data, grouped by section heading. An empty key renders an untitled group,
+     * and an item with children renders as a disclosure.
+     */
     navigationGroups?: Record<string, SidebarNavItem[]>;
     /** Entries pinned to the footer — support, settings, sign out. */
     footerNavItems?: SidebarFlatNavItem[];
-    /** The current route. Everything active follows from this. */
+    /** The current route. Active rows, and which parent is expanded, follow from this alone. */
     currentUrl?: string;
     /** Resolves an icon name to a component, so navigation data can stay serialisable. */
     iconMap?: Record<string, ComponentType<{
         className?: string;
     }>>;
-    /** Counts keyed by `handle`, for values that change after the nav was defined. */
+    /**
+     * Counts keyed by `handle`, overriding an item's declared badge — for a number that
+     * changes after the nav was defined.
+     */
     liveBadges?: Record<string, string | number>;
     loading?: boolean;
     /** Rows shown while loading. */
@@ -50,7 +56,9 @@ export interface AppSidebarProps extends LayoutNavigationAdapter {
 }
 /**
  * Resolves an icon that may be a name (looked up in `iconMap`), a component or a node.
- * Exported for `renderItem` callers.
+ * Exported because a caller supplying `renderItem` still wants the same resolution — a row
+ * rendered by hand should not need its own copy of “string means look it up, component
+ * means render it, node means use it”.
  */
 export declare function SidebarIcon({ icon, iconMap, }: {
     icon?: LayoutIconSource;

package/dist/components/layout/sidebar/index.d.ts

@@ -4,4 +4,4 @@ export { SidebarWorkspace, type SidebarWorkspaceProps, type WorkspaceLink, } fro
 export { SidebarUser, type SidebarUserProps } from './partials/sidebar-user.js';
 export { defaultSidebarWorkspaceStrings, defaultSidebarUserStrings, type SidebarWorkspaceStrings, type SidebarUserStrings, } from './sidebar.strings.js';
 export type { SidebarFlatNavItem, SidebarItemContext, SidebarNavItem, } from './nav.types.js';
-export { isPathMatch, resolveActiveHref, toPath } from '../../../lib/navigation.js';
+export { isPathMatch, resolveActiveHref, toPath, type LinkRenderer, type LinkRenderProps, } from '../../../lib/navigation.js';

package/dist/components/layout/sidebar/nav.types.d.ts

@@ -1,5 +1,6 @@
 import { ReactNode } from 'react';
-import { LayoutIconSource, LayoutLinkRenderer } from '../layout.types.js';
+import { LinkRenderer } from '../../../lib/navigation.js';
+import { LayoutIconSource } from '../layout.types.js';
 export interface SidebarNavItem {
     label: ReactNode;
     href?: string;
@@ -19,7 +20,7 @@ export interface SidebarItemContext {
     /** Whether the row's children are shown: the reader's toggle if they used it, else derived from the current URL. */
     expanded: boolean;
     badge?: string | number;
-    renderLink: LayoutLinkRenderer;
+    renderLink: LinkRenderer;
     /**
      * Flips `expanded` for a row with children; wire it to a custom parent row's click.
      * AppSidebar always supplies it; optional for hand-built contexts.

package/dist/components/layout/sidebar/partials/sidebar-logo.d.ts

@@ -6,4 +6,9 @@ export interface SidebarLogoProps {
     collapsedLogo?: ReactNode;
     className?: string;
 }
+/**
+ * The product mark in the rail’s header. It swaps to the compact mark when the rail
+ * collapses to icons rather than scaling the full one down, because a squeezed wordmark is
+ * unreadable at rail width.
+ */
 export declare function SidebarLogo({ logo, collapsedLogo, className }: SidebarLogoProps): import("react").JSX.Element | null;

package/dist/components/layout/sidebar/partials/sidebar-user.d.ts

@@ -12,4 +12,9 @@ export interface SidebarUserProps {
     /** Replaces the row's content, keeping the button and the menu. */
     renderTrigger?: (user: LayoutUser) => ReactNode;
 }
+/**
+ * The account row at the foot of the rail. Its menu opens to the RIGHT when the rail is
+ * collapsed and ABOVE when it is not, because a menu that always drops down is off-screen at
+ * the bottom of a full-height panel.
+ */
 export declare function SidebarUser({ user, customContent, onProfile, onSettings, onLogout, strings, renderTrigger, }: SidebarUserProps): import("react").JSX.Element;

package/dist/components/layout/sidebar/partials/sidebar-workspace.d.ts

@@ -16,4 +16,8 @@ export interface SidebarWorkspaceProps extends LayoutNavigationAdapter {
     strings?: Partial<SidebarWorkspaceStrings>;
     contentClassName?: string;
 }
+/**
+ * The rail’s header as a workspace switcher. The whole header row is the trigger, not a
+ * chevron beside a decorative name — the name is what a reader aims at.
+ */
 export declare function SidebarWorkspace({ logo, collapsedLogo, workspaceLinks, renderLink, strings, contentClassName, }: SidebarWorkspaceProps): import("react").JSX.Element;

package/dist/components/layout/workspace/index.d.ts

@@ -3,3 +3,4 @@ export { WorkspaceLayout, type WorkspaceLayoutProps, type WorkspaceContentWidth,
 export { WorkspaceNav, type WorkspaceNavProps, type WorkspaceNavItem, type WorkspaceNavGroup, type WorkspaceNavStatus, type WorkspaceNavRenderContext, } from './workspace-nav.js';
 export { WorkspaceLocaleStrip, type WorkspaceLocaleStripProps, type WorkspaceLocaleItem, } from './workspace-locale-strip.js';
 export { defaultWorkspaceNavStrings, defaultWorkspaceLocaleStripStrings, defaultWorkspaceRecordHeaderStrings, type WorkspaceNavStrings, type WorkspaceLocaleStripStrings, type WorkspaceRecordHeaderStrings, } from './workspace.strings.js';
+export type { LinkRenderer, LinkRenderProps } from '../../../lib/navigation.js';

package/dist/components/layout/workspace/workspace-layout.d.ts

@@ -25,4 +25,9 @@ export interface WorkspaceLayoutProps extends Omit<ComponentProps<"div">, "child
     contentRender?: useRender.ComponentProps<"main">["render"];
     railClassName?: string;
 }
+/**
+ * The frame a single RECORD is edited in. Not an app shell — it sits inside one: a record
+ * with many sections needs its own navigation, and nesting a second shell is how a page ends
+ * up with two sidebars.
+ */
 export declare function WorkspaceLayout({ header, sidebar, rail, children, contentWidth, label, sidebarWidth, railWidth, className, headerClassName, bodyClassName, sidebarClassName, contentClassName, contentRender, railClassName, style, ...props }: WorkspaceLayoutProps): import("react").JSX.Element;

package/dist/components/layout/workspace/workspace-locale-strip.d.ts

@@ -18,4 +18,9 @@ export interface WorkspaceLocaleStripProps extends Omit<ComponentProps<"div">, "
     actions?: ReactNode;
     strings?: Partial<WorkspaceLocaleStripStrings>;
 }
+/**
+ * The languages a record exists in, and how complete each is. A strip rather than a
+ * select, because the completeness is the reason to switch and a select hides it behind a
+ * press.
+ */
 export declare function WorkspaceLocaleStrip({ locales, activeLocale, onLocaleChange, actions, strings, className, ...props }: WorkspaceLocaleStripProps): import("react").JSX.Element;

package/dist/components/layout/workspace/workspace-nav.d.ts

@@ -39,4 +39,9 @@ export interface WorkspaceNavProps extends Omit<ComponentProps<"nav">, "onSelect
     footerSlot?: ReactNode;
     strings?: Partial<WorkspaceNavStrings>;
 }
+/**
+ * Navigation for a record filled in over time. The difference from every other nav in the
+ * kit is COMPLETION: each section reports how much of it is done, because that is what
+ * decides where the reader goes next.
+ */
 export declare function WorkspaceNav({ groups, activeId, onSelect, renderItem, renderLink, footerSlot, strings, className, ...props }: WorkspaceNavProps): import("react").JSX.Element;

package/dist/components/layout/workspace/workspace.d.ts

@@ -11,7 +11,9 @@ export interface WorkspaceRecordMetadataItem {
     value: React.ReactNode;
 }
 export interface WorkspaceRecordHeaderProps extends Omit<React.ComponentProps<"div">, "title"> {
+    /** What the record IS. Gives way before the badges do. */
     title: React.ReactNode;
+    /** One line under the title. */
     description?: React.ReactNode;
     /** An avatar, an icon medallion, a thumbnail. */
     media?: React.ReactNode;
@@ -19,7 +21,10 @@ export interface WorkspaceRecordHeaderProps extends Omit<React.ComponentProps<"d
     badges?: React.ReactNode;
     /** A single prominent status, rendered after the badges. */
     status?: React.ReactNode;
-    /** Key/value pairs, drawn inline: each label and its value are one item, read as one fact. */
+    /**
+     * Key/value pairs, drawn as an inline MetadataList: each label and its value are one item,
+     * read as one fact, with a middle dot between items.
+     */
     metadata?: WorkspaceRecordMetadataItem[];
     /** Overrides this header's own copy — the names of its two unlabelled regions. */
     strings?: Partial<WorkspaceRecordHeaderStrings>;
@@ -27,6 +32,7 @@ export interface WorkspaceRecordHeaderProps extends Omit<React.ComponentProps<"d
     actions?: React.ReactNode;
     /** A second, quieter row beneath — filters, tabs, bulk controls. */
     secondaryActions?: React.ReactNode;
+    /** The heading element, for the document outline. */
     headingLevel?: 1 | 2 | 3;
 }
 export declare function WorkspaceRecordHeader({ title, description, media, badges, status, metadata, actions, strings, secondaryActions, headingLevel, className, children, ...props }: WorkspaceRecordHeaderProps): React.JSX.Element;

package/dist/components/primitives/address.d.ts

@@ -2,15 +2,20 @@ import { ComponentPropsWithoutRef, ReactNode, Ref } from 'react';
 import { ValueProps } from './value.js';
 import { AddressOrder, AddressParts } from './address.format.js';
 export interface AddressProps extends Omit<ComponentPropsWithoutRef<"address">, "children" | "color"> {
-    /** The address, as fields. Anything empty simply drops out. */
+    /**
+     * The address, as fields — line1, line2, city, region, postalCode, country. Anything
+     * empty simply drops out.
+     */
     value?: AddressParts | null;
     /**
-     * `block` is the envelope form across several lines; `inline` is one line for a cell.
+     * `block` is the envelope form: an `<address>` element with a line per row. `inline` is
+     * one line, in a span, for a cell or a summary.
      */
     format?: "block" | "inline";
     /**
      * An ISO country code deciding the line order (`US`, `GB`, `DE`). Read from
-     * `value.country` when that is a code; never inferred from the reader's locale.
+     * `value.country` when that is a code; never inferred from the reader's locale — the
+     * locale is a language and the address is a place.
      */
     countryCode?: string | null;
     /** Overrides the ordering outright, for a country the kit does not know. */

package/dist/components/primitives/address.format.d.ts

@@ -40,8 +40,9 @@ export interface FormatAddressOptions {
     locale?: string;
 }
 /**
- * Returns the address as lines, each already joined. Empty fields drop out, and a line
- * left with nothing drops with them, so a missing `line2` never leaves a blank row.
+ * The same ordering outside React: the address as lines, each already joined. Empty fields
+ * drop out, and a line left with nothing drops with them, so a missing `line2` never leaves
+ * a blank row.
  */
 export declare function formatAddressLines(parts: AddressParts, { countryCode, order, separator, locale }?: FormatAddressOptions): string[];
 /** The same address on one line, for a cell or a summary row. */

package/dist/components/primitives/coordinates.d.ts

@@ -2,18 +2,32 @@ import { ReactNode, Ref } from 'react';
 import { SpanProps, ValueProps } from './value.js';
 import { CoordinatesStrings } from './primitives.strings.js';
 export interface CoordinatesProps extends SpanProps {
+    /**
+     * Signed decimal degrees. Either one missing renders the empty label — half a coordinate
+     * locates nothing.
+     */
     latitude?: number | null;
+    /**
+     * Signed decimal degrees. Either one missing renders the empty label — half a coordinate
+     * locates nothing.
+     */
     longitude?: number | null;
-    /** `decimal` is "48.85837, 2.29448"; `dms` is "48°51'30.1\"N 2°17'40.1\"E". */
+    /**
+     * `decimal` is `48.85837, 2.29448`: what an API round-trips and what a reader pastes into
+     * a map. `dms` is `48°51'30.1"N 2°17'40.1"E`, still what marine, aviation and survey
+     * users read.
+     */
     format?: "decimal" | "dms";
-    /** Decimal places in `decimal` form. Five is about a metre. */
+    /** Decimal places in `decimal` form. Five is about a metre, three about a building. */
     precision?: number;
     /**
-     * Adds hemisphere letters to the decimal form: "48.85837°N, 2.29448°E". Off by default
-     * (a signed pair pastes into a map); `dms` always shows them.
+     * Adds hemisphere letters (N/S/E/W) to the decimal form: "48.85837°N, 2.29448°E". Off by
+     * default because a signed pair is the portable form, the one that pastes into a map.
+     * `dms` always shows them — an unsigned DMS value is ambiguous.
      */
     showHemisphere?: boolean;
     locale?: string;
+    /** The four hemisphere letters. */
     strings?: Partial<CoordinatesStrings>;
     emptyLabel?: ReactNode;
     size?: ValueProps["size"];

package/dist/components/primitives/date.d.ts

@@ -3,8 +3,16 @@ import { SpanProps, ValueProps } from './value.js';
 import { DateInput } from './date.format.js';
 /** What DatePrimitive, Time, and DateTime all take. Three components, one shape. */
 export interface DateBaseProps extends SpanProps {
+    /**
+     * The moment to show: whatever the API returned — a Date, an ISO string or an epoch
+     * number. Parsed once, here.
+     */
     value?: DateInput;
-    /** date-fns pattern. Falls back to the scope's `dateFormat`. */
+    /**
+     * A date-fns pattern, when the default is not what this column needs. `DatePrimitive`
+     * falls back to the scope's `dates.format`, `Time` to its `dates.timeFormat`, and
+     * `DateTime` to the two joined.
+     */
     pattern?: string;
     emptyLabel?: ReactNode;
     size?: ValueProps["size"];
@@ -13,12 +21,40 @@ export interface DateBaseProps extends SpanProps {
     type?: ValueProps["type"];
     ref?: Ref<HTMLSpanElement>;
 }
+/**
+ * A date in the scope's pattern. Also exported as `Date`, its natural name: `DatePrimitive`
+ * exists because `Date` collides with the global in a file that also constructs one, so
+ * import whichever reads better at the call site.
+ */
 export declare function DatePrimitive({ value, pattern, ...props }: DateBaseProps): import("react").JSX.Element;
+/**
+ * The same value as a time of day. Three components rather than a granularity prop, because
+ * a column shows one of them and never switches.
+ */
 export declare function Time({ value, pattern, ...props }: DateBaseProps): import("react").JSX.Element;
+/**
+ * The same value as a date and a time. Three components rather than a granularity prop,
+ * because a column shows one of them and never switches.
+ */
 export declare function DateTime({ value, pattern, ...props }: DateBaseProps): import("react").JSX.Element;
 export interface DateRangeProps extends Omit<DateBaseProps, "value"> {
+    /**
+     * Where the range begins. Either end may be absent — an open range is a real state, not
+     * an error.
+     */
     start?: DateInput;
+    /**
+     * Where the range ends. Either end may be absent — an open range is a real state, not an
+     * error.
+     */
     end?: DateInput;
+    /**
+     * A date-fns pattern for both ends, when the collapsing is not wanted: only the default
+     * drops a repeated month.
+     * @default "d MMM yyyy"
+     */
+    pattern?: string;
+    /** Between the two ends. An en dash by default. */
     separator?: string;
 }
 export declare function DateRange({ start, end, pattern, separator, ...props }: DateRangeProps): import("react").JSX.Element;
@@ -37,11 +73,16 @@ export interface RelativeTimeProps extends Omit<DateBaseProps, "pattern"> {
      * row of dates reads as a length rather than a moment.
      */
     addSuffix?: boolean;
-    /** Distinguishes "less than a minute" from "30 seconds". */
+    /**
+     * Distinguishes "less than a minute" from "30 seconds". Only worth it for a feed measured
+     * in seconds.
+     */
     includeSeconds?: boolean;
     /**
      * Replaces the wording for this one value. Falls back to the scope's
-     * `dates.formatRelativeTime`, and then to date-fns.
+     * `dates.formatRelativeTime`, and then to date-fns, whose built-in wording the scope's
+     * `dates.locale` translates: a date-fns locale OBJECT, since the locales are modules and
+     * cannot be looked up from a BCP-47 tag without putting every language in every bundle.
      */
     formatRelativeTime?: (date: Date, now: Date) => string;
 }

package/dist/components/primitives/date.format.d.ts

@@ -6,10 +6,13 @@ export interface FormatDateRangeOptions {
     /** date-fns locale object. The React component reads it from the scope for you. */
     locale?: Locale;
 }
-/** Returns undefined rather than an Invalid Date, so the empty state renders instead. */
+/**
+ * The single parse every date primitive goes through. Returns undefined rather than an
+ * Invalid Date, so the empty state renders instead.
+ */
 export declare function parseDateInput(value: DateInput): Date | undefined;
 /**
- * Collapses a range to its distinct parts: same day renders once, and a range within one
- * month drops the repeated month from the start date.
+ * The same collapsing outside React: a range reduced to its distinct parts. The same day
+ * renders once, and a range within one month drops the repeated month from the start date.
  */
 export declare function formatDateRange(start: DateInput, end: DateInput, { pattern, separator, locale }?: FormatDateRangeOptions): string | undefined;

package/dist/components/primitives/dimensions.d.ts

@@ -2,10 +2,15 @@ import { ReactNode, Ref } from 'react';
 import { SpanProps, ValueProps } from './value.js';
 import { DimensionPart } from './dimensions.format.js';
 export interface DimensionsProps extends SpanProps {
+    /** The first part. The parts stay separate numbers until the render joins them. */
     width?: DimensionPart;
+    /** The second part. */
     height?: DimensionPart;
+    /** The third part, optional — two values render as a plane. */
     depth?: DimensionPart;
+    /** Appended once, not per part. */
     unit?: ReactNode;
+    /** Between the parts. A multiplication sign, not the letter x. */
     separator?: ReactNode;
     locale?: string;
     options?: Intl.NumberFormatOptions;

package/dist/components/primitives/dimensions.format.d.ts

@@ -6,4 +6,5 @@ export interface FormatDimensionsOptions {
     locale?: string;
     options?: Intl.NumberFormatOptions;
 }
+/** The same joining outside React. */
 export declare function formatDimensions(width: DimensionPart, height: DimensionPart, { depth, unit, separator, locale, options }?: FormatDimensionsOptions): string | undefined;

package/dist/components/primitives/duration.d.ts

@@ -2,12 +2,17 @@ import { ReactNode, Ref } from 'react';
 import { DurationUnit, DurationUnitDisplay } from '../../lib/format.js';
 import { SpanProps, ValueProps } from './value.js';
 export interface DurationProps extends SpanProps {
+    /** The length. Seconds unless `from` says otherwise. */
     value?: number | null;
     /** The unit the incoming value is in. */
     from?: DurationUnit;
     locale?: string;
-    /** How many units to show before truncating. */
+    /**
+     * How many units to show before truncating. "2 hours 14 minutes 3 seconds" is rarely
+     * useful — the reader wants the magnitude, and the tail is noise.
+     */
     maxParts?: number;
+    /** How each unit is written. */
     unitDisplay?: DurationUnitDisplay;
     minimumFractionDigits?: number;
     maximumFractionDigits?: number;

package/dist/components/primitives/file-size.d.ts

@@ -2,13 +2,30 @@ import { ReactNode, Ref } from 'react';
 import { SpanProps, ValueProps } from './value.js';
 import { FileSizeBase, FileSizeUnit } from './file-size.format.js';
 export interface FileSizeProps extends SpanProps {
+    /** The size. Bytes unless `from` says otherwise. */
     value?: number | null;
+    /**
+     * The unit `value` is given in. Converted with the same base, so `from="megabytes"` means
+     * 2^20 under `binary` and 10^6 under `decimal`.
+     */
     from?: FileSizeUnit;
-    /** `binary` (default), `decimal`, or `iec`. See file-size.format.ts. */
+    /**
+     * Which base and which labels. `binary` divides by 1024 and labels it MB — the pairing
+     * Windows and most file managers show, chosen so a size agrees with the machine it
+     * describes rather than with SI. `decimal` is SI-correct and what Apple platforms and
+     * storage vendors use. `iec` is strictly correct. The default does not move, so nothing
+     * already shipped changes.
+     * @default "binary"
+     */
     base?: FileSizeBase;
     locale?: string;
     emptyLabel?: ReactNode;
     size?: ValueProps["size"];
+    /**
+     * For a size given a box of its own. A COLUMN of sizes is aligned by the column —
+     * `<TableCell align="end">` — because the primitive is a span, and blockifying it to
+     * align would break the text runs it also sits in.
+     */
     align?: ValueProps["align"];
     weight?: ValueProps["weight"];
     type?: ValueProps["type"];

package/dist/components/primitives/file-size.format.d.ts

@@ -7,4 +7,5 @@ export interface FileSizeFormatOptions {
     base?: FileSizeBase;
     locale?: string;
 }
+/** The same formatting outside React. */
 export declare function formatFileSize(value: number, { from, base, locale }?: FileSizeFormatOptions): string;

package/dist/components/primitives/initials-format.d.ts

@@ -11,7 +11,8 @@ export interface InitialsFormatOptions {
     fallback?: string;
 }
 /**
- * Derive short, Unicode-aware initials from a person or resource name.
+ * The same derivation outside React: short, Unicode-aware initials from a person or
+ * resource name.
  *
  * `first-last` is the identity default (`Mary Jane Smith` → `MS`). Use
  * `first-words` for admin surfaces that intentionally use the first

package/dist/components/primitives/initials.d.ts

@@ -4,8 +4,15 @@ import { InitialsMaxCharacters, InitialsStrategy } from './initials-format.js';
 export interface InitialsProps extends Omit<ValueProps, "children"> {
     /** Person, organisation, or resource name to derive initials from. */
     value?: string | null;
-    /** First + last word by default; `first-words` keeps the leading N words instead. */
+    /**
+     * First + last word by default; `first-words` keeps the leading N words instead.
+     * @default "first-last"
+     */
     strategy?: InitialsStrategy;
+    /**
+     * How many characters are kept.
+     * @default 2
+     */
     maxCharacters?: InitialsMaxCharacters;
     locale?: string;
     /** Returned when no usable letter or number exists. */