gridsmith-ui 0.20.0 → 0.22.0

package/dist/index.d.ts

@@ -2,8 +2,10 @@ import * as react from 'react';
 import { ButtonHTMLAttributes, ReactNode, InputHTMLAttributes, LabelHTMLAttributes, TextareaHTMLAttributes, Ref, ReactElement, CSSProperties, HTMLAttributes, RefObject, KeyboardEvent, AnchorHTMLAttributes, ComponentType } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { IconName } from './icons.js';
-import { C as ColumnKind, B as BreakpointKey } from './table-utils-GounRE6s.js';
-export { a as BreakpointWidthProvider, u as useBreakpoint } from './table-utils-GounRE6s.js';
+import { C as ColumnKind, B as BreakpointKey } from './table-utils-BkjNEWts.js';
+export { a as BreakpointWidthProvider, u as useBreakpoint } from './table-utils-BkjNEWts.js';
+import { P as Pager, A as AppShellPreferences } from './use-pagination-DiJo0aW5.js';
+export { a as PaginationOptions, b as PreferencesContext, R as ResolvedPreferences, p as preferenceActionKey, u as usePagination, c as usePreferences } from './use-pagination-DiJo0aW5.js';
 
 type ButtonVariant = "default" | "secondary" | "tertiary" | "outline" | "ghost" | "destructive" | "success" | "warning" | "link";
 type ButtonSize = "xs" | "sm" | "md" | "lg" | "icon-xs" | "icon-sm" | "icon" | "icon-lg";
