@box-kite/react 2.2.0 → 2.2.2

package/components/dataGrid/contracts/dataGridContract.d.ts

@@ -4,6 +4,7 @@ import { ComponentsAndVariants } from '../../../types';
 import { SortDirection } from '../../../utils/array/arrayUtils';
 import { default as AggregateCellModel } from '../models/aggregateCellModel';
 import { default as CellModel } from '../models/cellModel';
+import { DataGridLocaleText } from '../models/localeText';
 export type { SortDirection };
 export type Key = string | number;
 /**
@@ -589,10 +590,22 @@ export interface GridDefinition<TRow> {
     resizerStyle?: 'visible' | 'hover' | 'hidden';
     /** How the column follows the pointer during a resize drag. 'smooth' (default): updates batched once per animation frame (~60fps, ~1 frame behind the cursor). 'instant': updates synchronously on every pointer move so the column tracks the cursor with no added latency. */
     resizeMode?: 'smooth' | 'instant';
+    /**
+     * How a sortable header cell answers the pointer. `'static'` (default): each cell paints its own inset
+     * pill. `'sliding'`: one pill for the whole header that flows from cell to cell, leading with the edge it
+     * moves towards — measured, so it needs JavaScript, and reduced motion makes it jump instead.
+     */
+    headerHover?: 'static' | 'sliding';
     /** Control the header context menu for all columns. false hides it entirely. Object controls individual sections. Default: true. Individual column settings take priority. */
     contextMenu?: boolean | ContextMenuConfig;
     /** Custom component to render when data is empty */
     noDataComponent?: React.ReactNode;
+    /**
+     * Every word the grid writes itself — labels, accessible names, announcements, messages — for a
+     * translation or a house style. Any subset: what is left out stays English (`DATA_GRID_LOCALE_TEXT`).
+     * A value with something in it is a function, so a language can put the words in its own order.
+     */
+    localeText?: Partial<DataGridLocaleText>;
     /**
      * A row of grand totals pinned under the rows, over every column carrying an `aggregate`. It covers the
      * rows the grid holds after filtering — which is the page, not the table, when the server is paginating.

package/components/dataGrid/gridNavigationContext.d.ts

@@ -1,5 +1,6 @@
 import { ChangeDetails } from '../../react/a11y/useControllableState';
 import { RovingFocusItemProps, RovingFocusReason } from '../../react/a11y/useRovingFocus';
+import { default as ActiveCellStore } from '../../utils/dataGrid/activeCellStore';
 /**
  * The grid's keyboard coordinates, shared with every cell. Rows are numbered as `aria-rowindex` is —
  * headers, then the filter row, then the body — and a cell asks for its roving tabindex by that pair, so
@@ -12,8 +13,10 @@ export interface GridNavigation {
     columnCount: number;
     /** How many rows sit above the body — the offset from a body row's index to its row number. */
     headerRowCount: number;
-    /** The roving tabindex and the ref for one cell, in the coordinates above. */
-    cellProps: (row: number, column: number) => RovingFocusItemProps;
+    /** The ref and the focus handler for one cell, in the coordinates above. Stable: the tabindex is `activeCell`. */
+    cellProps: (row: number, column: number) => Omit<RovingFocusItemProps, 'tabIndex'>;
+    /** Which cell holds the tab stop. Subscribed to per cell, so a move re-renders two cells rather than all of them. */
+    activeCell: ActiveCellStore;
     /**
      * Move the tab stop to a cell without a keystroke having done it — what Tab out of an editor and into
      * the next editable cell moves. `'programmatic'` rather than `'keyboard'` on purpose: a keyboard move
@@ -30,3 +33,5 @@ declare const GridNavigationContext: import('react').Context<GridNavigation | nu
 export default GridNavigationContext;
 /** The grid navigation a cell belongs to. */
 export declare function useGridNavigationContext(): GridNavigation | null;
+/** One cell's roving tabindex, ref and focus handler — re-rendering the cell only when its own tabindex changes. */
+export declare function useGridCellProps(navigation: GridNavigation | null, row: number, column: number): Partial<RovingFocusItemProps>;

