@gridkitjs/react 0.3.1 → 0.5.0

package/README.md

@@ -29,8 +29,12 @@ const columns: readonly ColumnDefinition<Row>[] = [
 <DataGridComponent
   dataSource={rows}
   columns={columns}
+  getRowId={(row) => String(row.Id)}
+  label="Application costs"
   resizableColumns
   resizeMode="fit"
+  selectable={{ rows: "multiple", cells: "single" }}
+  onRowSelectionChange={({ selected }) => persist(selected)}
 />;
 ```
 
@@ -39,6 +43,16 @@ drives its default alignment. With `resizableColumns`, a column edge can be
 dragged to resize or double-clicked to fit its content. `resizeMode="fit"`
 keeps columns filling the grid; `"fixed"` lets each keep its own width.
 
+`selectable` says which parts of the grid the user may select and how many of
+each — `false`, `"single"` or `"multiple"` per member, off by default. Click
+replaces, Ctrl-click toggles, Shift-click takes a range, and thirteen callbacks
+report it with the resolved row, column or cell value rather than a bare id.
+Give `getRowId` alongside it for data that sorts, filters or pages.
+
+The grid is an ARIA grid: one tab stop, with the arrow keys moving cell to cell
+within it, `Ctrl+Arrow` reordering a column and `Alt+Arrow` resizing one. Name
+it with `label`, or a screen reader announces only "grid".
+
 Requires React 19.
 
 Full documentation: [github.com/blagojablazhevski/gridkit](https://github.com/blagojablazhevski/gridkit#readme)

package/dist/index.d.ts

@@ -1,7 +1,34 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { ColumnDefinition as ColumnDefinition$1, ColumnSizingState, ColumnOrderState, ColumnSizeDefaults, ColumnResizeEvent, ColumnOrderEvent, ResolvedColumn as ResolvedColumn$1 } from '@gridkitjs/core';
-export { CellTemplateContext, ColumnResizeEvent, ColumnSizeDefaults, ColumnSizingState } from '@gridkitjs/core';
+import { RowSelectEvent, RowsSelectEvent, RowSelectionChangeEvent, CellSelectEvent as CellSelectEvent$1, CellSelectionChangeEvent as CellSelectionChangeEvent$1, ColumnDefinition as ColumnDefinition$1, ColumnSelectEvent as ColumnSelectEvent$1, ColumnSelectionChangeEvent as ColumnSelectionChangeEvent$1, ColumnsSelectEvent as ColumnsSelectEvent$1, SelectableConfig, SelectionState, CellSelectionState, ColumnSizingState, ColumnOrderState, ColumnSizeDefaults, ColumnResizeEvent, ColumnOrderEvent, ColumnSortState, ColumnSortEvent, FilterState, ResolvedColumn as ResolvedColumn$1, SelectedCell as SelectedCell$1, SelectedColumn as SelectedColumn$1 } from '@gridkitjs/core';
+export { CellSelectionMode, CellSelectionState, CellTemplateContext, ColumnResizeEvent, ColumnSizeDefaults, ColumnSizingState, ResolvedRow, RowSelectEvent, RowSelectionChangeEvent, RowsSelectEvent, SelectableConfig, SelectedCellRef, SelectionMode, SelectionState } from '@gridkitjs/core';
+
+/**
+ * Reported as the user selects. Every one of these is fanned out from a single
+ * diff of the transition it describes, so no two can disagree about what one
+ * interaction did.
+ */
+interface SelectionCallbacks<Row> {
+    /** Called once per row newly selected. The last call names the last row. */
+    onRowSelect?: ((event: RowSelectEvent<Row>) => void) | undefined;
+    /** Called once with every row one interaction selected. */
+    onRowsSelect?: ((event: RowsSelectEvent<Row>) => void) | undefined;
+    onRowDeselect?: ((event: RowSelectEvent<Row>) => void) | undefined;
+    onRowsDeselect?: ((event: RowsSelectEvent<Row>) => void) | undefined;
+    /**
+     * Called once per change with what it added, what it removed and everything
+     * selected after it — the one to persist from.
+     */
+    onRowSelectionChange?: ((event: RowSelectionChangeEvent<Row>) => void) | undefined;
+    onColumnSelect?: ((event: ColumnSelectEvent<Row>) => void) | undefined;
+    onColumnsSelect?: ((event: ColumnsSelectEvent<Row>) => void) | undefined;
+    onColumnDeselect?: ((event: ColumnSelectEvent<Row>) => void) | undefined;
+    onColumnsDeselect?: ((event: ColumnsSelectEvent<Row>) => void) | undefined;
+    onColumnSelectionChange?: ((event: ColumnSelectionChangeEvent<Row>) => void) | undefined;
+    onCellSelect?: ((event: CellSelectEvent<Row>) => void) | undefined;
+    onCellDeselect?: ((event: CellSelectEvent<Row>) => void) | undefined;
+    onCellSelectionChange?: ((event: CellSelectionChangeEvent<Row>) => void) | undefined;
+}
 
 /**
  * A column whose header and cells may render arbitrary React content.
@@ -11,6 +38,21 @@ export { CellTemplateContext, ColumnResizeEvent, ColumnSizeDefaults, ColumnSizin
 type ColumnDefinition<Row> = ColumnDefinition$1<Row, ReactNode>;
 /** A column paired with the width it renders at. */
 type ResolvedColumn<Row> = ResolvedColumn$1<Row, ReactNode>;
+/**
+ * The selection payloads, bound to React's node type for the same reason
+ * `ColumnDefinition` is: they carry a resolved column, whose label is whatever
+ * a `headerTemplate` returned.
+ *
+ * The row payloads name no node type at all and so are re-exported from
+ * `@gridkitjs/core` as they are.
+ */
+type SelectedColumn<Row> = SelectedColumn$1<Row, ReactNode>;
+type SelectedCell<Row> = SelectedCell$1<Row, ReactNode>;
+type ColumnSelectEvent<Row> = ColumnSelectEvent$1<Row, ReactNode>;
+type ColumnsSelectEvent<Row> = ColumnsSelectEvent$1<Row, ReactNode>;
+type ColumnSelectionChangeEvent<Row> = ColumnSelectionChangeEvent$1<Row, ReactNode>;
+type CellSelectEvent<Row> = CellSelectEvent$1<Row, ReactNode>;
+type CellSelectionChangeEvent<Row> = CellSelectionChangeEvent$1<Row, ReactNode>;
 type Borders = "horizontal" | "vertical" | "all" | "none";
 /**
  * How a column's width relates to the grid's.
@@ -26,11 +68,39 @@ interface HoverableConfig {
     columns?: boolean;
     cells?: boolean;
 }
-interface DataGridProps<Row> {
+interface DataGridProps<Row> extends SelectionCallbacks<Row> {
     columns?: readonly ColumnDefinition<Row>[] | undefined;
     dataSource?: readonly Row[] | undefined;
+    /**
+     * A row's stable identity, for state keyed by it. Defaults to the row's
+     * position, which is enough for a static grid but ties that state to where a
+     * row sits rather than to the row — so anything sorting, filtering or paging
+     * its data should give one.
+     *
+     * Called for every row on every change to `dataSource`, so it should be
+     * cheap and stable; an inline arrow is fine, one that re-reads the data is
+     * not.
+     */
+    getRowId?: ((row: Row, index: number) => string) | undefined;
     borders?: Borders | undefined;
     hoverable?: HoverableConfig | undefined;
+    /**
+     * Which parts of the grid the user may select, and how many of each —
+     * `{ rows: "multiple", cells: "single" }`. A cell addresses one value, so it
+     * has no `"multiple"`.
+     *
+     * Off by default, unlike `hoverable`: selection claims the click, which a
+     * grid that only displays data should not do. Give `getRowId` alongside it
+     * for data that sorts, filters or pages, or a selection follows the position
+     * rather than the row.
+     */
+    selectable?: SelectableConfig | undefined;
+    /** Row ids selected to start with, keyed as `getRowId` resolves them. Uncontrolled. */
+    defaultRowSelection?: SelectionState | undefined;
+    /** Column ids selected to start with. Uncontrolled. */
+    defaultColumnSelection?: SelectionState | undefined;
+    /** The cell selected to start with. Uncontrolled. */
+    defaultCellSelection?: CellSelectionState | undefined;
     /** Whether columns can be dragged wider, unless a column says otherwise. */
     resizableColumns?: boolean | undefined;
     /**
@@ -68,7 +138,32 @@ interface DataGridProps<Row> {
      * the order as it was does not call it.
      */
     onColumnOrderChange?: ((event: ColumnOrderEvent) => void) | undefined;
+    /**
+     * Whether columns can be sorted by clicking their header toggle, unless a
+     * column says otherwise. Shift-click stacks a column into the sort instead
+     * of replacing it.
+     */
+    sortableColumns?: boolean | undefined;
+    /** The sort to start with, in priority order. Uncontrolled. */
+    defaultColumnSort?: ColumnSortState | undefined;
+    /**
+     * Called once when the user changes the sort — a toggle, a stack, or a
+     * clear back to "none".
+     */
+    onColumnSortChange?: ((event: ColumnSortEvent) => void) | undefined;
+    /** The filter to start with — every applied entry, ANDed together. Uncontrolled. */
+    defaultFilter?: FilterState<Row> | undefined;
+    /**
+     * The grid's accessible name, announced when it takes focus. A grid without
+     * one is read only as "grid", which says nothing about which grid.
+     */
+    label?: string | undefined;
+    /**
+     * The id of an element naming the grid, for a heading already on the page.
+     * Takes precedence over `label`, as `aria-labelledby` does.
+     */
+    labelledBy?: string | undefined;
 }
-declare function DataGridComponent<Row>({ dataSource, columns, borders, hoverable, resizableColumns, reorderableColumns, resizeMode, defaultColumnSizing, defaultColumnOrder, columnSizeDefaults, onColumnResize, onColumnOrderChange, }: DataGridProps<Row>): react.JSX.Element;
+declare function DataGridComponent<Row>({ dataSource, columns, getRowId, borders, hoverable, selectable, defaultRowSelection, defaultColumnSelection, defaultCellSelection, resizableColumns, reorderableColumns, resizeMode, defaultColumnSizing, defaultColumnOrder, columnSizeDefaults, onColumnResize, onColumnOrderChange, sortableColumns, defaultColumnSort, onColumnSortChange, defaultFilter, label, labelledBy, ...callbacks }: DataGridProps<Row>): react.JSX.Element;
 
-export { type ColumnDefinition, DataGridComponent, type DataGridProps, type ResizeMode, type ResolvedColumn };
+export { type CellSelectEvent, type CellSelectionChangeEvent, type ColumnDefinition, type ColumnSelectEvent, type ColumnSelectionChangeEvent, type ColumnsSelectEvent, DataGridComponent, type DataGridProps, type ResizeMode, type ResolvedColumn, type SelectedCell, type SelectedColumn };