@box-kite/react 2.2.0 → 2.2.1

package/components/dataGrid/components/dataGridGroupRow.d.ts

@@ -4,10 +4,10 @@ interface Props<TRow> {
     /** Position in the whole row list, not in the rendered window. */
     index: number;
     /**
-     * The grid's store version. Not read: it is what tells the memo below that something the row draws
-     * from the model has moved, since every other prop it takes holds still while the window slides.
+     * This row's version (`GridModel.rowVersion`). Not read: it is what tells the memo below that something
+     * the row draws from the model has moved, since every other prop it takes holds still while the window slides.
      */
-    version: number;
+    version: string;
 }
 declare function DataGridGroupRowImpl<TRow>(props: Props<TRow>): import("react").JSX.Element;
 /**

package/components/dataGrid/components/dataGridHeader.d.ts

@@ -1,6 +1,10 @@
 import { default as GridModel } from '../models/gridModel';
 interface Props<TRow> {
     grid: GridModel<TRow>;
+    /** `GridModel.headerVersion`. Not read: it is what tells the memo below the header has something new to draw. */
+    version: string;
 }
-export default function DataGridHeader<TRow>(props: Props<TRow>): import("react").JSX.Element;
-export {};
+declare function DataGridHeaderImpl<TRow>(props: Props<TRow>): import("react").JSX.Element;
+/** Memoized, so a press that only moves the tab stop does not redraw the header and the filters under it. */
+declare const DataGridHeader: typeof DataGridHeaderImpl;
+export default DataGridHeader;

package/components/dataGrid/components/dataGridRow.d.ts

@@ -4,10 +4,10 @@ interface Props<TRow> {
     /** Position in the whole row list, not in the rendered window. */
     index: number;
     /**
-     * The grid's store version. Not read: it is what tells the memo below that something the row draws
-     * from the model has moved, since every other prop it takes holds still while the window slides.
+     * This row's version (`GridModel.rowVersion`). Not read: it is what tells the memo below that something
+     * the row draws from the model has moved, since every other prop it takes holds still while the window slides.
      */
-    version: number;
+    version: string;
 }
 declare function DataGridRowImpl<TRow>(props: Props<TRow>): import("react").JSX.Element;
 /**

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/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>[];
@@ -231,9 +255,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 +328,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/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;
@@ -54,6 +56,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,102 @@
+/**
+ * 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 column chooser's accessible name. */
+    columnsMenu: string;
+    columnsMenuSearchPlaceholder: string;
+    columnsMenuShowAll: string;
+    columnsMenuHideAll: 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/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;
+};