@tensor_1/react 2.49.1 → 2.51.0

package/dist/components/DataWorkspace.d.ts

@@ -2,6 +2,7 @@ import * as react from 'react';
 import { HTMLAttributes, ReactNode } from 'react';
 import { UixRenderLink } from '../link.js';
 import { FilterField, FilterValue, SummarizeFilterOptions } from '../filter-model.js';
+import { PaginationLabels } from './Pagination.js';
 import { TableDensity } from './Table.js';
 import { SavedViewMenuProps, ViewMenuProps } from './TableControls.js';
 
@@ -37,6 +38,18 @@ interface DataWorkspaceLabels {
     filteredEmptyDetail: string;
     error: string;
     retry: string;
+    /** A sorted header's place among two or more sort keys (HAR-2623): `{n}`. */
+    sortPriority: string;
+    /** A group header's row count (HAR-2625): `{count}`. */
+    groupCount: string;
+    /** The same for one row. */
+    groupCountOne: string;
+    /** A group header's toggle while the group is open: `{name}`. */
+    collapseGroup: string;
+    /** The same while it is collapsed. */
+    expandGroup: string;
+    /** A group header's checkbox: `{name}`. */
+    selectGroup: string;
 }
 declare const DEFAULT_DATA_WORKSPACE_LABELS: DataWorkspaceLabels;
 interface DataWorkspaceColumn<T> {
@@ -48,23 +61,105 @@ interface DataWorkspaceColumn<T> {
     align?: 'start' | 'end';
     /** A CSS width for the column, e.g. `12rem`. */
     width?: string;
+    /**
+     * The column's floor, e.g. `14rem` (HAR-2624). In a fixed layout the table's own min-width is
+     * the sum of its columns' floors, so a squeezed table scrolls rather than narrow them.
+     */
+    minWidth?: string;
+    /**
+     * A class on the column's header and body cells, e.g. `uix-col--truncate` (HAR-2624). A width
+     * tier (`uix-col--w-md`) or `uix-col--flex` also sizes the column's `<col>` in a fixed layout.
+     */
+    className?: string;
+    /**
+     * The responsive ladder (`mobile`, HAR-2622): `low` columns go below 900 px of workspace width,
+     * `mid` ones below 600 px; `high` (the default) stay.
+     */
+    priority?: 'high' | 'mid' | 'low';
+    /** The column's name in words: a card's label under `mobile="cards"`. Default: `header` when it is a string. */
+    label?: string;
 }
 interface DataWorkspaceSort {
     columnId: string;
     direction: 'ascending' | 'descending';
 }
+/** `sort` as a product passes it: one key (or none), or an ordered list of keys (HAR-2623). */
+type DataWorkspaceSortState = DataWorkspaceSort | readonly DataWorkspaceSort[] | null;
+/** What `onSortChange` receives: a list when `sort` is a list, else one key or `null`. */
+type DataWorkspaceSortValue<S> = S extends readonly DataWorkspaceSort[] ? DataWorkspaceSort[] : DataWorkspaceSort | null;
 /** The record-id column: the first column, the row's way into its record. */
 interface DataWorkspaceIdColumn<T> {
     header: ReactNode;
     /** The id as shown, e.g. "INC-20418". Also names the row's checkbox and ↗ button. */
     text: (row: T) => string;
+    /**
+     * The cell's content instead of `text` (HAR-2622): e.g. a strong title over a muted line, with
+     * the search match marked. It sits inside the same button or link; `text` still names the
+     * checkbox and the ↗.
+     */
+    render?: (row: T) => ReactNode;
     /** The id button opens a peek of the record. */
     onPeek?: (row: T) => void;
     /** The ↗ link goes to the full record. */
     href?: (row: T) => string;
+    /**
+     * Without `onPeek`: the whole id is the link to `href`, with the ↗ inside it, for a row whose
+     * own record is the way in (HAR-2622). Off: the id is text and the ↗ is the link.
+     */
+    linkId?: boolean;
+    /** The column's width in a fixed layout (`fixed`), e.g. `16rem`. */
+    width?: string;
+    /** The column's floor in a fixed layout. Default: the `md` column tier. */
+    minWidth?: string;
+    /**
+     * The sort key the id column answers to in `sort` / `onSortChange` (HAR-2631), e.g. `title`
+     * when the id shows the title. Default `'id'`. Keep it distinct from the data columns' ids.
+     */
+    id?: string;
+    /**
+     * The id header sorts like a data column (HAR-2631): a click cycles it, Shift + click (or
+     * Shift + Enter / Space) adds it as a further key in a multi-sort, with its ordinal and
+     * `aria-sort`. Off: the header is plain, as in 2.50.0.
+     */
+    sortable?: boolean;
     renderLink?: UixRenderLink;
 }
-type DataWorkspacePagination = {
+/** A group of rows under one header row (HAR-2625). The product computes the groups. */
+interface DataWorkspaceGroup<T> {
+    id: string;
+    /** The group's value as shown, e.g. a status pill. */
+    label: ReactNode;
+    /** The group's name in words, for its toggle and checkbox. Default: `label` when a string, else `id`. */
+    name?: string;
+    rows: readonly T[];
+    /** The group's total, when it holds more than the rows on this page. Default: `rows.length`. */
+    count?: number;
+    /** Aggregated cells in the header row, by column id (a sum, a range), each under its column. */
+    aggregates?: Readonly<Record<string, ReactNode>>;
+}
+/** Where a row's actions are shown (HAR-2634), the second argument of `rowActions`. */
+interface DataWorkspaceRowActionsContext {
+    /** The ladder's step: `null` for the full table (or without `mobile`). */
+    ladder: 'cards' | 'priority' | 'priority-mid' | null;
+    /** The narrowest table step (`priority-mid`): render only the always-on control. Cards keep the full set, on a line of their own. */
+    compact: boolean;
+}
+/** Windowing for a long unpaged list (HAR-2626), over `useVirtualRows`. */
+interface DataWorkspaceVirtualize {
+    /** Window only above this many rows. Default 100. */
+    threshold?: number;
+    /** The first paint's row height in px; the mounted rows are measured after. Default: by density (44, 56, 68). */
+    estimatedRowHeight?: number;
+    /** The scrolling body's height cap in px. Default 640. */
+    maxHeight?: number;
+    /** Rows rendered beyond each edge. Default 8. */
+    overscan?: number;
+}
+/**
+ * The footer's pager. `labels` words the pager itself; without them it takes `UixLabelsProvider`
+ * `pagination`, then English (HAR-2631).
+ */
+type DataWorkspacePagination = ({
     mode: 'offset';
     page: number;
     pageSize: number;
@@ -83,38 +178,87 @@ type DataWorkspacePagination = {
     pageSize?: number;
     pageSizes?: readonly number[];
     onPageSizeChange?: (size: number) => void;
+}) & {
+    labels?: Partial<PaginationLabels>;
 };
-interface DataWorkspaceProps<T> extends Omit<HTMLAttributes<HTMLElement>, 'children'> {
+interface DataWorkspaceProps<T, S extends DataWorkspaceSortState = DataWorkspaceSort | null> extends Omit<HTMLAttributes<HTMLElement>, 'children'> {
     /** Names the workspace region and the table. */
     label: string;
     rows: readonly T[];
     getRowId: (row: T) => string;
+    /**
+     * A row's name in words, where the kit names a row (its checkbox, HAR-2632) and there is no
+     * `idColumn.text`: a title or a person, never a key. Without it the row id is used, which is
+     * a UUID on many tables. Keep it stable (`useCallback`), as rows are memoised.
+     */
+    rowLabel?: (row: T) => string;
     columns: readonly DataWorkspaceColumn<T>[];
     idColumn?: DataWorkspaceIdColumn<T>;
-    sort?: DataWorkspaceSort | null;
-    onSortChange?: (sort: DataWorkspaceSort | null) => void;
+    /**
+     * The sort: one key, or an ordered list of keys (HAR-2623). With a list, Shift + click (or
+     * Shift + Enter / Space) on a header adds, turns or removes that column as a further key, and
+     * each sorted header shows its place once two or more keys are set.
+     */
+    sort?: S;
+    /** Receives the same shape `sort` holds: a list for a list, else one key or `null`. */
+    onSortChange?: (sort: DataWorkspaceSortValue<S>) => void;
+    /**
+     * List mode even while `sort` is `null` or one key, for a product whose sort state starts
+     * empty. Type `sort` as a list (`[]` for none): `onSortChange` then receives a list.
+     */
+    multiSort?: boolean;
     /** The selected row ids. Kept by id, so a refresh or a new page keeps them. */
     selection?: ReadonlySet<string>;
     onSelectionChange?: (selection: Set<string>) => void;
+    /** At most this many rows can be selected: the unchecked boxes are disabled at the cap (HAR-2622). */
+    maxSelection?: number;
     /** The bulk bar's actions for the selection (a `Menu` for the overflow). */
     bulkActions?: (selectedIds: string[]) => ReactNode;
     /**
      * A row's actions (a `Menu`, quick buttons), in a column frozen at the right edge and sized to
      * them. Return `null` for a row without actions; with none on the page there is no column.
+     * The second argument says where the row is shown (HAR-2634): at the narrowest step of the
+     * ladder (`compact`, a workspace under 600 px with `mobile`), render only the always-on control,
+     * the peek or a kebab; the peek or the record carries the verbs. A frozen actions cell is for
+     * compact controls: word verbs (wider than a quarter of the table) unfreeze and scroll with
+     * their row, at any width.
      */
-    rowActions?: (row: T) => ReactNode;
+    rowActions?: (row: T, context: DataWorkspaceRowActionsContext) => ReactNode;
     /** More props for a row, e.g. a data attribute that marks it changed (see ChangeHighlight, PR #164). */
     getRowProps?: (row: T) => HTMLAttributes<HTMLTableRowElement> & Record<`data-${string}`, string | undefined>;
     density?: TableDensity;
+    /** Zebra rows (the `Table` default, on). The View menu's toggle (HAR-2624). */
+    zebra?: boolean;
+    /**
+     * Freeze the first column without an id column; with selection the checkbox is frozen too
+     * (HAR-2624). With `mobile`, nothing is frozen from the narrowest step (under 600 px).
+     */
+    freezeFirstColumn?: boolean;
+    /**
+     * `table-layout: fixed` with a `<colgroup>` from the columns' widths and tiers, and the table's
+     * min-width at the sum of the columns' floors (TENSOR HAR-997), so a truncating column clips
+     * instead of growing. Default: on when a column has `className` or `minWidth`. Not in cards.
+     */
+    fixed?: boolean;
+    /**
+     * The responsive ladder, from the workspace's own width (HAR-2622): `priority` drops `low`
+     * columns below 900 px and `mid` ones below 600 px; `cards` turns the rows into cards below
+     * 768 px (each value labelled by its column) and drops low-priority columns up to 900 px.
+     */
+    mobile?: 'priority' | 'cards';
     /**
      * Toolbar: the search field. Ctrl/⌘ + / focuses it from inside the workspace, or from the page
-     * when nothing has focus and this is the page's first workspace.
+     * when nothing has focus and this is the page's first workspace. `onSubmit` (Enter), `onClear`
+     * (the × or Escape) and `maxLength` go to the `SearchBar`.
      */
     search?: {
         value: string;
         onChange: (value: string) => void;
         label?: string;
         placeholder?: string;
+        onSubmit?: (value: string) => void;
+        onClear?: () => void;
+        maxLength?: number;
     };
     /**
      * Toolbar: filter chips and "+ Filter" over `FilterEditor`. A chip whose value holds ids
@@ -127,11 +271,24 @@ interface DataWorkspaceProps<T> extends Omit<HTMLAttributes<HTMLElement>, 'child
         /** Rows matching each filter, shown on its chip. */
         counts?: Readonly<Record<string, number>>;
         summary?: SummarizeFilterOptions;
+        /**
+         * Clear every filter in one change (HAR-2622), instead of one `onChange` per field: a product
+         * whose state is the URL would otherwise navigate once per field from the same stale state.
+         * `search: true` from "Nothing matches" while searching: clear the search too (the kit then
+         * does not call `search.onChange('')`).
+         */
+        onClearAll?: (scope: {
+            search: boolean;
+        }) => void;
     };
-    /** Toolbar: the saved-view trigger, named by the current view, opening a `SavedViewMenu`. */
+    /**
+     * Toolbar: the saved-view trigger, named by the current view, opening a `SavedViewMenu`.
+     * `note` sits above the list ("Saved views could not be loaded").
+     */
     savedViews?: {
         current: ReactNode;
         menu: SavedViewMenuProps;
+        note?: ReactNode;
     };
     /** Toolbar: the View button, opening a `ViewMenu` (columns, density). */
     viewMenu?: ViewMenuProps;
@@ -139,17 +296,63 @@ interface DataWorkspaceProps<T> extends Omit<HTMLAttributes<HTMLElement>, 'child
     viewChanged?: boolean;
     onSaveView?: () => void;
     onSaveViewAs?: () => void;
+    /** When Save as shows: `changed` (default) with `viewChanged`; `always`, to keep any view under a name (HAR-2622). */
+    saveViewAs?: 'changed' | 'always';
     /** Toolbar: a maximize toggle; Escape restores, unless an open popover or menu takes it first. */
     maximized?: boolean;
     onMaximizedChange?: (maximized: boolean) => void;
     /** Toolbar: the product's own actions at the end ("New incident"). */
     toolbarEnd?: ReactNode;
+    /** Between the toolbar (and bulk bar) and the rows: notices, a "3 new — show" pill, a truncation warning. */
+    beforeBody?: ReactNode;
     pagination?: DataWorkspacePagination;
     /** `loading`: the first load (skeleton rows). `error`: with `onRetry`. */
     status?: 'ready' | 'loading' | 'error';
     /** A refetch (filter, sort, page, saved view): the rows stay under `TableWrap refreshing`. */
     refreshing?: boolean;
     onRetry?: () => void;
+    /** Skeleton rows on a first load. Default 6. */
+    loadingRows?: number;
+    /** The empty body in place of the default one (HAR-2624), e.g. an `EmptyState` with the first action. */
+    empty?: ReactNode;
+    /** The default empty body's action ("Add the first book"). */
+    emptyAction?: ReactNode;
+    /** The filtered-empty body in place of the default one. */
+    filteredEmpty?: ReactNode;
+    /** A further action in the default filtered-empty body, after its Clear filters. */
+    filteredEmptyAction?: ReactNode;
+    /** The error body in place of the default one (a problem's title, a diagnostic line, Retry). */
+    error?: ReactNode;
+    /**
+     * A product state in place of the rows, whatever `status` says (a page past the end: "Go to the
+     * first page"). The toolbar stays; the footer goes. A refetch shows it busy.
+     */
+    stateOverride?: ReactNode;
+    /** Rows in groups under collapsible header rows, in place of `rows` (HAR-2625). Not windowed. */
+    groups?: readonly DataWorkspaceGroup<T>[];
+    /** The collapsed group ids. Without it the workspace keeps them itself. */
+    collapsedGroups?: ReadonlySet<string>;
+    /** A group was collapsed or opened: the new set of collapsed ids. */
+    onCollapsedGroupsChange?: (collapsed: Set<string>) => void;
+    /**
+     * Window a long unpaged list (HAR-2626): only the rows in view are mounted, in a body that
+     * scrolls under its sticky header. Off with `pagination`, `groups` and the cards ladder.
+     */
+    virtualize?: boolean | DataWorkspaceVirtualize;
+    /**
+     * The keyboard row model (HAR-2626): one row in the tab order, ↑ / ↓ / Home / End move between
+     * rows, Enter opens the row (`onRowActivate`, else its id: the peek or the link), Space does not
+     * scroll the page. Default: on with `onRowActivate`.
+     */
+    rowNavigation?: boolean;
+    /** A row's primary action: Enter on the row, and a click on the row (not on a control in it or its cell). Turns on `rowNavigation`. */
+    onRowActivate?: (row: T) => void;
+    /** `false`: only Enter activates a row, not a pointer click. Default `true`. */
+    activateOnClick?: boolean;
+    /** The row with the tab stop, to drive it from the product's own shortcuts (j / k). Changing it focuses that row. */
+    activeRowId?: string | null;
+    /** The tab stop moved to another row (a key, a click, focus entering a row). */
+    onActiveRowChange?: (rowId: string) => void;
     labels?: Partial<DataWorkspaceLabels>;
 }
 /**
@@ -161,7 +364,11 @@ interface DataWorkspaceProps<T> extends Omit<HTMLAttributes<HTMLElement>, 'child
  * footer with rows per page and `Pagination` (offset or cursor); first-load, empty,
  * filtered-empty and error states, and a refetch that keeps the rows. Prop-driven: the product
  * keeps its surface registry, URL state, data fetching and permissions.
+ *
+ * 2.50 (HAR-2622..2626, ADR-0005 addendum): a responsive ladder (`mobile`, `column.priority`), a
+ * rich id cell, multi-column sort, the product's state bodies and `beforeBody`, row groups,
+ * windowing (`virtualize`) and a keyboard row model (`onRowActivate`).
  */
-declare function DataWorkspace<T>({ label, rows, getRowId, columns, idColumn, sort, onSortChange, selection, onSelectionChange, bulkActions, rowActions, getRowProps, density, search, filters, savedViews, viewMenu, viewChanged, onSaveView, onSaveViewAs, maximized, onMaximizedChange, toolbarEnd, pagination, status, refreshing, onRetry, labels: labelOverrides, className, ...props }: DataWorkspaceProps<T>): react.JSX.Element;
+declare function DataWorkspace<T, S extends DataWorkspaceSortState = DataWorkspaceSort | null>({ label, rows, getRowId, rowLabel, columns, idColumn, sort, onSortChange, selection, onSelectionChange, maxSelection, bulkActions, rowActions, getRowProps, density, zebra, freezeFirstColumn, fixed, mobile, search, filters, savedViews, viewMenu, viewChanged, onSaveView, onSaveViewAs, saveViewAs, maximized, onMaximizedChange, toolbarEnd, beforeBody, pagination, status, refreshing, onRetry, loadingRows, empty, emptyAction, filteredEmpty, filteredEmptyAction, error, stateOverride, groups, collapsedGroups, onCollapsedGroupsChange, virtualize, rowNavigation, onRowActivate, activateOnClick, activeRowId, onActiveRowChange, multiSort, labels: labelOverrides, className, ...props }: DataWorkspaceProps<T, S>): react.JSX.Element;
 
-export { DEFAULT_DATA_WORKSPACE_LABELS, DataWorkspace, type DataWorkspaceColumn, type DataWorkspaceIdColumn, type DataWorkspaceLabels, type DataWorkspacePagination, type DataWorkspaceProps, type DataWorkspaceSort };
+export { DEFAULT_DATA_WORKSPACE_LABELS, DataWorkspace, type DataWorkspaceColumn, type DataWorkspaceGroup, type DataWorkspaceIdColumn, type DataWorkspaceLabels, type DataWorkspacePagination, type DataWorkspaceProps, type DataWorkspaceRowActionsContext, type DataWorkspaceSort, type DataWorkspaceSortState, type DataWorkspaceSortValue, type DataWorkspaceVirtualize };