themelia-ui 2.0.0 → 3.0.0

package/dist/components/features/schema-form/schema-form-field.d.ts

@@ -4,4 +4,9 @@ export interface SchemaFormFieldRendererProps extends SchemaFormFieldContext {
     strings: SchemaFormStrings;
     className?: string;
 }
+/**
+ * One field, resolved from its schema entry to a control, with FormField owning the label, hint
+ * and message. Reach for it when a form is mostly generated but one field needs to be placed by
+ * hand.
+ */
 export declare function SchemaFormFieldRenderer({ field, value, values, error, disabled, required, fieldId, onValueChange, onError, strings, className, }: SchemaFormFieldRendererProps): import("react").JSX.Element;

package/dist/components/features/schema-form/schema-form.d.ts

@@ -1,2 +1,6 @@
 import { SchemaFormProps } from './schema-form.types.js';
+/**
+ * Renders and validates a form described as data. `validate()` runs on submit, and a message
+ * clears as soon as its field changes.
+ */
 export declare function SchemaForm({ schema, value, defaultValue, errors, disabled, layout, columns, id, name, title, description, headerSlot, footerSlot, actionsSlot, emptySlot, showActions, submitLabel, resetLabel, submitDisabled, resetDisabled, submitting, onValueChange, onFieldChange, onSubmit, onReset, onError, renderField, renderSection, strings, className, contentClassName, sectionClassName, fieldClassName, }: SchemaFormProps): import("react").JSX.Element;

package/dist/components/features/schema-form/schema-form.types.d.ts

@@ -23,8 +23,10 @@ export interface SchemaFormOption {
 }
 /** Returns a message to fail, or anything else to pass. */
 export type SchemaFormValidator = (value: SchemaFormValue, values: SchemaFormValues, field: SchemaFormField) => true | string | null | undefined;