package/components/dataGrid/models/columnModel.d.ts

@@ -52,6 +52,8 @@ export default class ColumnModel<TRow> {
     get isLastLeaf(): boolean;
     get key(): Key;
     get header(): string | undefined;
+    /** The header group this column sits under, if any. A pinned half of a group is a copy with the same header. */
+    get group(): ColumnModel<TRow> | undefined;
     get align(): "center" | "left" | "right" | "start" | "end" | undefined;
     /** End-aligned either way it is spelled — `right` is the physical name of `end` in a left-to-right grid. */
     get isEndAligned(): boolean;

package/components/dataGrid/models/columnVisibilityModel.d.ts

@@ -3,12 +3,19 @@ import { default as GridModel } from './gridModel';
 export interface ColumnVisibilityEntry<TRow> {
     id: string;
     label: string;
+    /** The header group's text, when the column sits under one. */
+    group?: string;
     column: ColumnModel<TRow>;
     visible: boolean;
 }
+/** A run of entries under one header group, in column order. `group` is absent for ungrouped columns. */
+export interface ColumnVisibilitySection<TRow> {
+    group?: string;
+    entries: ColumnVisibilityEntry<TRow>[];
+}
 /**
- * Backs the top-bar column-visibility menu: the toggleable (user data) columns, which
- * are currently shown, and a diff-based bulk setter.
+ * Backs the top-bar columns panel: the toggleable (user data) columns, which are currently shown, the
+ * search over them, and a diff-based bulk setter.
  */
 export default class ColumnVisibilityModel<TRow> {
     readonly grid: GridModel<TRow>;
@@ -17,8 +24,15 @@ export default class ColumnVisibilityModel<TRow> {
     get entries(): ColumnVisibilityEntry<TRow>[];
     get selectedIds(): string[];
     get total(): number;
+    get visibleCount(): number;
     get hiddenCount(): number;
     get hasHidden(): boolean;
+    /** The entries whose label or group contains `query`, ignoring case and surrounding space. */
+    search(query: string): ColumnVisibilityEntry<TRow>[];
+    /** `entries` cut into consecutive runs that share a group, which is what the panel draws a heading over. */
+    sections(entries: ColumnVisibilityEntry<TRow>[]): ColumnVisibilitySection<TRow>[];
     /** Make exactly the columns in `ids` visible, toggling only those whose state must change. */
     setVisibility: (ids: string[]) => void;
+    /** Show or hide every column in `entries` (all of them by default), leaving the rest as they are. */
+    setAll: (visible: boolean, entries?: ColumnVisibilityEntry<TRow>[]) => void;
 }

package/components/dataGrid/models/editModel.d.ts

@@ -3,10 +3,6 @@ import { default as ColumnModel } from './columnModel';
 import { default as GridModel } from './gridModel';
 import { RangeBounds } from './rangeModel';
 import { default as RowModel } from './rowModel';
-/** What a rejection with no message of its own says. A silent refusal is one nobody can act on. */
-export declare const DEFAULT_EDIT_ERROR = "Invalid value";
-/** What a pasted value is refused with when it is not the kind of value the cell holds at all. */
-export declare const WRONG_KIND_ERROR = "Wrong kind of value";
 /** A key that starts an edit by replacing the value: one printable character, unmodified. */
 export declare function isTypingKey(event: React.KeyboardEvent): boolean;
 /**
@@ -22,6 +18,10 @@ export declare function isTypingKey(event: React.KeyboardEvent): boolean;
 export default class EditModel<TRow> {
     readonly grid: GridModel<TRow>;
     constructor(grid: GridModel<TRow>);
+    /** What a rejection with no message of its own says. A silent refusal is one nobody can act on. */
+    private get invalidValue();
+    /** A validator that threw is a refusal, and what it threw is the message. */
+    private errorText;
     /** The accepted values, keyed by cell. Cleared by `clearEdits()` and by a datasource refresh. */
     private readonly values;
     /** The cells the last paste was refused on. They keep the invalid ring, which is all a batch can show. */
@@ -36,6 +36,8 @@ export default class EditModel<TRow> {
     /** The editor a cell opens, worked out from the value in it when the column names none. */
     editorFor(column: ColumnModel<TRow>, value: unknown): CellEditorConfig<TRow>;
     isEditing(rowKey: Key, columnKey: Key): boolean;
+    /** Everything about this row the editor draws: which cell is open, what is in it and what it was told. */
+    rowDigest(rowKey: Key): string;
     /** Whether an editor is open anywhere. A Ctrl+V while one is belongs to the editor, not to the grid. */
     get isOpen(): boolean;
     /** Whether the last paste was refused on this cell, which is the only mark a batch of them can carry. */

package/components/dataGrid/models/exportModel.d.ts

@@ -47,6 +47,6 @@ export default class ExportModel<TRow> {
      * of its own to say — the same column it occupies on screen when that column is exported at all.
      */
     private footerRow;
-    /** The file's name, without an extension: what was asked for, else the grid's title, else `export`. */
+    /** The file's name, without an extension: what was asked for, else the grid's title, else `localeText.exportFileName`. */
     fileName(options?: DataGridExportOptions): string;
 }

package/components/dataGrid/models/gridModel.d.ts

@@ -9,6 +9,7 @@ import { default as EditModel } from './editModel';
 import { default as ExportModel } from './exportModel';
 import { default as FilterModel } from './filterModel';
 import { default as GroupRowModel } from './groupRowModel';
+import { DataGridLocaleText } from './localeText';
 import { default as PaginationModel } from './paginationModel';
 import { default as RangeModel } from './rangeModel';
 import { default as RowModel } from './rowModel';
@@ -25,8 +26,27 @@ export default class GridModel<TRow> {
     subscribe: (listener: () => void) => (() => void);
     /** Monotonic snapshot version — stable between changes, increments on notify(). */
     getSnapshot: () => number;
-    /** Signal subscribers that state changed and a re-render is needed. */
+    private static drawnPropsChanged;
+    /** Bumped by a change every row draws from — a sort, a filter, the columns — and by nothing row-local. */
+    private _epoch;
+    /** Signal subscribers that state changed and a re-render is needed. Every rendered row redraws. */
     notify: () => void;
+    /**
+     * A change that `rowVersion` sees row by row — a selection, the current cell, a keystroke in an editor —
+     * so only the rows whose version moved redraw, rather than every row on screen (bug #237).
+     */
+    notifyRows: () => void;
+    /**
+     * What a rendered row's memo compares: the grid-wide epoch plus the row's own state. A `Cell` of your own
+     * that reads something outside its row redraws on a grid-wide change, not on another row's selection.
+     */
+    rowVersion(row: RowModel<TRow> | GroupRowModel<TRow> | DetailRowModel<TRow>, index: number): string;
+    private _selectionVersion;
+    /**
+     * What the memoized header compares: a grid-wide change, or the selection its checkbox shows. A focus move
+     * re-renders the component holding the tab stop, and the header — filter row included — no longer with it.
+     */
+    get headerVersion(): string;
     /**
      * Sync incoming props. Called during render by the framework adapter — clears
      * the affected memos but does NOT notify (no extra render cycle; memos recompute
@@ -56,6 +76,10 @@ export default class GridModel<TRow> {
     get titleId(): string;
     get resizerStyle(): 'visible' | 'hover' | 'hidden';
     get resizeMode(): 'smooth' | 'instant';
+    get headerHover(): 'static' | 'sliding';
+    private _localeText?;
+    /** The grid's words: `def.localeText` over the English defaults, merged once per object it is given. */
+    get localeText(): DataGridLocaleText;
     readonly sourceColumns: import('../../../utils/memo').Memo<ColumnModel<TRow>[]>;
     readonly columns: import('../../../utils/memo').Memo<{
         start: ColumnModel<TRow>[];
@@ -155,6 +179,11 @@ export default class GridModel<TRow> {
     private _sizingElement;
     get sizingElement(): HTMLElement | null;
     setSizingElement: (el: HTMLElement | null) => void;
+    /**
+     * Writes the width variables straight onto the sizing element, ahead of the render that will agree with
+     * them: a resize drag repaints without re-rendering every row, and a new scroller width lands before paint.
+     */
+    paintSizes: () => void;
     /**
      * Which way the grid reads, resolved off the element the widths are written to. A model with no
      * element yet — a server render, a headless host — reads as left to right, the initial value.
@@ -231,9 +260,34 @@ export default class GridModel<TRow> {
     /** Whether any user-facing column is currently visible (else the empty-columns state shows). */
     get hasVisibleColumns(): boolean;
     get isEmpty(): boolean;
-    /** Header select-all checkbox state. */
+    /**
+     * The rows the header checkbox acts on: what the filters leave on screen. A select-all reaching rows
+     * nobody can see is a bulk action on rows nobody chose; with a datasource it is the blocks it holds.
+     */
+    get selectableRows(): TRow[];
+    /** The keys of `selectableRows`. A datasource's grow as blocks arrive, so only the client side is kept. */
+    private readonly _selectableKeys;
+    private get selectableKeys();
+    private _selectionCounts?;
+    /** How many selected rows are on screen — read by the header and the footer on every render, so kept. */
+    private get shownSelectedCount();
+    /** Header select-all checkbox state: every row on screen is selected, whatever the filters hide. */
     get allRowsSelected(): boolean;
     get someRowsSelected(): boolean;
+    /**
+     * Selected rows the filters hide. A filter never drops a selection, so the footer says what it is
+     * keeping out of sight; a server's rows are unknown until fetched, so there it is never counted.
+     */
+    get hiddenSelectedCount(): number;
+    /** The keys "Show selected" froze when it was pressed, so a row unticked in that view stays put. */
+    private _selectionView;
+    get isSelectionView(): boolean;
+    /** Only the grid's own filtering can be set aside; a server's or a tree's cannot. */
+    get canShowSelection(): boolean;
+    /** "Show selected" sets the filters aside rather than adding to them: the rows it is for are the hidden ones. */
+    toggleSelectionView: () => void;
+    /** A filter typed while viewing the selection is a new question, so the view gives way to it. */
+    private leaveSelectionView;
     private _selectionAnnounced;
     /**
      * What the grid's live region says. Ticking a checkbox halfway down a virtualized grid changes nothing a
@@ -279,7 +333,11 @@ export default class GridModel<TRow> {
     toggleRowSelection: (rowKey: Key) => void;
     /** `all` is the header checkbox rather than a count: a group covering every row is still not select-all. */
     toggleRowsSelection: (rowKeys: Key[], all?: boolean) => void;
+    /** Ticks or clears the rows on screen only — selected rows the filters hide are left as they are. */
     toggleSelectAllRows: () => void;
+    /** Every row, hidden ones included: the footer's way out of a selection the filters keep half out of sight. */
+    clearSelection: () => void;
+    private selectionChanged;
     toggleColumnVisibility: (columnKey: Key) => void;
     setWidth: (columnKey: Key, width: number) => void;
     private _groupColumns?;

package/components/dataGrid/models/groupRowModel.d.ts

@@ -31,14 +31,14 @@ export default class GroupRowModel<TRow> {
     aggregateValue(_column: ColumnModel<TRow>): AggregateValue | undefined;
     get key(): Key;
     parentRow?: GroupRowModel<TRow>;
-    private readonly _cells;
+    private _cells?;
     get cells(): GroupRowCellModel<TRow>[];
+    private cellCache;
     /**
      * The cells this row actually renders, each with the column it starts at. A `hidden` cell is a
      * data column the grouping cell has absorbed into its span: no element, and nothing to navigate
      * to — which is why a group row's cell positions and its `aria-colindex` values differ.
      */
-    private readonly _renderedCells;
     get renderedCells(): {
         cell: GroupRowCellModel<TRow>;
         columnIndex: number;

package/components/dataGrid/models/headerCellModel.d.ts

@@ -14,6 +14,8 @@ export default class HeaderCellModel<TRow> {
      */
     get hiddenLabel(): string | undefined;
     get isSortable(): boolean;
+    /** Whether the cell paints its own hover pill: under `'sliding'` the header draws one for every cell. */
+    get hasHoverPill(): boolean;
     get isSorted(): boolean;
     get sortDirection(): SortDirection | undefined;
     get showResizer(): boolean;
@@ -33,6 +35,11 @@ export default class HeaderCellModel<TRow> {
     get ariaSort(): 'ascending' | 'descending' | 'none' | undefined;
     /** What the resizer names itself. A separator carries no text, so it has nothing else to go on. */
     get resizerLabel(): string;
+    /**
+     * Whether this header ends where the grid does. A resizer straddling that edge overhangs the scroller,
+     * which made every grid whose columns exactly fit scroll sideways by 3px.
+     */
+    get isAtGridEnd(): boolean;
     /** `aria-valuenow`: how wide the column is right now, in px. */
     get width(): number;
     /** `aria-valuemin`: every leaf the header covers at the narrowest the grid allows. */
@@ -54,6 +61,9 @@ export default class HeaderCellModel<TRow> {
         isFirstEndPinned: boolean;
         isLastEndPinned: boolean;
         isSortable: boolean;
+        hasHoverPill: boolean;
+        isPillBeforeResizer: boolean;
+        isPillAfterResizer: boolean;
         isRowNumber: boolean;
         isFirstLeaf: boolean;
         isLastLeaf: boolean;

package/components/dataGrid/models/localeText.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Every word the grid writes itself — visible text, accessible names, announcements and messages. A value
+ * with something in it is a function, because word order and plurals differ between languages and a
+ * sentence glued from pieces cannot be translated. Override any subset through `def.localeText`.
+ */
+export interface DataGridLocaleText {
+    /** The global search box's placeholder. */
+    searchPlaceholder: string;
+    /** The columns button's text and the panel's accessible name. */
+    columnsMenu: string;
+    /** The button's accessible name while some columns are hidden — it has to start with `columnsMenu`. */
+    columnsMenuLabel: (shown: number, total: number) => string;
+    columnsMenuSearchPlaceholder: string;
+    columnsMenuShowAll: string;
+    columnsMenuHideAll: string;
+    /** The count above the list: "6 of 8 shown". */
+    columnsMenuShown: (shown: number, total: number) => string;
+    /** What the list says when the search matches no column. */
+    columnsMenuNoMatch: (query: string) => string;
+    /** The ✕ on a grouped column's chip. */
+    stopGrouping: (column: string) => string;
+    /** The export buttons' visible text, and their accessible names. */
+    exportCsv: string;
+    exportCsvLabel: string;
+    exportExcel: string;
+    exportExcelLabel: string;
+    /** The exported file's name when there is no `fileName` and no string `title`. */
+    exportFileName: string;
+    selectAllRows: string;
+    /** The hidden names of the row-number and row-detail columns, which draw no header text. */
+    rowNumberHeader: string;
+    rowDetailHeader: string;
+    /** The grouping column's header when more than one column is grouped. */
+    groupHeader: string;
+    columnOptions: (column: string) => string;
+    resizeColumn: (column: string) => string;
+    /** A resizer's `aria-valuetext`. */
+    columnWidth: (pixels: number) => string;
+    sortAscending: string;
+    sortDescending: string;
+    clearSort: string;
+    /** The pin items name a screen side, so a right-to-left page swaps them. */
+    pinLeft: string;
+    pinRight: string;
+    unpin: string;
+    groupBy: (column: string) => string;
+    ungroupAll: string;
+    filterPlaceholder: string;
+    filterColumn: (column: string) => string;
+    clearFilter: (column: string) => string;
+    filterComparison: (column: string) => string;
+    filterValuePlaceholder: string;
+    filterFromPlaceholder: string;
+    filterToPlaceholder: string;
+    filterFrom: (column: string) => string;
+    filterTo: (column: string) => string;
+    filterSelectPlaceholder: string;
+    filterSelectSearchPlaceholder: string;
+    filterSelectClear: string;
+    filterSelectAll: string;
+    /** How a multiselect filter lists a `null` value. */
+    filterEmptyValue: string;
+    /** What an empty grid shows when there is no `noDataComponent`. */
+    noRows: string;
+    loadingRows: string;
+    selectRow: (rowNumber: number) => string;
+    selectGroupRows: (group: string) => string;
+    expandRowDetail: (rowNumber: number) => string;
+    collapseRowDetail: (rowNumber: number) => string;
+    expandTreeRow: (name: string) => string;
+    collapseTreeRow: (name: string) => string;
+    /** What a tree row with no value of its own is called in its expander's name. */
+    unnamedRow: (rowNumber: number) => string;
+    editCell: (column: string) => string;
+    /** A refused edit with no message of its own. */
+    invalidValue: string;
+    /** A pasted value the column cannot read, such as text in a number column. */
+    wrongKindOfValue: string;
+    /** The totals row's label when `def.footer` has none. */
+    footerTotal: string;
+    noColumnsTitle: string;
+    noColumnsDescription: string;
+    /** A failed fetch whose error carries no message. */
+    loadError: string;
+    retry: string;
+    rowCount: (filtered: number, total: number) => string;
+    pageRowRange: (start: number, end: number, total: number) => string;
+    /** `hidden` is how many selected rows the filters keep off screen. */
+    selectedCount: (selected: number, hidden: number) => string;
+    clearFilters: string;
+    /** A toggle: it shows the selected rows whatever the filters say, and pressing it again shows the rest. */
+    showSelected: string;
+    clearSelection: string;
+    rowsPerPage: string;
+    /** An entry in the page-size list. */
+    pageSizeOption: (size: number) => string;
+    pageNumber: string;
+    /** The text after the page box: "of 12". */
+    pageCount: (totalPages: number) => string;
+    firstPage: string;
+    previousPage: string;
+    nextPage: string;
+    lastPage: string;
+    /** What the live region says when the selection changes. */
+    selectionAnnouncement: (selected: number, total: number) => string;
+}
+/** The grid's own words, in English. Spread it to start a translation: `{ ...DATA_GRID_LOCALE_TEXT, clearFilters: 'Rensa filter' }`. */
+export declare const DATA_GRID_LOCALE_TEXT: DataGridLocaleText;

package/components/dataGrid/models/rangeModel.d.ts

@@ -57,6 +57,8 @@ export default class RangeModel<TRow> {
     isCurrent(row: number, column: number): boolean;
     /** Whether the cell is part of a marked block. A single current cell is the cursor, not a selection. */
     isSelected(row: number, column: number): boolean;
+    /** Everything about this body row the range draws: the current column, the block's columns, and a drag. */
+    rowDigest(row: number): string;
     /**
      * Put the current cell here. `extend` keeps the anchor where it is, which is what makes Shift+arrow and
      * a drag grow a rectangle instead of moving a cursor.

package/components/dataGrid/models/rowModel.d.ts

@@ -29,7 +29,7 @@ export default class RowModel<TRow> {
     /** Whether clicking the row toggles its detail panel. */
     get expandOnRowClick(): boolean;
     toggleDetail: () => void;
-    private readonly _cells;
+    private _cells?;
     get cells(): CellModel<TRow>[];
     /** One cell per visible column — the width the grid navigation sees for this row. */
     get cellCount(): number;

package/components/dataGrid/useFilterDraft.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A debounced input over a value the grid owns. When the grid's value changes to something the draft does
+ * not already say — "Clear filters" in the footer, a controlled prop — the draft takes it and any pending
+ * commit is dropped; a copy read once at mount kept showing a filter that was gone.
+ */
+export default function useFilterDraft<T>(committed: T, matches: (committed: T) => boolean, adopt: (committed: T) => void): {
+    debounce: (key: string, commit: () => void) => void;
+    cancel: () => void;
+};