@@ -207,7 +209,8 @@ interface ComboboxProps extends FieldControlWiring {
 declare function Combobox({ value, onChange: onChangeProp, options, placeholder, disabled, loading, className, ref, container, error, size: sizeProp, ...wiring }: ComboboxProps): react_jsx_runtime.JSX.Element;
 
 type CheckboxSize = "sm" | "md";
-interface CheckboxProps {
+/** A Field passes its wiring (0.21.0): its label names the box, and its hint and error describe it. */
+interface CheckboxProps extends FieldControlWiring {
     checked: boolean;
     onChange: (checked: boolean) => void;
     label?: string;
@@ -217,7 +220,7 @@ interface CheckboxProps {
     className?: string;
     ref?: Ref<HTMLInputElement>;
 }
-declare function Checkbox({ checked, onChange: onChangeProp, label, size, disabled, indeterminate, className, ref }: CheckboxProps): react_jsx_runtime.JSX.Element;
+declare function Checkbox({ checked, onChange: onChangeProp, label, size, disabled, indeterminate, className, ref, ...wiring }: CheckboxProps): react_jsx_runtime.JSX.Element;
 interface CheckboxGroupProps {
     value: string[];
     onChange: (value: string[]) => void;
@@ -241,7 +244,8 @@ interface RadioOption {
     label: string;
     disabled?: boolean;
 }
-interface RadioGroupProps {
+/** A Field passes its wiring (0.21.0): its label names the group, and its hint and error describe it. */
+interface RadioGroupProps extends FieldControlWiring {
     value: string;
     onChange: (value: string) => void;
     options: RadioOption[];
@@ -249,7 +253,7 @@ interface RadioGroupProps {
     className?: string;
     label?: string;
 }
-declare function RadioGroup({ value, onChange: onChangeProp, options, orientation, className, label }: RadioGroupProps): react_jsx_runtime.JSX.Element;
+declare function RadioGroup({ value, onChange: onChangeProp, options, orientation, className, label, ...wiring }: RadioGroupProps): react_jsx_runtime.JSX.Element;
 
 interface DatePickerProps extends Omit<FieldControlWiring, "id"> {
     value: Date | null;
@@ -364,7 +368,10 @@ interface FileUploadProps {
     onCancel?: (item: FileUploadItem) => void;
     /** A failed upload's Retry. With `upload`, FileUpload runs it again itself. */
     onRetry?: (item: FileUploadItem) => void;
-    /** A file's Remove. With `files` the page takes it off its list; otherwise FileUpload does, and tells the page. */
+    /**
+     * A file's Remove. With `files` the page takes it off its list; otherwise FileUpload does, and tells the page. Without
+     * it, Remove shows only on a failed file: the page would still have a file the user removed (0.21.0).
+     */
     onRemove?: (item: FileUploadItem) => void;
     /**
      * The types the zone takes, as for an `<input type="file">`: ".csv", "image/*", "application/pdf". The zone says them
@@ -486,7 +493,8 @@ interface PinInputProps {
 }
 declare function PinInput({ value, onChange: onChangeProp, length, mask, disabled, size: sizeProp, className, error, id, }: PinInputProps): react_jsx_runtime.JSX.Element;
 
-interface RatingProps {
+/** A Field passes its wiring (0.21.0): its label names the stars, and its hint and error describe them. */
+interface RatingProps extends FieldControlWiring {
     value: number;
     onChange?: (value: number) => void;
     max?: number;
@@ -496,7 +504,7 @@ interface RatingProps {
     className?: string;
     error?: boolean;
 }
-declare function Rating({ value, onChange: onChangeProp, max, allowHalf, readOnly, size, className, error, }: RatingProps): react_jsx_runtime.JSX.Element;
+declare function Rating({ value, onChange: onChangeProp, max, allowHalf, readOnly, size, className, error, ...wiring }: RatingProps): react_jsx_runtime.JSX.Element;
 
 interface ColorPickerProps {
     value: string;
@@ -552,8 +560,10 @@ interface FormWrapperProps {
      * them from the page as before.
      *
      * In a Drawer, Dialog or Sheet, return the save's promise: the overlay stops asking before discarding once it
-     * resolves, and keeps asking if it's rejected. Returning nothing works for a save that keeps the form on screen; a
-     * submit that moves on to another step keeps the overlay's changes until the flow saves (Sprint 25.12 A15).
+     * resolves, and keeps asking if it's rejected. If you catch a failure to show it, throw it again, so the promise
+     * rejects: one that resolves is a save. Returning nothing works for a save that keeps the form on screen or shows a
+     * confirmation in its place; a submit that moves on to another step keeps the overlay's changes until the flow saves
+     * (Sprint 25.12 A15). A field still invalid once the page has answered means nothing saved.
      */
     onSubmit: (errors: FormErrors) => unknown;
     validationMode?: ValidationMode;
@@ -677,13 +687,20 @@ interface CardProps extends HTMLAttributes<HTMLDivElement> {
 }
 declare const Card: react.ForwardRefExoticComponent<CardProps & react.RefAttributes<HTMLDivElement>>;
 interface CardHeaderProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * The header's badges and buttons, in one slot. A badge sits beside the title (D1a); a button, like the ⋯, at the
+     * row's end. A header holds a status badge and at most one action or the ⋯ menu (data_display#35).
+     */
     actions?: ReactNode;
     icon?: IconName;
     menuItems?: DropdownMenuEntry[];
 }
 declare const CardHeader: react.ForwardRefExoticComponent<CardHeaderProps & react.RefAttributes<HTMLDivElement>>;
 interface CardTitleProps extends HTMLAttributes<HTMLHeadingElement> {
-    /** Max lines before clamping (with the full title on hover). Default 2, like CardDescription; 1 truncates on one line; 0 = no limit. */
+    /**
+     * Max lines before clamping (with the full title on hover). Default 2, like CardDescription, and 1 in a CardHeader's
+     * row, where the title truncates beside its badge and the ⋯ (Sprint 25.13 A1); 0 = no limit.
+     */
     lines?: number;
 }
 declare const CardTitle: react.ForwardRefExoticComponent<CardTitleProps & react.RefAttributes<HTMLHeadingElement>>;
@@ -726,7 +743,13 @@ interface DataListProps {
 declare function DataList({ items, columns, className }: DataListProps): react_jsx_runtime.JSX.Element;
 
 interface CardGridProps extends HTMLAttributes<HTMLDivElement> {
-    /** The narrowest a card may be, as a CSS length. The grid takes as many columns as fit at it. Default "14rem". */
+    /**
+     * The narrowest a card may be, as a CSS length; the grid takes as many columns as fit at it. By default a collection
+     * reads it from its cards' headers (Sprint 25.13 A2): about 20rem when a header is given `actions` (a badge or a
+     * button besides the ⋯), so a name shows beside them, and 14rem otherwise (a file grid keeps its smaller cards). A comparison keeps
+     * 14rem whatever its headers hold, so its plans stay side by side (D29). Pass one when the cards need their own:
+     * the width at which the longest title you expect still shows beside what its header holds.
+     */
     minWidth?: string;
     /** The most cards in a row, however wide the grid is. Default 4. A comparison (`compare`) takes all its cards instead. */
     maxColumns?: number;
@@ -743,6 +766,13 @@ interface CardGridProps extends HTMLAttributes<HTMLDivElement> {
      * the gap is this prop, never a `gap-*` class (which would leave the columns measured for another gap).
      */
     gap?: string;
+    /**
+     * A collection whose cards all fit on one row fills it (Sprint 25.13 A32, the owner's R28-61: a short row "looks odd
+     * like a fourth card was supposed to be there"): they share the row equally, and a lone card takes at most half. A
+     * grid of more rows keeps its columns. Default on; pass false for a collection whose count changes (a filter, a
+     * pager's last page), so its cards don't change size as the results change.
+     */
+    fill?: boolean;
     children: ReactNode;
     ref?: Ref<HTMLDivElement>;
 }
@@ -762,7 +792,7 @@ interface CardGridProps extends HTMLAttributes<HTMLDivElement> {
  * share three rows (header, content, footer), so their parts line up; a child that is not a Card fills its three rows
  * without lining anything up.
  */
-declare function CardGrid({ minWidth, maxColumns, compare, gap, className, style, children, ref, ...props }: CardGridProps): react_jsx_runtime.JSX.Element;
+declare function CardGrid({ minWidth, maxColumns, compare, gap, fill, className, style, children, ref, ...props }: CardGridProps): react_jsx_runtime.JSX.Element;
 
 interface DescriptionItem {
     label: string;
@@ -818,11 +848,26 @@ interface AccordionProps {
 }
 declare function Accordion({ items, type, defaultOpen, open: controlledOpen, onOpenChange, className }: AccordionProps): react_jsx_runtime.JSX.Element;
 
+/** A row: a value or an element for each column's key, and any fields of the page's own (an `id`, say). */
+type TableRow = Record<string, string | number | ReactNode>;
 interface Column {
     key: string;
     header: string;
     align?: "left" | "center" | "right";
     sortable?: boolean;
+    /**
+     * What the column sorts by, when its cells don't say (Sprint 25.13 A3): a column of elements (an avatar beside a name,
+     * a badge, a time) gives each row's name, number or date here, `sortValue: (row) => row.actorName`, and a column of
+     * sizes gives bytes. Without it a sortable column sorts by the cell itself, which works for text and numbers; a cell
+     * that is an element can't be compared, and the column warns in development (data_display#1).
+     */
+    sortValue?: (row: TableRow) => string | number | Date | null | undefined;
+    /**
+     * Keep the column in view while the table scrolls sideways (Sprint 25.13 A35): "end" for the row's actions, pinned on
+     * the right; "start" for the row's name, drawn first and pinned beside the selection while it leaves room. Without a
+     * "start" column, the first column is the row's name.
+     */
+    pin?: "start" | "end";
     /** Opt-in text truncation. true = 1 line, or { lines: N } for multi-line clamp before truncating. */
     truncate?: boolean | {
         lines: number;
@@ -843,25 +888,58 @@ type SortDir = "asc" | "desc" | null;
 type TableDensity = "default" | "compact";
 interface TableProps {
     columns: Column[];
-    data: Record<string, string | number | ReactNode>[];
+    /** Every row. With `pager`, the whole list: the table sorts all of it and draws the pager's part (A3). */
+    data: TableRow[];
     className?: string;
     sortable?: boolean;
     sortKey?: string | null;
     sortDir?: SortDir;
     onSortChange?: (key: string | null, dir: SortDir) => void;
     selectable?: boolean;
+    /** The selected rows, as indexes into `data`, which a sort or a new page never changes. */
     selectedRows?: number[];
     onSelectionChange?: (rows: number[]) => void;
     expandable?: boolean;
-    renderExpanded?: (row: Record<string, string | number | ReactNode>, index: number) => ReactNode;
+    /** A row's panel, under it when it's open; `index` is the row's index in `data`. */
+    renderExpanded?: (row: TableRow, index: number) => ReactNode;
+    /**
+     * The field that names a row (default `id`, Sprint 25.13 A46): open rows are kept by it, so a sort, a filter or a
+     * new page never moves them. A row with no such field is named by its index in `data`.
+     */
+    rowKey?: string;
+    /**
+     * The open rows, by the field `rowKey` names (A46), controlled with `onExpandedChange`. A record's address opens its
+     * row, `expandedRows={id ? [id] : []}`: the row is brought into view, and with a pager its page comes up.
+     */
+    expandedRows?: Array<string | number>;
+    /** The rows open at first, when the table keeps its own (A46). */
+    defaultExpandedRows?: Array<string | number>;
+    onExpandedChange?: (rows: Array<string | number>) => void;
     density?: TableDensity;
     stickyHeader?: boolean;
     striped?: boolean;
     loading?: boolean;
     emptyState?: ReactNode;
-    onRowClick?: (row: Record<string, string | number | ReactNode>, index: number) => void;
-    /** Breakpoint at which the table switches to card layout. Defaults to "md" (768px). */
+    /**
+     * A click on a row, or Enter or Space on it: the page decides what opens. Without it an expandable row opens with a
+     * click anywhere on it (P33). A click on a control inside the row stays that control's (A45).
+     */
+    onRowClick?: (row: TableRow, index: number) => void;
+    /** The screen width below which the table shows cards: the project's responsive.tableToCardsBreakpoint, else "md". */
     mobileBreakpoint?: BreakpointKey;
+    /**
+     * The table's own width below which it shows cards (Sprint 25.13 A35), in px: about a phone's by default, so a table
+     * in a pane, a drawer or a dialog stays a table, scrolling sideways, until its space is a phone's. 0 never switches by
+     * width; a narrow screen still does.
+     */
+    cardsBelow?: number;
+    /**
+     * The list's pager (Sprint 25.13 A3), from `usePagination(rows)` over the same rows as `data`: the table sorts every
+     * row, draws the pager's part (a page, or every page loaded so far) and, beneath it, the control in the project's
+     * style. A new sort starts again at page 1. Give TableToolbar the same pager for the count, and draw no <Pagination>
+     * of your own.
+     */
+    pager?: Pager<unknown>;
     /**
      * The table's title inside its frame (Sprint 25.9, A1): a heading in CardTitle's style at CardHeader's inset, in a band
      * above the scroll area that never scrolls sideways, and the `<table>`'s name. Title a table this way or with a
@@ -882,7 +960,7 @@ interface TableProps {
     "aria-label"?: string;
     ref?: Ref<HTMLDivElement>;
 }
-declare function Table({ columns, data, className, sortable, sortKey: controlledSortKey, sortDir: controlledSortDir, onSortChange, selectable, selectedRows, onSelectionChange, expandable, renderExpanded, density, stickyHeader, striped, loading, emptyState, onRowClick, mobileBreakpoint: mobileBreakpointProp, title, description, actions, "aria-label": ariaLabel, ref, }: TableProps): react_jsx_runtime.JSX.Element;
+declare function Table({ columns: columnsProp, data, className, sortable, sortKey: controlledSortKey, sortDir: controlledSortDir, onSortChange, selectable, selectedRows, onSelectionChange, expandable, renderExpanded, rowKey, expandedRows: expandedRowsProp, defaultExpandedRows, onExpandedChange, density, stickyHeader, striped, loading, emptyState, onRowClick, mobileBreakpoint: mobileBreakpointProp, cardsBelow, pager, title, description, actions, "aria-label": ariaLabel, ref, }: TableProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null | undefined;
 
 interface CalendarEvent {
     id: string;
@@ -1153,8 +1231,13 @@ interface TimelineProps {
     minItemWidth?: number;
     className?: string;
     ref?: Ref<HTMLDivElement>;
+    /**
+     * The list's pager (Sprint 25.13 A3), from `usePagination(items)` over the same items: the timeline draws the pager's
+     * part of every item and, beneath it, the control in the project's style. Draw no <Pagination> of your own.
+     */
+    pager?: Pager<unknown>;
 }
-declare function Timeline({ items, orientation, minItemWidth, className, ref }: TimelineProps): react_jsx_runtime.JSX.Element;
+declare function Timeline({ items: allItems, orientation, minItemWidth, className, ref, pager }: TimelineProps): react_jsx_runtime.JSX.Element;
 
 interface CodeBlockProps {
     code: string;
@@ -1467,6 +1550,11 @@ interface StackedListProps {
     flush?: boolean;
     /** @deprecated Sprint 25.4: use variant="articles" (hover="title") — the default variant tints the row. */
     hover?: "tint" | "title";
+    /**
+     * The list's pager (Sprint 25.13 A3), from `usePagination(items)` over the same items: the list draws the pager's
+     * part of every item and, beneath it, the control in the project's style. Draw no <Pagination> of your own.
+     */
+    pager?: Pager<unknown>;
 }
 declare const StackedList: react.ForwardRefExoticComponent<StackedListProps & react.RefAttributes<HTMLUListElement>>;
 
@@ -2230,6 +2318,8 @@ interface PaginationProps {
     /** The Load more button's label (default "Load more"). */
     loadMoreLabel?: string;
     className?: string;
+    /** Set by `usePagination` in `pager.props`: which list the control belongs to (Sprint 25.13 A3). */
+    pagerToken?: object;
 }
 declare function Pagination(props: PaginationProps): react_jsx_runtime.JSX.Element;
 
@@ -2825,11 +2915,12 @@ interface ToastProps {
     pauseOnHover?: boolean;
     /**
      * The toast's action. Sprint 25.12 A40 (the sourced overlays#18): a toast with an action never closes on a timer while
-     * the action can still be taken. With `actionWindow` the action lapses after that long, and the toast stays as a plain
-     * message for its `duration`; without one it stays until the user acts or dismisses it.
+     * the action can still be taken. With `actionWindow` the action lapses after that long: in a ToastProvider the toast
+     * then stays as a plain message for its `duration`, and a standalone toast closes (onDismiss). Without one it stays until
+     * the user acts or dismisses it.
      */
     action?: ToastAction;
-    /** How long the action is offered once the toast shows, in ms (an Undo's window). */
+    /** How long the action is offered once the toast shows, in ms (an Undo's window). A standalone toast closes when it ends. */
     actionWindow?: number;
     position?: ToastPosition;
     mode?: "light" | "dark";
@@ -2970,71 +3061,6 @@ interface ScrollAreaProps {
 }
 declare function ScrollArea({ children, className, orientation, maxHeight, maxWidth, }: ScrollAreaProps): react_jsx_runtime.JSX.Element;
 
-type PreferenceValidationTiming = "onBlur" | "onSubmit" | "onChange";
-type PreferenceBreakpoint = "sm" | "md" | "lg";
-type PreferenceEmptyStyle = "illustration-cta" | "text-cta" | "redirect";
-type PreferenceLoadingStyle = "skeleton" | "spinner" | "progress-bar";
-type PreferenceDestructiveMode = "dialog" | "undo";
-/** dataDisplay.paginationStyle — how a long list shows more: page numbers, a Load more button, or loading as the user scrolls. */
-type PreferencePaginationStyle = "pagination" | "load-more" | "infinite-scroll";
-interface AppShellPreferences {
-    /** forms.validationTiming — when a field first shows its error. */
-    validationTiming?: PreferenceValidationTiming;
-    /** forms.actions — where a form's buttons sit and how they align. */
-    formActions?: {
-        align?: "start" | "end";
-        placement?: "auto" | "inline";
-    };
-    /** dataDisplay.itemsPerPage — the page size of a paged or load-more list. */
-    itemsPerPage?: number;
-    /** dataDisplay.paginationStyle — page numbers, a Load more button, or loading on scroll; usePagination and Pagination follow it (round 22). */
-    paginationStyle?: PreferencePaginationStyle;
-    /** responsive.tableToCardsBreakpoint — below this width a Table becomes stacked cards. */
-    tableToCardsBreakpoint?: PreferenceBreakpoint;
-    /** emptyStates.emptyStyle — illustration with an action, text with an action, or redirect to creation. */
-    emptyStyle?: PreferenceEmptyStyle;
-    /** emptyStates.loadingStyle — what a page shows while data loads. */
-    loadingStyle?: PreferenceLoadingStyle;
-    /** destructiveActions.mode — confirm in a dialog, or act now with an Undo toast. */
-    destructiveMode?: PreferenceDestructiveMode;
-    /** destructiveActions.highSeverityActions — always confirm in a dialog, even in undo mode. */
-    highSeverityActions?: string[];
-    /** destructiveActions.typeToConfirmActions — the user types the name before the confirm enables. */
-    typeToConfirmActions?: string[];
-    /** destructiveActions.undoWindowSeconds — how long the Undo toast stays. */
-    undoWindowSeconds?: number;
-}
-declare const PreferencesContext: react.Context<AppShellPreferences | null>;
-/** Every preference in force, the shell's value or the house default — what app code reads. */
-interface ResolvedPreferences {
-    validationTiming: PreferenceValidationTiming;
-    formActions: {
-        align: "start" | "end";
-        placement: "auto" | "inline";
-    };
-    itemsPerPage: number;
-    paginationStyle: PreferencePaginationStyle;
-    tableToCardsBreakpoint: PreferenceBreakpoint;
-    emptyStyle: PreferenceEmptyStyle;
-    loadingStyle: PreferenceLoadingStyle;
-    destructiveMode: PreferenceDestructiveMode;
-    highSeverityActions: string[];
-    typeToConfirmActions: string[];
-    undoWindowSeconds: number;
-}
-/**
- * For app code: every preference in force — the shell's value, else the house default — so a page never writes a
- * fallback of its own. Round 21 (run 58): with every field optional, TypeScript made the builder write
- * `const { itemsPerPage = 20 } = usePreferences()`, a second copy of the preference it then edited by hand when the
- * rule changed. Paged lists use `usePagination`, which reads the page size itself.
- */
-declare function usePreferences(): ResolvedPreferences;
-/**
- * "Remove range" → "remove_range": the key the high-severity and type-to-confirm lists use. The engine's `actionKey`
- * (platform/src/lib/destructive-mode.ts) is the same rule for compliance; a platform test keeps the two identical.
- */
-declare function preferenceActionKey(label: string): string;
-
 interface AppShellContextValue {
     hasSidebar: boolean;
     hasMobileMenu: boolean;
@@ -3169,68 +3195,6 @@ interface AppShellProps {
 }
 declare const AppShell: react.ForwardRefExoticComponent<AppShellProps & react.RefAttributes<HTMLDivElement>>;
 
-/**
- * A long list in one hook (round 21; all three list styles since round 22). The page size and the list style are the
- * project's `dataDisplay.itemsPerPage` and `dataDisplay.paginationStyle`, read from the shell, so a mid-build
- * `update_rule` on either reaches every list with no page edited. The page gets what to show, the props for
- * `<Pagination>` — page numbers, a Load more button or loading on scroll, whichever the project's style is — and the
- * numbers the count line needs ("Showing 51–100 of 200 events", or "Showing 40 of 120 members" while a list grows).
- *
- * Run 58 hand-wrote the paging; runs 59 and 60 hand-wrote load-more and scroll loading — an IntersectionObserver, a
- * visible count and a page size copied in as a constant, twice in one app — because the library had no way to.
- *
- *   const pager = usePagination(sortedEvents, { resetOn: [sortKey, sortDir] })
- *   <TableToolbar resultCount={sortedEvents.length} resultNoun={["event", "events"]} pagination={pager} />
- *   <Table columns={columns} data={pager.items.map(toRow)} />
- *   <Pagination {...pager.props} />
- */
-interface Pager<T> {
-    /** The list style this list follows: the project's, unless `style` was passed. */
-    style: PreferencePaginationStyle;
-    /** What to show: the current page's rows, or every row loaded so far on a list that grows. */
-    items: T[];
-    /** The current page, from 1; on a growing list, how many pages are loaded. */
-    page: number;
-    pageSize: number;
-    totalItems: number;
-    totalPages: number;
-    /** The first and last row numbers on screen, from 1 ("Showing 51–100"); [0, 0] for an empty list. */
-    range: [number, number];
-    /** How many rows are on screen. */
-    shown: number;
-    /** Rows left to show: a next page, or more to load. */
-    hasMore: boolean;
-    /** The next page, or the next `pageSize` rows on a growing list. */
-    loadMore: () => void;
-    setPage: (page: number) => void;
-    /** A page-size selector's choice; it wins over the project's page size and starts again at page 1. */
-    setPageSize: (size: number) => void;
-    /** Spread onto <Pagination>: it renders page numbers, a Load more button or the scroll trigger, as `style` says. */
-    props: {
-        currentPage: number;
-        totalPages: number;
-        onPageChange: (page: number) => void;
-        pageSize: number;
-        onPageSizeChange: (size: number) => void;
-        mode: PreferencePaginationStyle;
-        hasMore: boolean;
-        onLoadMore: () => void;
-    };
-}
-interface PaginationOptions {
-    /** A fixed page size for this list, over the project's. Leave it out: the project's page size is the rule. */
-    pageSize?: number;
-    /** Values that start the list again at page 1 when they change — the sort column and direction, a search query. */
-    resetOn?: unknown;
-    /**
-     * A list style for this list only, over the project's. Leave it out: the project's style is the rule. Passing one that
-     * differs is overriding a rule in force — ask the user first, and put `// @gridsmith-override
-     * dataDisplay.paginationStyle: <their reason>` above the call.
-     */
-    style?: PreferencePaginationStyle;
-}
-declare function usePagination<T>(list: readonly T[], options?: PaginationOptions): Pager<T>;
-
 interface DestructiveActionOptions {
     /** The action's key as the preference lists name it ("remove_range"); derived from `title` when omitted. */
     action?: string;
@@ -3242,8 +3206,11 @@ interface DestructiveActionOptions {
     confirmLabel?: string;
     /** The text the user must type when the action is on the type-to-confirm list (the item's name). */
     typeToConfirm?: string;
-    /** Performs the action. In undo mode it runs at once. */
-    onConfirm: () => void | Promise<void>;
+    /**
+     * Performs the action. In undo mode it runs at once. Reject (throw) when it fails: the hook then says so and claims
+     * nothing. Any return is allowed; a promise is awaited.
+     */
+    onConfirm: () => unknown;
     /**
      * Restores what the action removed; the Undo toast's action in undo mode. Without it the toast has no Undo. It may
      * return a promise: once it resolves the hook confirms with a toast (`restoredMessage`), and a rejection shows an
@@ -3422,4 +3389,4 @@ interface UseTextOverflowResult {
  */
 declare function useTextOverflow(options?: UseTextOverflowOptions): UseTextOverflowResult;
 
-export { Accordion, ActionPanel, ActionPanelGroup, AddAnother, type AddAnotherProps, Alert, type AlertPlacement, AppShell, type AppShellContextValue, type AppShellFocus, type AppShellPreferences, type AppShellTheme, AsidePanel, type AsidePanelProps, type AsidePanelSide, Avatar, AvatarGroup, type AvatarGroupItem, type AvatarGroupProps, type AvatarStatus, Badge, type BadgePaletteColor, type BadgeSeverity, type BadgeSize, type BadgeVariant, BottomNav, type BottomNavItem, type BreadcrumbItem$1 as BreadcrumbItem, Breadcrumbs, type BreadcrumbsSeparator, type BreadcrumbsSize, type BreadcrumbsVariant, BreakpointKey, BulkActionBar, Button, ButtonSizeContext, Calendar, type CalendarDay, Card, CardContent, CardDescription, CardFooter, CardGrid, type CardGridProps, CardHeader, type CardSelectType, CardTitle, type CardVariant, Carousel, type ChatMessage, type ChatMessageAction, type ChatMessageLayout, ChatMessageList, type ChatMessageSender, type ChatMessageSource, type ChatMessageStatus, ChatPanel, type ChatPanelProps, type ChatPanelStatusTone, Checkbox, CheckboxGroup, CheckboxGroupItem, CodeBlock, Collapsible, ColorPicker, type Column, Combobox, CommandPalette, ContextMenu, type ControlSize, ControlSizeContext, CornerPanel, type CornerPanelEdge, type CornerPanelProps, DEFAULT_DATE_RANGE_PRESETS, DataList, type DateInput, DatePicker, type DateRange, DateRangePicker, type DateRangePickerProps, type DateRangePreset, type DateRangeWords, type DescriptionItem, DescriptionList, type DescriptionListOrientation, type DescriptionListSize, type DestructiveActionHandle, type DestructiveActionOptions, Dialog, Divider, Dock, Drawer, Dropdown, DropdownMenu, type DropdownMenuDivider, type DropdownMenuEntry, type DropdownMenuItem, EmptyState, EntityCell, Field, type FieldControlProps, type FieldLabel, type FieldProps, FileUpload, type FileUploadItem, type FileUploadRequestOptions, type FileUploadStatus, type FitLabelsOptions, type FittedLabel, FormWrapper, Gantt, type GanttGroup, type GanttItem, type GanttProps, type GanttStatus, type GanttTone, type GridKeyboard, type GridKeyboardOptions, HoverCard, InlineFieldError, Input, Kbd, Label, type LabelBox, Launcher, type LauncherEdge, type LauncherProps, type LauncherVariant, type LauncherWhenOpen, Link, type LinkProps, MentionInput, MobileHeaderMenu, type MobileHeaderMenuItemData, type MobileHeaderMenuType, NavItem, type NavItemProps, type NavItemType, NavMenu, type NavMenuItem, Navbar, type NavbarSize, type NavbarType, type NavbarVariant, NotificationCenter, NumberInput, PageContainer, type PageContainerWidth, PageHeader, type PageHeaderBehavior, type PageHeaderIntensity, type PageHeaderProps, type PageHeaderVariant, type Pager, Pagination, type PaginationOptions, PinInput, Popover, PreferencesContext, Progress, type PromiseToastMessages, RadioGroup, Rating, type ResolvedPreferences, ScrollArea, SectionHeading, type SectionHeadingProps, SegmentedControl, SettingsLayout, type SettingsLayoutProps, type SettingsSection, Sheet, Sidebar, type SidebarContextValue, type SidebarItem, SidebarNav, type SidebarNavSize, type SidebarPosition, type SidebarSection, type SidebarType, Skeleton, SkipLink, SliderRange, Spinner, StackedList, type StackedListVariant, StatsCard, StatusDot, type StatusDotVariant, Stepper, TIME_ZOOMS, type Tab, Table, type TableDensity, type TableProps, TableToolbar, type TableToolbarActiveFilter, type TableToolbarFilterOption, Tabs, Tag, TagInput, type TagPaletteColor, type TagVariant, TextOverflow, type TextOverflowProps, Textarea, TimeBar, type TimeBarProps, TimePicker, TimeRow, type TimeRowProps, type TimeScale, TimeScaleHeader, type TimeScaleHeaderProps, type TimeScaleOptions, type TimeTick, TimeViewport, type TimeViewportHandle, type TimeViewportLayout, type TimeViewportProps, type TimeViewportState, type TimeZoom, Timeline, Toast, type ToastAction, type ToastApi, type ToastOptions, type ToastPosition, ToastProvider, type ToastVariant, Toggle, Tooltip, Tour, TransferList, TreeView, type Trend, type UseTextOverflowOptions, type UseTextOverflowResult, dateOfDay, dayOf, endDayOf, fitLabel, fitLabels, formatDateRange, preferenceActionKey, timeExtent, useAppShell, useContentWidth, useDestructiveAction, useFittedLabels, useFormContext, useGridKeyboard, usePagination, usePreferences, useSidebar, useTextMeasure, useTextOverflow, useTimeScale, useTimeViewport, useTimeViewportLayout, useToast, useToastOptional, useUnsavedChanges };
+export { Accordion, ActionPanel, ActionPanelGroup, AddAnother, type AddAnotherProps, Alert, type AlertPlacement, AppShell, type AppShellContextValue, type AppShellFocus, AppShellPreferences, type AppShellTheme, AsidePanel, type AsidePanelProps, type AsidePanelSide, Avatar, AvatarGroup, type AvatarGroupItem, type AvatarGroupProps, type AvatarStatus, Badge, type BadgePaletteColor, type BadgeSeverity, type BadgeSize, type BadgeVariant, BottomNav, type BottomNavItem, type BreadcrumbItem$1 as BreadcrumbItem, Breadcrumbs, type BreadcrumbsSeparator, type BreadcrumbsSize, type BreadcrumbsVariant, BreakpointKey, BulkActionBar, Button, ButtonSizeContext, Calendar, type CalendarDay, Card, CardContent, CardDescription, CardFooter, CardGrid, type CardGridProps, CardHeader, type CardSelectType, CardTitle, type CardVariant, Carousel, type ChatMessage, type ChatMessageAction, type ChatMessageLayout, ChatMessageList, type ChatMessageSender, type ChatMessageSource, type ChatMessageStatus, ChatPanel, type ChatPanelProps, type ChatPanelStatusTone, Checkbox, CheckboxGroup, CheckboxGroupItem, CodeBlock, Collapsible, ColorPicker, type Column, Combobox, CommandPalette, ContextMenu, type ControlSize, ControlSizeContext, CornerPanel, type CornerPanelEdge, type CornerPanelProps, DEFAULT_DATE_RANGE_PRESETS, DataList, type DateInput, DatePicker, type DateRange, DateRangePicker, type DateRangePickerProps, type DateRangePreset, type DateRangeWords, type DescriptionItem, DescriptionList, type DescriptionListOrientation, type DescriptionListSize, type DestructiveActionHandle, type DestructiveActionOptions, Dialog, Divider, Dock, Drawer, Dropdown, DropdownMenu, type DropdownMenuDivider, type DropdownMenuEntry, type DropdownMenuItem, EmptyState, EntityCell, Field, type FieldControlProps, type FieldLabel, type FieldProps, FileUpload, type FileUploadItem, type FileUploadRequestOptions, type FileUploadStatus, type FitLabelsOptions, type FittedLabel, FormWrapper, Gantt, type GanttGroup, type GanttItem, type GanttProps, type GanttStatus, type GanttTone, type GridKeyboard, type GridKeyboardOptions, HoverCard, InlineFieldError, Input, Kbd, Label, type LabelBox, Launcher, type LauncherEdge, type LauncherProps, type LauncherVariant, type LauncherWhenOpen, Link, type LinkProps, MentionInput, MobileHeaderMenu, type MobileHeaderMenuItemData, type MobileHeaderMenuType, NavItem, type NavItemProps, type NavItemType, NavMenu, type NavMenuItem, Navbar, type NavbarSize, type NavbarType, type NavbarVariant, NotificationCenter, NumberInput, PageContainer, type PageContainerWidth, PageHeader, type PageHeaderBehavior, type PageHeaderIntensity, type PageHeaderProps, type PageHeaderVariant, Pager, Pagination, PinInput, Popover, Progress, type PromiseToastMessages, RadioGroup, Rating, ScrollArea, SectionHeading, type SectionHeadingProps, SegmentedControl, SettingsLayout, type SettingsLayoutProps, type SettingsSection, Sheet, Sidebar, type SidebarContextValue, type SidebarItem, SidebarNav, type SidebarNavSize, type SidebarPosition, type SidebarSection, type SidebarType, Skeleton, SkipLink, SliderRange, type SortDir, Spinner, StackedList, type StackedListVariant, StatsCard, StatusDot, type StatusDotVariant, Stepper, TIME_ZOOMS, type Tab, Table, type TableDensity, type TableProps, type TableRow, TableToolbar, type TableToolbarActiveFilter, type TableToolbarFilterOption, Tabs, Tag, TagInput, type TagPaletteColor, type TagVariant, TextOverflow, type TextOverflowProps, Textarea, TimeBar, type TimeBarProps, TimePicker, TimeRow, type TimeRowProps, type TimeScale, TimeScaleHeader, type TimeScaleHeaderProps, type TimeScaleOptions, type TimeTick, TimeViewport, type TimeViewportHandle, type TimeViewportLayout, type TimeViewportProps, type TimeViewportState, type TimeZoom, Timeline, Toast, type ToastAction, type ToastApi, type ToastOptions, type ToastPosition, ToastProvider, type ToastVariant, Toggle, Tooltip, Tour, TransferList, TreeView, type Trend, type UseTextOverflowOptions, type UseTextOverflowResult, dateOfDay, dayOf, endDayOf, fitLabel, fitLabels, formatDateRange, timeExtent, useAppShell, useContentWidth, useDestructiveAction, useFittedLabels, useFormContext, useGridKeyboard, useSidebar, useTextMeasure, useTextOverflow, useTimeScale, useTimeViewport, useTimeViewportLayout, useToast, useToastOptional, useUnsavedChanges };