+/** The keys every field shares, whatever its `type`. */
 export interface SchemaFormFieldBase {
     key: string;
+    /** Picks the control. Omitted means `text`. */
     type?: SchemaFormFieldType;
     label: string;
     description?: string;
@@ -32,21 +34,42 @@ export interface SchemaFormFieldBase {
     helperText?: string;
     placeholder?: string;
     required?: boolean;
-    /** A function form, for a field only editable once a sibling says so. */
+    /**
+     * The predicate form reads the whole value set, for a field only editable once a sibling
+     * says so.
+     */
     disabled?: boolean | ((values: SchemaFormValues) => boolean);
-    /** A hidden field is not rendered AND not validated. */
+    /**
+     * A hidden field is not rendered AND not validated — blocking a submit on a required field
+     * the reader cannot see is a dead end. The predicate form reads the whole value set, for a
+     * field that only matters once a sibling says so.
+     */
     hidden?: boolean | ((values: SchemaFormValues) => boolean);
     defaultValue?: SchemaFormValue;
     /** Puts the field in a section without listing it there. */
     sectionId?: string;
+    /**
+     * Column span inside the section grid, which is keyed to a container. A form in a 320px
+     * drawer collapses to one column whatever the section asked for.
+     */
     width?: SchemaFormFieldWidth;
     className?: string;
     /** Merged onto the control rather than the field wrapper. */
     controlClassName?: string;
+    /**
+     * Return a string to fail. The first message wins: the rest are about a value already known
+     * to be wrong.
+     */
     validate?: SchemaFormValidator | SchemaFormValidator[];
-    /** Turns the stored value into what the control displays. */
+    /**
+     * Turns the stored value into what the control displays: with `parseValue`, the two halves
+     * of a custom representation.
+     */
     formatValue?: (value: SchemaFormValue, values: SchemaFormValues) => string;
-    /** Turns what the control produced back into the stored value. */
+    /**
+     * Turns what the control produced back into the stored value: with `formatValue`, the two
+     * halves of a custom representation.
+     */
     parseValue?: (value: string, values: SchemaFormValues) => SchemaFormValue;
     /** Free-form payload, carried through to `renderField`. */
     meta?: Record<string, unknown>;
@@ -173,12 +196,28 @@ export interface SchemaFormSubmitHelpers {
     validate: () => boolean;
 }
 export interface SchemaFormProps {
+    /**
+     * Sections and fields. A section names its fields explicitly or claims the ones carrying its
+     * `sectionId`; whatever no section claimed lands in a leading default bucket.
+     */
     schema: SchemaFormSchema;
+    /**
+     * Controlled values. Under a controlled value the schema's own defaults still apply, so a
+     * consumer holding two fields does not blank the rest.
+     */
     value?: SchemaFormValues;
+    /** Uncontrolled starting values. An explicit default outranks the schema's own. */
     defaultValue?: SchemaFormValues;
-    /** Server-side messages, keyed by field. Merged over the form's own. */
+    /**
+     * Server-side messages, keyed by field. Merged over the form's own and not cleared by
+     * typing.
+     */
     errors?: SchemaFormErrors;
     disabled?: boolean;
+    /**
+     * One bordered surface with sections inside it, or one surface per section. The schema does
+     * not change between them.
+     */
     layout?: SchemaFormLayout;
     columns?: SchemaFormColumns;
     id?: string;
@@ -200,11 +239,20 @@ export interface SchemaFormProps {
     submitting?: boolean;
     onValueChange?: (values: SchemaFormValues) => void;
     onFieldChange?: (key: string, value: SchemaFormValue, values: SchemaFormValues) => void;
+    /**
+     * Runs only if validation passed. `helpers` carries `setFieldValue`, `setValues`, `reset`,
+     * and `validate` — for a server response that has to write back into the form.
+     */
     onSubmit?: (values: SchemaFormValues, helpers: SchemaFormSubmitHelpers, event: FormEvent<HTMLFormElement>) => void | Promise<void>;
     onReset?: (values: SchemaFormValues, helpers: SchemaFormSubmitHelpers) => void;
     /** Receives errors from submission and consumer predicates, validators, or parsers. */
     onError?: (error: unknown) => void;
+    /**
+     * Replaces how a field renders. It receives `defaultField`, so decorating is as easy as
+     * replacing.
+     */
     renderField?: (context: SchemaFormRenderFieldContext) => ReactNode;
+    /** Replaces how a section renders, with its fields already laid out. */
     renderSection?: (context: SchemaFormRenderSectionContext) => ReactNode;
     strings?: Partial<SchemaFormStrings>;
     className?: string;

package/dist/components/features/schema-form/use-schema-form.d.ts

@@ -16,4 +16,9 @@ export interface UseSchemaFormResult extends SchemaFormSubmitHelpers {
     getFieldError: (key: string) => string | undefined;
     getFieldValue: (key: string) => SchemaFormValue;
 }
+/**
+ * The values, the errors, and `validate()` without any of the rendering. Server `errors` win
+ * over local messages for the same key; local messages clear on the field's next change,
+ * server messages stay until the consumer replaces them.
+ */
 export declare function useSchemaForm({ fields, value, defaultValue, errors: externalErrors, onValueChange, onFieldChange, requiredError, validationError, onError, }: UseSchemaFormOptions): UseSchemaFormResult;

package/dist/components/features/sync/sync-range-form.d.ts

@@ -1,2 +1,6 @@
 import { SyncRangeFormProps, SyncRangeFormSubmit } from './sync.types.js';
+/**
+ * The body of a "reconcile the last N hours" dialog. It renders no buttons: the overlay's
+ * footer submits it through `formId`, so native validation runs first.
+ */
 export declare function SyncRangeForm<TSubmit = SyncRangeFormSubmit>({ formId, options, syncOptions, value, defaultValue, onValueChange, transformSubmit, onSubmit, onError, resetKey, disabled, submitting, errors, strings, className, }: SyncRangeFormProps<TSubmit>): import("react").JSX.Element;

package/dist/components/features/sync/sync.types.d.ts

@@ -11,7 +11,10 @@ export interface SyncRangeFormSubmit {
     options: string[];
 }
 export interface SyncRangeFormProps<TSubmit = SyncRangeFormSubmit> {
-    /** Set on the `<form>` so the overlay's footer, outside it, can submit it. */
+    /**
+     * Set on the `<form>` so the overlay's footer, outside it, can submit it. That is why this
+     * takes an id rather than rendering its own buttons.
+     */
     formId: string;
     /** The windows offered. */
     options: CardRadioOption[];
@@ -20,7 +23,11 @@ export interface SyncRangeFormProps<TSubmit = SyncRangeFormSubmit> {
     value?: SyncRangeFormValues;
     defaultValue?: Partial<SyncRangeFormValues>;
     onValueChange?: (value: SyncRangeFormValues) => void;
-    /** Maps the form's values to the consumer's payload. Replaces the numeric default. */
+    /**
+     * Maps the form's values to the consumer's payload. Replaces the numeric default, which
+     * THROWS rather than coercing — `Number("since-last-run")` is NaN, and an API asked to
+     * reconcile NaN hours does something unpredictable.
+     */
     transformSubmit?: (value: SyncRangeFormValues) => TSubmit;
     onSubmit: (data: TSubmit, values: SyncRangeFormValues) => void | Promise<void>;
     onError?: (error: unknown) => void;

package/dist/components/features/table/cell-renderers.d.ts

@@ -25,7 +25,12 @@ export interface StatusClusterCellProps {
     emptyLabel?: ReactNode;
     className?: string;
 }
-/** Several chips in one cell, e.g. overdue and partially paid. */
+/**
+ * Several status chips in one cell, e.g. overdue and partially paid; a status is a Badge. One of
+ * the cells every admin table has, so a page does not rewrite it per column: a thin arrangement
+ * over the kit's primitives that adds the cell's part — the alignment, the truncation, the empty
+ * case.
+ */
 export declare function StatusClusterCell({ items, emptyLabel, className, }: StatusClusterCellProps): import("react").JSX.Element;
 export interface DateCellProps {
     value?: DateValue;
@@ -36,11 +41,21 @@ export interface DateCellProps {
     emptyLabel?: ReactNode;
     className?: string;
 }
+/**
+ * A date, in the scope's pattern unless `pattern` says otherwise. One of the cells every admin
+ * table has, so a page does not rewrite it per column: a thin arrangement over the kit's
+ * primitives that adds the cell's part — the alignment, the truncation, the empty case.
+ */
 export declare function DateCell({ value, pattern, showIcon, icon, emptyLabel, className, }: DateCellProps): import("react").JSX.Element;
 export interface DateMetaCellProps extends DateCellProps {
     /** A second line under the date. A function derives it from the parsed date. */
     secondary?: ReactNode | ((date: Date) => ReactNode);
 }
+/**
+ * A date with a second line under it, given or derived from the parsed date. One of the cells
+ * every admin table has, so a page does not rewrite it per column: a thin arrangement over the
+ * kit's primitives that adds the cell's part — the alignment, the truncation, the empty case.
+ */
 export declare function DateMetaCell({ value, pattern, showIcon, icon, emptyLabel, secondary, className, }: DateMetaCellProps): import("react").JSX.Element;
 export interface CurrencyCellProps {
     value?: number | string | null;
@@ -50,6 +65,11 @@ export interface CurrencyCellProps {
     weight?: "normal" | "medium" | "semibold" | "bold";
     className?: string;
 }
+/**
+ * An amount through Money. One of the cells every admin table has, so a page does not rewrite it
+ * per column: a thin arrangement over the kit's primitives that adds the cell's part — the
+ * alignment, the truncation, the empty case.
+ */
 export declare function CurrencyCell({ value, currency, locale, emptyLabel, weight, className, }: CurrencyCellProps): import("react").JSX.Element;
 export interface AvatarCellProps {
     name?: string | null;
@@ -60,5 +80,10 @@ export interface AvatarCellProps {
     emptyLabel?: ReactNode;
     className?: string;
 }
+/**
+ * A name with its avatar, falling back to initials, and an optional subtitle. One of the cells
+ * every admin table has, so a page does not rewrite it per column: a thin arrangement over the
+ * kit's primitives that adds the cell's part — the alignment, the truncation, the empty case.
+ */
 export declare function AvatarCell({ name, imageUrl, icon, subtitle, emptyLabel, className, }: AvatarCellProps): import("react").JSX.Element;
 export {};

package/dist/components/features/table/cell-value.d.ts

@@ -39,6 +39,11 @@ export type CellStackValue = PrimitiveCellValue | false | ReactElement | CellVal
 export interface CellValueProps extends CellValueDescriptor {
     children?: ReactNode;
 }
+/**
+ * One column's value, formatted. Beside MetadataValue on purpose: that renders a labelled fact on
+ * a detail panel, this renders a value in a grid, where alignment and truncation are the column's
+ * decisions rather than the value's.
+ */
 export declare function CellValue({ value, kind, display, href, currency, minimumFractionDigits, maximumFractionDigits, locale, dateLocale, pattern, from, moneyUnit, fallback, missing, wrap, className, children, }: CellValueProps): import("react").JSX.Element;
 export interface CellStackProps {
     /** Rendered top to bottom. A `false` entry is dropped, so a conditional line is one `&&`. */

package/dist/components/features/table/column-visibility-toggle.d.ts

@@ -1,3 +1,4 @@
 import { RowData } from '@tanstack/react-table';
 import { ColumnVisibilityToggleProps } from './table.types.js';
+/** The columns menu, one of the table's own controls: one checkbox per hideable column. */
 export declare function ColumnVisibilityToggle<TData extends RowData>({ table, className, align, labelVisibility, strings, buttonProps, }: ColumnVisibilityToggleProps<TData>): import("react").JSX.Element | null;

package/dist/components/features/table/data-table-actions.d.ts

@@ -1,3 +1,7 @@
 import { RowData } from '@tanstack/react-table';
 import { DataTableActionsProps } from './table.types.js';
+/**
+ * Row actions as a menu, as buttons, or whichever fits. `auto` measures the CONTAINER, not the
+ * window: whether three buttons fit in an actions column is a question about that column.
+ */
 export declare function DataTableActions<TData extends RowData>({ row, actions, menuLabel, displayMode, responsiveBreakpoint, strings, }: DataTableActionsProps<TData>): import("react").JSX.Element | null;

package/dist/components/features/table/data-table-body.d.ts

@@ -1,3 +1,4 @@
 import { RowData } from '@tanstack/react-table';
 import { DataTableBodyProps } from './table.types.js';
+/** The body rows, and the row that stands in for all of them when there are none. */
 export declare function DataTableBody<TData extends RowData>({ table, onRowClick, emptyStateMessage, emptyStateAction, cellClassName, rowClassName, stickyFirstColumn, hasSelectionColumn, striped, strings, }: DataTableBodyProps<TData>): import("react").JSX.Element;

package/dist/components/features/table/data-table-header.d.ts

@@ -1,3 +1,7 @@
 import { RowData } from '@tanstack/react-table';
 import { DataTableHeaderProps } from './table.types.js';
+/**
+ * The header rows — an optional band of column groups, then the columns. Sorting is base TableHead
+ * doing the work; this only translates the column's state into it.
+ */
 export declare function DataTableHeader<TData extends RowData>({ table, stickyHeader, headerClassName, cellClassName, stickyFirstColumn, hasSelectionColumn, columnGroups, headerTransparent, }: DataTableHeaderProps<TData>): import("react").JSX.Element;

package/dist/components/features/table/data-table-size.d.ts

@@ -1,3 +1,4 @@
 import { DataTableSize } from './table.types.js';
 export declare const DataTableSizeContext: import('react').Context<"sm" | "md" | "lg">;
+/** The table's `size` — its row density — for a part rendered inside a row. */
 export declare function useDataTableSize(): DataTableSize;

package/dist/components/features/table/data-table-toolbar.d.ts

@@ -1,3 +1,8 @@
 import { RowData } from '@tanstack/react-table';
 import { DataTableToolbarProps } from './table.types.js';
+/**
+ * The table's own controls — scroll arrows, the columns menu, full screen — in one bordered group.
+ * It renders NOTHING when it has nothing to offer: a table that fits, cannot hide a column and has
+ * no full-screen toggle would otherwise show an empty frame.
+ */
 export declare function DataTableToolbar<TData extends RowData>({ table, tableAreaRef, fullscreen, onFullscreenChange, showFullscreenToggle, enableColumnVisibility, labelVisibility, strings, }: DataTableToolbarProps<TData>): import("react").JSX.Element | null;

package/dist/components/features/table/fullscreen-toggle.d.ts

@@ -11,4 +11,8 @@ export interface FullscreenToggleProps {
     /** Replaces the underlying Button while retaining the toggle's behavior and content. */
     render?: ReactElement;
 }
+/**
+ * The full-screen toggle, one of the table's own controls, on its own for a consumer building
+ * their own toolbar.
+ */
 export declare function FullscreenToggle({ fullscreen, onFullscreenChange, enterLabel, exitLabel, strings, className, render, }: FullscreenToggleProps): import("react").JSX.Element;

package/dist/components/features/table/index.d.ts

@@ -10,7 +10,8 @@ export { getDataTableScrollContainer, useDataTableScrollState, type UseDataTable
 export { useFullscreenTableModality } from './use-fullscreen-modality.js';
 export { CellStack, CellValue, type CellStackProps, type CellStackValue, type CellValueDescriptor, type CellValueKind, type CellValueProps, type CellValueTuple, type PrimitiveCellValue, } from './cell-value.js';
 export { AvatarCell, CurrencyCell, DateCell, DateMetaCell, StatusCell, StatusClusterCell, type AvatarCellProps, type CurrencyCellProps, type DateCellProps, type DateMetaCellProps, type StatusCellEntry, type StatusCellProps, type StatusClusterCellItem, type StatusClusterCellProps, } from './cell-renderers.js';
-export { ResourceCell, type ResourceCellBadge, type ResourceCellLinkProps, type ResourceCellMetadataItem, type ResourceCellProps, } from './resource-cell.js';
+export { ResourceCell, type ResourceCellBadge, type ResourceCellMetadataItem, type ResourceCellProps, } from './resource-cell.js';
 export { defaultDataTableStrings, mergeDataTableStrings, type DataTableStrings, type DataTableStringsOverride, } from './table.strings.js';
 export type { ClassNameFor, ColumnGroup, ColumnVisibilityToggleProps, DataTableActionsProps, DataTableBodyProps, DataTableHeaderProps, DataTableProps, DataTableSelectionToolbarContext, DataTableSize, DataTableSurface, DataTableToolbarProps, RowActionsDisplayMode, RowClickHandler, RowSelectionHandler, SortingHandler, TableAction, } from './table.types.js';
 export { useDataTableSize } from './data-table-size.js';
+export type { LinkRenderer, LinkRenderProps } from '../../../lib/navigation.js';

package/dist/components/features/table/resource-cell.d.ts

@@ -1,5 +1,6 @@
 import { ReactNode } from 'react';
 import { BadgeTone } from '../../base/badge/index.js';
+import { LinkRenderer } from '../../../lib/navigation.js';
 export interface ResourceCellMetadataItem {
     id?: string;
     label?: ReactNode;
@@ -11,12 +12,6 @@ export type ResourceCellBadge = ReactNode | {
     tone?: BadgeTone;
     icon?: ReactNode;
 };
-export interface ResourceCellLinkProps {
-    href: string;
-    children: ReactNode;
-    className?: string;
-    "aria-label"?: string;
-}
 export interface ResourceCellProps {
     title?: ReactNode;
     subtitle?: ReactNode;
@@ -27,8 +22,8 @@ export interface ResourceCellProps {
     imageUrl?: string;
     fallback?: ReactNode;
     href?: string;
-    /** Routes the title through the app's router instead of a plain anchor. */
-    renderLink?: (props: ResourceCellLinkProps) => ReactNode;
+    /** Routes the title through the app's router, as every component's `renderLink` does; without it, a plain anchor. */
+    renderLink?: LinkRenderer;
     emptyLabel?: ReactNode;
     className?: string;
 }

package/dist/components/features/table/table.types.d.ts

@@ -51,21 +51,33 @@ export type RowActionsDisplayMode = "menu" | "inline" | "auto";
 export type ClassNameFor<TData extends RowData> = string | ((column: string, row: Row<TData> | null) => string);
 export interface DataTableProps<TData extends RowData, TValue = unknown> {
     size?: DataTableSize;
+    /**
+     * The wrapper's chrome. `card` is the ordinary treatment; `glass` is a hairline outline for a
+     * table inside another card, where two card surfaces are a box in a box; `flat` draws nothing.
+     */
     surface?: DataTableSurface;
     /** Drops the header row's muted fill. */
     headerTransparent?: boolean;
     /**
-     * Column definitions, or a `[columns, deps]` tuple memoised here. A column array rebuilt
-     * every render resets TanStack's column state.
+     * Ordinary TanStack column definitions, or a `[columns, deps]` tuple memoised here, because
+     * an array rebuilt every render resets column state on every keystroke elsewhere on the page.
      */
     columns: ColumnDef<TData, TValue>[] | [ColumnDef<TData, TValue>[], DependencyList];
+    /** The page to render. The table never slices it. */
     data: TData[];
     columnGroups?: ColumnGroup[];
+    /** Turns on sorting: the header control AND the state behind it. */
     enableSorting?: boolean;
+    /** Turns on the toolbar's filter AND the state behind it. Requires `filterColumn`. */
     enableFiltering?: boolean;
+    /**
+     * Turns on selection: the checkbox column AND the state behind it, so a checkbox column
+     * cannot exist with selection switched off.
+     */
     enableRowSelection?: boolean;
     enableMultiRowSelection?: boolean;
     enableSubRowSelection?: boolean;
+    /** Turns on column hiding: the toolbar's columns menu AND the state behind it. */
     enableColumnVisibility?: boolean;
     fullscreen?: boolean;
     defaultFullscreen?: boolean;
@@ -73,10 +85,22 @@ export interface DataTableProps<TData extends RowData, TValue = unknown> {
     showFullscreenToggle?: boolean;
     /** The consumer owns sorting: the table reports intent and does not reorder `data`. */
     manualSorting?: boolean;
+    /**
+     * Pins the header row. A pinned pane needs a bounded container to be pinned inside — sticky
+     * with no height cap (`maxBodyHeight`, `fillAvailableHeight`) sticks to the page, which is
+     * nothing.
+     */
     stickyHeader?: boolean;
     stickyToolbar?: boolean;
+    /**
+     * Pins the first column — and the selection checkbox before it, when there is one — while
+     * the body scrolls sideways.
+     */
     stickyFirstColumn?: boolean;
-    /** Caps the scrolling body. A number is pixels. */
+    /**
+     * Caps the scrolling body. A number is pixels. This is the bound a sticky header needs to be
+     * pinned inside.
+     */
     maxBodyHeight?: number | string;
     /** Fills the parent's height, scrolling the body instead of the page. */
     fillAvailableHeight?: boolean;
@@ -99,18 +123,41 @@ export interface DataTableProps<TData extends RowData, TValue = unknown> {
     /** Whether built-in toolbar controls draw their labels. Icon-only by default. */
     toolbarLabelVisibility?: "responsive" | "hidden";
     footerContent?: ReactNode;
-    /** `undefined` renders the default, `null`/`false` suppresses it, a function replaces it. */
+    /**
+     * The bar shown while rows are selected. `undefined` renders the default bar, `null` or
+     * `false` suppresses it, a node or a function replaces it. The function's context carries the
+     * selected rows and a `clearSelection`.
+     */
     selectionToolbar?: ReactNode | ((context: DataTableSelectionToolbarContext<TData>) => ReactNode);
+    /**
+     * The actions inside the default selection bar, or a function of the same context — the
+     * selected rows and a `clearSelection` — that returns them.
+     */
     bulkActions?: ReactNode | ((context: DataTableSelectionToolbarContext<TData>) => ReactNode);
     selectionToolbarClassName?: string;
+    /**
+     * Each row's actions, or a factory of them. The factory form is what a real table needs:
+     * “Delete” belongs on a cancelled booking and nowhere else. `href` is carried as data — the
+     * table never navigates.
+     */
     rowActions?: TableAction<TData>[] | ((row: TData) => TableAction<TData>[]);
     rowActionsMenuLabel?: string | ((row: TData) => string);
+    /**
+     * How row actions render: a menu, inline buttons, or `auto`. `auto` measures the TABLE, not
+     * the window: whether three buttons fit is a question about the table, and the same one is
+     * as often in a drawer as at page width.
+     */
     rowActionsDisplayMode?: RowActionsDisplayMode;
     /** Container width, in pixels, at which `auto` switches from a menu to inline. */
     rowActionsBreakpoint?: number;
-    /** Total page count. Supplying it renders the pager. */
+    /**
+     * Total page count. Supplying it renders the pager once there is more than one page. Add
+     * `totalRowCount` and `pageSize` for the “1–5 of 13” line beside it.
+     */
     pageCount?: number;
+    /** The current page, from 1. */
     page?: number;
+    /** Receives the page the pager moves to. */
     onPageChange?: (page: number) => void;
     /** The result-count line beside the pager. */
     totalRowCount?: number;
@@ -138,7 +185,8 @@ export interface DataTableProps<TData extends RowData, TValue = unknown> {
     };
     /**
      * Persists column visibility to localStorage under `dt.{storageKey}.columns`. An explicit
-     * `defaultColumnVisibility` still wins over the persisted value.
+     * `defaultColumnVisibility` still wins over the persisted value: a developer who hides a
+     * column in code means it.
      */
     storageKey?: string;
     style?: CSSProperties;

package/dist/components/features/table/use-fullscreen-modality.d.ts

@@ -1,2 +1,7 @@
 import { RefObject } from 'react';
+/**
+ * The modality full screen has to take so the page behind it stops being reachable: while
+ * `active`, Escape calls `onExit`, Tab cycles inside `regionRef`, the page stops scrolling, and
+ * focus returns to the opener afterwards.
+ */
 export declare function useFullscreenTableModality(active: boolean, regionRef: RefObject<HTMLElement | null>, onExit: () => void): void;

package/dist/components/features/table/use-table-scroll.d.ts

@@ -11,6 +11,11 @@ export interface UseDataTableScrollStateResult {
     scrollLeft: () => void;
     scrollRight: () => void;
 }
+/**
+ * Whether the table is scrolled away from either edge, and the nudges that move it — what the
+ * toolbar's scroll arrows react to. For a consumer building their own toolbar: reimplementing the
+ * overflow booleans and the nudges means two answers to “can this scroll right”.
+ */
 export declare function useDataTableScrollState(tableAreaRef: RefObject<HTMLDivElement | null>, options?: {
     stepPx?: number;
     deps?: readonly unknown[];

package/dist/components/features/theme-tweaker/theme-scope.d.ts

@@ -1,2 +1,7 @@
 import { ThemeScopeProps } from './theme-tweaker.types.js';
+/**
+ * Applies a theme to an intentionally isolated subtree: one DOM node carrying the theme's
+ * variables and its mode. An app-wide theme belongs on the shared root instead, through
+ * useAppliedTheme.
+ */
 export declare const ThemeScope: import('react').ForwardRefExoticComponent<ThemeScopeProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/components/features/theme-tweaker/theme-tweaker.d.ts

@@ -1,2 +1,8 @@
 import { ThemeTweakerProps } from './theme-tweaker.types.js';
+/**
+ * Edits the kit's public theme contract live and exports the result. Controlled through
+ * `value` / `onValueChange` for the theme and `config` / `onConfigChange` for the provider
+ * settings. Set `apply={false}` when the application owns theme application; `preview={false}`
+ * edits the actual app without a sample preview.
+ */
 export declare const ThemeTweaker: import('react').ForwardRefExoticComponent<ThemeTweakerProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/components/features/theme-tweaker/theme-tweaker.types.d.ts

@@ -97,10 +97,17 @@ export interface ThemeTweakerProps extends Omit<HTMLAttributes<HTMLDivElement>,
      * mounted, so portaled menus and dialogs inherit the edit too.
      */
     target?: ThemeTweakerTarget;
+    /**
+     * Writes the edited theme onto the target. Set `false` when the application owns theme
+     * application, as with useAppliedTheme at its root.
+     */
     apply?: boolean;
     /** Manages `.light` / `.dark` on a non-self target. Off when a theme manager owns it. */
     manageModeClass?: boolean;
-    /** `false` hides it; a node replaces the built-in one. */
+    /**
+     * The sample the edit is shown on. `false` hides it, so the editor edits the actual app
+     * without a sample preview; a node replaces the built-in one.
+     */
     preview?: ReactNode | false;
     fileName?: string;
     config?: UIConfig;

package/dist/components/features/theme-tweaker/ui-config-settings.d.ts

@@ -6,4 +6,9 @@ export interface UIConfigSettingsProps {
     strings?: UIConfigSettingsStrings;
     className?: string;
 }
+/**
+ * The provider settings editor — the non-CSS half of a theme, which ThemeTweaker includes under
+ * Provider. Connect its controlled `config` to your root UIProvider to update mounted
+ * consumers.
+ */
 export declare function UIConfigSettings({ config, onChange, strings, className, }: UIConfigSettingsProps): import("react").JSX.Element;

package/dist/components/features/theme-tweaker/use-applied-theme.d.ts

@@ -1,11 +1,23 @@
 import { RefObject } from 'react';
 import { ThemeDefinition, ThemeTweakerTarget } from './theme-tweaker.types.js';
 interface UseAppliedThemeOptions {
+    /** Writes the theme while `true`; `false` removes what it wrote. */
     apply: boolean;
+    /** Manages `.light` / `.dark` on the target. `false` when UIProvider owns the colour scheme. */
     manageModeClass: boolean;
+    /** The editor's own element, which a `self` target means. */
     selfRef: RefObject<HTMLDivElement | null>;
+    /**
+     * Where the theme goes: `document` for document-wide values, an element, or a function
+     * returning one; `null` applies nothing. A `self` target is left to ThemeScope's inline style.
+     */
     target: ThemeTweakerTarget;
     theme: ThemeDefinition;
 }
+/**
+ * Writes an edited theme onto a live element and removes it on cleanup. Keep it mounted with
+ * `target: "document"` and `apply: true` to apply document-wide values; set
+ * `manageModeClass: false` when UIProvider owns the colour scheme.
+ */
 export declare function useAppliedTheme({ apply, manageModeClass, selfRef, target, theme, }: UseAppliedThemeOptions): void;
 export {};

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

@@ -9,16 +9,37 @@ export interface SidebarInsetLayoutProps extends Omit<ComponentProps<"div">, "ch
     toolbar?: ReactNode | false;
     /** Rendered at the toolbar's trailing edge — a search field, an account menu. */
     toolbarEnd?: ReactNode;
-    /** Shows the panel toggle in the toolbar. On mobile it is the only way to open it. */
+    /**
+     * Shows the panel toggle, the toolbar's collapse control. On mobile it is the only way to
+     * open the panel; turn it off for a shell whose navigation is opened from somewhere else.
+     */
     showTrigger?: boolean;
-    /** Caps the content measure so a wide monitor does not stretch prose across the page. */
+    /**
+     * Caps the content at a reading measure instead of letting it run the shell's full width,
+     * so a wide monitor does not stretch prose across the page.
+     */
     boundContent?: boolean;
-    /** Bounds the shell to its parent instead of the viewport. See SidebarProvider. */
+    /**
+     * Bounds the shell to its parent instead of the viewport. The panel is fixed by default,
+     * which is right for a shell that owns the screen and wrong everywhere else.
+     */
     contained?: boolean;
     defaultOpen?: boolean;
-    /** Configure controlled state, persistence, shortcuts and translated sidebar controls. */
+    /**
+     * Passes `open`/`onOpenChange`, `persist`, `keyboardShortcut` and `strings` to the
+     * shell's provider: controlled state, persistence, shortcuts and translated sidebar
+     * controls. Disable persistence and shortcuts in independent embedded examples.
+     */
     sidebarProviderProps?: Pick<SidebarProviderProps, "open" | "onOpenChange" | "persist" | "keyboardShortcut" | "strings">;
+    /**
+     * Styles the toolbar without wrapping it. The shell owns the grid, so a wrapper around a
+     * region would break the sticky rows.
+     */
     toolbarClassName?: string;
+    /**
+     * Styles the content region without wrapping it. The shell owns the grid, so a wrapper
+     * around a region would break the sticky rows.
+     */
     contentClassName?: string;
     /**
      * Replaces the element the content region is drawn as (`<main>` by default). Pass
@@ -35,9 +56,16 @@ export interface StackedLayoutProps extends Omit<ComponentProps<"div">, "childre
     headerEnd?: ReactNode;
     /** Fit a parent with a definite height and scroll the content below the header. */
     contained?: boolean;
-    /** Set false for tables or composed workspaces that use the full content width. */
+    /**
+     * Caps the reading width. Set false for wide tables and composed workspaces that use the
+     * full content width.
+     */
     boundContent?: boolean;
     children: ReactNode;
+    /**
+     * Styles the header row without wrapping it. The shell owns the grid, so a wrapper around
+     * a region would break the sticky rows.
+     */
     headerClassName?: string;
     contentClassName?: string;
     /**