@gridkitjs/react 0.9.0 → 0.11.0

package/README.md

@@ -12,7 +12,7 @@ pnpm add @gridkitjs/react
 
 ```tsx
 import { defineColumnsFromRows } from "@gridkitjs/core";
-import { DataGridComponent, type ColumnDefinition } from "@gridkitjs/react";
+import { DataGrid, type ColumnDefinition } from "@gridkitjs/react";
 
 const rows = [
   { Id: 1, Application: { Id: 9, Name: "Portal" }, Cost: 1250.5 },
@@ -23,10 +23,15 @@ type Row = (typeof rows)[number];
 
 const columns: readonly ColumnDefinition<Row>[] = [
   ...defineColumnsFromRows(rows),
-  { field: "Cost", id: "Cost.currency", type: "currency", header: "Cost" },
+  {
+    field: "Cost",
+    id: "Cost.currency",
+    type: "currency",
+    header: "Cost",
+  },
 ];
 
-<DataGridComponent
+<DataGrid
   dataSource={rows}
   columns={columns}
   getRowId={(row) => String(row.Id)}

package/dist/index.d.ts

@@ -1,34 +1,7 @@
 import * as react from 'react';
 import { ReactNode, Ref, RefObject } from 'react';
-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, ResolvedRow, DisplayRow, ResolvedColumn as ResolvedColumn$1, ColumnSizingState, ColumnOrderState, ColumnSortState, GroupByState, GroupExpansionState, PaginationState, AggregateResults, SelectionState, CellSelectionState, SelectableConfig, ColumnSizeDefaults, ColumnResizeEvent, ColumnOrderEvent, ColumnSortEvent, GroupByEvent, GroupExpansionEvent, FilterState, PaginationChangeEvent, AggregateState, GroupAggregateDisplay, 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;
-}
+import { CellSelectEvent as CellSelectEvent$1, CellSelectionChangeEvent as CellSelectionChangeEvent$1, ColumnDefinition as ColumnDefinition$1, ColumnSelectEvent as ColumnSelectEvent$1, ColumnSelectionChangeEvent as ColumnSelectionChangeEvent$1, ColumnsSelectEvent as ColumnsSelectEvent$1, DataColumn as DataColumn$1, GridOptions, PaginationState, SelectionCallbacks as SelectionCallbacks$1, ResolvedRow, DisplayRow, ResolvedColumn as ResolvedColumn$1, ColumnSizingState, ColumnOrderState, ColumnVisibilityState, ColumnSortState, FilterState, GroupByState, GroupExpansionState, AggregateResults, SelectionState, CellSelectionState, GridState, SerializedGridState, GridContextMenuTarget, GridCommandTarget, SelectedCell as SelectedCell$1, SelectedColumn as SelectedColumn$1 } from '@gridkitjs/core';
+export { Borders, CellSelectionMode, CellSelectionState, CellTemplateContext, ColumnResizeEvent, ColumnSizeDefaults, ColumnSizingState, ColumnVisibilityEvent, ColumnVisibilityState, ContextMenuOpenChangeEvent, FilterChangeEvent, FilterEntry, FilterState, GridCommand, GridCommandEvent, GridCommandTarget, GridContextMenuOptions, GridContextMenuRequest, GridContextMenuTarget, GridMessages, GridOptions, GridState, GridToolbarOptions, GroupByBarVisibility, HoverableConfig, MenuEntry, ResizeMode, ResolvedRow, RowPointerEvent, RowProps, RowSelectEvent, RowSelectionChangeEvent, RowsSelectEvent, SelectableConfig, SelectedCellRef, SelectionMode, SelectionState, SerializedGridState, ToolbarEntry, serializeGridState } from '@gridkitjs/core';
 
 /**
  * A column whose header and cells may render arbitrary React content.
@@ -38,6 +11,8 @@ interface SelectionCallbacks<Row> {
 type ColumnDefinition<Row> = ColumnDefinition$1<Row, ReactNode>;
 /** A column paired with the width it renders at. */
 type ResolvedColumn<Row> = ResolvedColumn$1<Row, ReactNode>;
+/** A column paired with its id, hidden or not — what `getDataColumns()` lists. */
+type DataColumn<Row> = DataColumn$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
@@ -53,17 +28,19 @@ 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 SelectionCallbacks<Row> = SelectionCallbacks$1<Row, ReactNode>;
 /**
- * Imperative handle for a mounted `DataGridComponent`, reached via its `ref`
- * prop. Read-plus-standard-actions: getters mirror the grid's live state,
- * and the actions are the ones every grid ref carries (focus, clear/select
- * all, scroll-to). Sizing, order, sort, and selection stay uncontrolled via
- * their existing `default*` props — this is not a second, imperative-only
- * way to drive that same state. `subscribe` doesn't change that: it's a
- * read/notify channel for reacting to state that already lives here, not a
- * write path — nothing becomes newly *driven* through the ref by its
- * existence. See `packages/react/src/DataGrid/hooks/` for the public hooks
- * built on it.
+ * Imperative handle for a mounted `DataGrid`, reached via its `ref` prop:
+ * the grid's DOM nodes, getters for its live state, the actions every grid
+ * ref carries (focus, select all, scroll-to), and a setter for every slice of
+ * state, for a toolbar, a saved layout or a test to drive it from outside.
+ *
+ * Every getter reads the grid's state at call time, so a read straight after
+ * an action sees its result. Every setter changes the grid as the user's own
+ * interaction would: it fires the slice's `on*Change` callback, and, for a
+ * slice held through a controlled prop, only asks. `subscribe` is the
+ * notify channel for state that changes; see
+ * `packages/react/src/DataGrid/hooks/` for the public hooks built on it.
  */
 interface DataGridApi<Row> {
     /** The grid's scrollable viewport element. */
@@ -83,11 +60,22 @@ interface DataGridApi<Row> {
      * when `groupBy` is empty.
      */
     getDisplayRows(): readonly DisplayRow<Row>[];
-    /** Columns as currently sized and ordered — what's rendered. */
+    /**
+     * The current page of `getDisplayRows()` — exactly the rows the body
+     * renders. All of `getDisplayRows()` when `paginated` is off.
+     */
+    getPageRows(): readonly DisplayRow<Row>[];
+    /** Columns as currently sized and ordered — what's rendered, so hidden columns are left out. */
     getColumns(): readonly ResolvedColumn<Row>[];
+    /** Every column in its current order, hidden ones included — what sorting, filtering and grouping read. */
+    getDataColumns(): readonly DataColumn<Row>[];
     getColumnSizing(): ColumnSizingState;
     getColumnOrder(): ColumnOrderState;
+    /** Columns shown or hidden since the grid mounted. A column absent from it follows its definition's `hidden`. */
+    getColumnVisibility(): ColumnVisibilityState;
     getColumnSort(): ColumnSortState;
+    /** The filter the rows are shown through — every entry, ANDed together. */
+    getFilter(): FilterState<Row>;
     getGroupBy(): GroupByState;
     getGroupExpansion(): GroupExpansionState;
     /** The active page and page size. Meaningful even when `paginated` is off — it stays at page 0 over the grid's whole (single) page. */
@@ -102,6 +90,12 @@ interface DataGridApi<Row> {
      */
     getAggregates(): AggregateResults;
     getRowSelection(): SelectionState;
+    /**
+     * The selected rows themselves, in the order they were selected — among
+     * every row the filter lets through, on any page or in any group, so a row
+     * filtered out while selected is left out until it is back.
+     */
+    getSelectedRows(): readonly ResolvedRow<Row>[];
     getColumnSelection(): SelectionState;
     getCellSelection(): CellSelectionState;
     /** The cell currently holding the grid's single tab stop. */
@@ -109,9 +103,29 @@ interface DataGridApi<Row> {
         rowIndex: number;
         columnIndex: number;
     };
+    /**
+     * Every slice of state as the grid applies it, in one object — what
+     * `restoreState` takes back. Pass it through `serializeGridState` before
+     * saving it as JSON.
+     */
+    getState(): GridState<Row>;
+    /**
+     * Puts back state saved earlier, whole or in part — from `getState()`, or
+     * from `serializeGridState` and back through JSON. Each slice given is set
+     * as its setter would set it, firing its callback when it changes; the
+     * grid re-renders once.
+     */
+    restoreState(saved: Partial<GridState<Row>> | Partial<SerializedGridState<Row>>): void;
     focusCell(rowIndex: number, columnIndex: number): void;
     clearSelection(): void;
     selectAllRows(): void;
+    /**
+     * Selects rows by id, as far as `selectable.rows` allows: `"replace"` (the
+     * default) selects exactly these — only the last of them under
+     * `"single"` — and `"toggle"` flips each one. Fires the row selection
+     * callbacks once for the whole call, and none when nothing changed.
+     */
+    selectRows(rowIds: readonly string[], intent?: "replace" | "toggle"): void;
     /** Expands every group at once — there is no dedicated UI control for it. */
     expandAllGroups(): void;
     /** Collapses every group currently shown at once — see `collapseAllGroups` in `@gridkitjs/core` for what "currently shown" means for a group already nested under a collapsed one. */
@@ -124,6 +138,84 @@ interface DataGridApi<Row> {
     previousPage(): void;
     /** Changes the page size, resetting to the first page. */
     setPageSize(pageSize: number): void;
+    /**
+     * Shows the columns with the given ids, each in the place it held when
+     * hidden. Reports one `onColumnVisibilityChange` for the whole call, and
+     * none if every column was already showing.
+     */
+    showColumns(columnIds: readonly string[]): void;
+    /**
+     * Hides the columns with the given ids. A hidden column still sorts,
+     * filters and groups, and keeps its place in the column order.
+     */
+    hideColumns(columnIds: readonly string[]): void;
+    /**
+     * Replaces the filter, the way a filter UI would, and sends an uncontrolled
+     * grid back to its first page. Reports one `onFilterChange`, and none when
+     * `filter` is equal to the current one. With a controlled `filter` prop it
+     * only asks, as any change does.
+     */
+    setFilter(filter: FilterState<Row>): void;
+    /**
+     * Replaces the sort. Reports one `onColumnSortChange`, naming the first
+     * column whose place or direction changed, and none for an equal sort —
+     * the rule every setter below follows for its own slice and callback.
+     */
+    setColumnSort(sort: ColumnSortState): void;
+    /** Replaces the group-by stack. Reports through `onGroupByChange`. */
+    setGroupBy(groupBy: GroupByState): void;
+    /** Replaces the collapsed groups. Reports through `onGroupExpansionChange` with `groupId: null`. */
+    setGroupExpansion(expansion: GroupExpansionState): void;
+    /** Replaces the page and page size as given. Reports through `onPaginationChange`. */
+    setPagination(pagination: PaginationState): void;
+    /** Replaces the column widths. Reports through `onColumnResize`, as the `"end"` of a resize. */
+    setColumnSizing(sizing: ColumnSizingState): void;
+    /** Replaces the column order. Reports through `onColumnOrderChange`. */
+    setColumnOrder(order: ColumnOrderState): void;
+    /** Replaces the column visibility state. Reports through `onColumnVisibilityChange`. */
+    setColumnVisibility(visibility: ColumnVisibilityState): void;
+    /** Replaces the selected row ids as given, whatever `selectable` allows. Fires the row selection callbacks. */
+    setRowSelection(selection: SelectionState): void;
+    /** Replaces the selected column ids as given. Fires the column selection callbacks. */
+    setColumnSelection(selection: SelectionState): void;
+    /** Replaces the selected cell as given, `null` for none. Fires the cell selection callbacks. */
+    setCellSelection(selection: CellSelectionState): void;
+    /**
+     * Sizes a shown column to fit its content, as double-clicking its resize
+     * handle does, reporting through `onColumnResize`. A hidden column, or one
+     * with no rows to measure, is left as it is.
+     */
+    autoFitColumn(columnId: string): void;
+    /**
+     * `autoFitColumn` for each of the given columns, or for every column shown
+     * when given none.
+     */
+    autoFitColumns(columnIds?: readonly string[]): void;
+    /**
+     * Opens the context menu `target` has, as a right-click there would —
+     * selecting it and focusing its cell first — beside `anchor`, a point in
+     * viewport coordinates or an element, or else below its cell. Says whether
+     * it opened: not for a target not on screen, nor where `contextMenu`
+     * gives no menu.
+     */
+    openContextMenu(target: GridContextMenuTarget, anchor?: {
+        readonly x: number;
+        readonly y: number;
+    } | Element): boolean;
+    /** Closes the context menu, if one is open. */
+    closeContextMenu(): void;
+    /**
+     * Opens the column chooser at the grid's top-end corner, in place of any
+     * panel open; it gives focus back to what had it when it closes.
+     */
+    openColumnChooser(): void;
+    /**
+     * Runs a command by id — a built-in or one of `commands` — on `target`,
+     * `{ area: "grid" }` when left out, when it is visible and enabled there.
+     * Reports it through `onCommand` with `source: "api"`, and says whether it
+     * ran.
+     */
+    runCommand(commandId: string, target?: GridCommandTarget): boolean;
     /** Scrolls the row with the given id into view, if it is currently shown. */
     scrollToRow(rowId: string, options?: ScrollIntoViewOptions): void;
     /** Scrolls the column with the given id into view. */
@@ -138,32 +230,7 @@ interface DataGridApi<Row> {
      */
     subscribe(listener: () => void): () => void;
 }
-type Borders = "horizontal" | "vertical" | "all" | "none";
-/**
- * How a column's width relates to the grid's.
- *
- * `"fit"` keeps the columns filling the grid: the space a column gives up is
- * handed to the others, and the space it takes comes out of them. `"fixed"`
- * lets every column keep its own width, so a resize moves one column and
- * nothing else, and the grid scrolls or leaves a gap accordingly.
- */
-type ResizeMode = "fit" | "fixed";
-/**
- * How the group-by bar's visibility follows the active grouping. `"always"`
- * renders it even with an empty `groupBy` — a fixed drop target and a
- * constant reminder grouping exists. `"never"` never renders it, for a grid
- * driving `groupBy` entirely by its own UI (a header toggle, `Alt+ArrowDown`)
- * or programmatically. `"auto"` renders it once `groupBy` is non-empty, or
- * while a header drag eligible to drop into it is in progress — so there is
- * always somewhere to drop the very first column, even from a fully empty
- * grouping.
- */
-type GroupByBarVisibility = "always" | "auto" | "never";
-interface HoverableConfig {
-    rows?: boolean;
-    columns?: boolean;
-    cells?: boolean;
-}
+
 /**
  * Everything a `pager.template` render prop needs to rebuild the built-in
  * pager's UI itself. Passed fresh on every render where pagination-relevant
@@ -215,151 +282,24 @@ interface InfiniteScrollConfig {
     /** Whether a load triggered by `onLoadMore` is still in flight. Suppresses further calls to it until this goes back to `false`. */
     readonly isLoadingMore?: boolean | undefined;
     /**
-     * `IntersectionObserver`'s `rootMargin` — how far from the bottom of the
-     * scrollable body `onLoadMore` fires, ahead of the sentinel actually
-     * scrolling into view. Defaults to `"200px"`.
+     * How far from the bottom of the scrollable body `onLoadMore` fires, ahead
+     * of the sentinel actually scrolling into view, as CSS margins — an
+     * intersection observer's `rootMargin`. Defaults to `"200px"`.
      */
     readonly rootMargin?: string | undefined;
-    /** Replaces the built-in "Loading more…" row. */
+    /** Replaces the built-in "Loading more…" row (`messages.loadingMore`). */
     readonly loadingTemplate?: (() => ReactNode) | undefined;
 }
-interface DataGridProps<Row> extends SelectionCallbacks<Row> {
+/**
+ * The props that name a React type, and so have no place in the
+ * framework-free `GridOptions`: columns whose templates return `ReactNode`,
+ * the pager and infinite-scroll configs whose templates do too, and the
+ * toolbar's custom entries.
+ */
+interface ReactRenderSlots<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;
-    /**
-     * Whether columns can be dragged into a new position, unless a column says
-     * otherwise. Turning it off leaves an order the user already made in place.
-     */
-    reorderableColumns?: boolean | undefined;
-    /**
-     * Whether columns fill the grid's width or sit at their own. Defaults to
-     * `"fit"`, under which columns the user has sized keep their width and the
-     * rest share what is left.
-     */
-    resizeMode?: ResizeMode | undefined;
-    /** Column widths to start from, keyed by column id. Uncontrolled. */
-    defaultColumnSizing?: ColumnSizingState | undefined;
-    /**
-     * Column ids in the order to start in. Uncontrolled, and partial: ids it
-     * omits keep their position among `columns` and follow those it lists.
-     */
-    defaultColumnOrder?: ColumnOrderState | undefined;
-    /**
-     * Sizes applied to columns that do not set their own — the width they start
-     * at and the bounds they may be resized between. Distinct from
-     * `defaultColumnSizing`, which sets specific columns' starting widths.
-     */
-    columnSizeDefaults?: Partial<ColumnSizeDefaults> | undefined;
-    /**
-     * Called as the user resizes a column. Fires continuously with
-     * `phase: "move"` and once on release with `phase: "end"` — the latter being
-     * the one to persist. Auto-fit does not call it; it reports user intent only.
-     */
-    onColumnResize?: ((event: ColumnResizeEvent) => void) | undefined;
-    /**
-     * Called once when the user drops a column somewhere new. A drop that leaves
-     * 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;
-    /**
-     * Whether columns can be grouped by — a header's click/`Alt+ArrowDown`
-     * toggle — unless a column says otherwise. The grouping itself still
-     * applies when this is off, via `defaultGroupBy` or the imperative API;
-     * this only gates that one interaction, the same way `sortableColumns`
-     * gates the sort toggle without disabling `defaultColumnSort`. Independent
-     * of `groupByBarVisibility` and `groupByDraggableColumns`, which gate the
-     * bar and the drag-in gesture respectively.
-     */
-    groupableColumns?: boolean | undefined;
-    /**
-     * Whether a groupable header shows its group-toggle icon, unless a column
-     * says otherwise. Purely a rendering choice: `Alt+ArrowDown` keeps working
-     * on a groupable header with the icon hidden.
-     */
-    groupToggleIconColumns?: boolean | undefined;
-    /**
-     * Whether a column's header may be dragged into the group-by bar to add
-     * it to the grouping, unless a column says otherwise. Independent of
-     * `groupableColumns`: a column can be groupable via its header's
-     * click/keyboard toggle, via this drag, both, or neither.
-     */
-    groupByDraggableColumns?: boolean | undefined;
-    /** How the group-by bar's visibility follows the active grouping. */
-    groupByBarVisibility?: GroupByBarVisibility | undefined;
-    /** The group-by stack to start with, outer to inner. Uncontrolled. */
-    defaultGroupBy?: GroupByState | undefined;
-    /**
-     * Called once when the user changes the group-by stack — adding, removing,
-     * or reordering a level.
-     */
-    onGroupByChange?: ((event: GroupByEvent) => void) | undefined;
-    /** Group keys collapsed to start with — every other group starts expanded. Uncontrolled. */
-    defaultGroupExpansion?: GroupExpansionState | undefined;
-    /** Called once when the user expands or collapses a group, or every group at once. */
-    onGroupExpansionChange?: ((event: GroupExpansionEvent) => void) | undefined;
-    /** The filter to start with — every applied entry, ANDed together. Uncontrolled. */
-    defaultFilter?: FilterState<Row> | undefined;
-    /**
-     * Whether the grid's rows are split into pages. A page's unit is a
-     * top-level group or a bare data row, never a leaf row — a group is never
-     * split across a page boundary. Off by default, matching `sortableColumns`.
-     */
-    paginated?: boolean | undefined;
-    /**
-     * The page and page size to start on. Uncontrolled. Defaults to
-     * `{ pageIndex: 0, pageSize: 25 }` when `paginated` is on and this is
-     * omitted.
-     */
-    defaultPagination?: PaginationState | undefined;
     /** Presentation options for the built-in pager. */
     pager?: PagerConfig | undefined;
-    /** Called once when the user changes the page or the page size. */
-    onPaginationChange?: ((event: PaginationChangeEvent) => void) | undefined;
     /**
      * Loads more rows as the user scrolls near the bottom, instead of paging.
      * Mutually exclusive with `paginated` — setting both logs a dev-time
@@ -368,68 +308,19 @@ interface DataGridProps<Row> extends SelectionCallbacks<Row> {
      * bound, so the mounted row count never grows with it either.
      */
     infiniteScroll?: InfiniteScrollConfig | undefined;
-    /**
-     * Aggregates to compute — a subtotal per group (rendered in that group's
-     * header) plus a grand total over the whole filtered/grouped dataset
-     * (rendered in a footer). Always computed over every row, never scoped to
-     * the current page. A plain controlled prop, unlike `sort`/`filter`/
-     * `groupBy`/`pagination`: there is no built-in UI for a user to add or
-     * remove an aggregate interactively, so there is no `defaultAggregates`/
-     * `onAggregatesChange` pair to go with it.
-     */
-    aggregates?: AggregateState<Row> | undefined;
-    /**
-     * Where a group's own aggregate results render. `"inline"` (the default)
-     * keeps them as text in the group header, next to its leaf-row count.
-     * `"row"` instead renders a dedicated row after that group's last visible
-     * entry, with each aggregate's value in the `<td>` for its own column —
-     * the same alignment the grand-total footer's own cells have. Has no
-     * effect when `aggregates` is empty or omitted.
-     */
-    groupAggregateDisplay?: GroupAggregateDisplay | undefined;
-    /**
-     * Bounds the row area's height, independently scrollable — the grid's own
-     * chrome (group-by bar, header, footer, pager) stays outside it and
-     * always visible. A number is pixels; a string is passed through as a CSS
-     * length (e.g. "60vh"). Omitted, the body's height stays content-driven,
-     * same as today.
-     */
-    height?: number | string | undefined;
-    /**
-     * Renders only the rows near the current scroll position rather than every
-     * row at once — for a dataset too large to mount in full. Requires
-     * `height` to be set; a grid without a bounded body has no viewport to
-     * window rows against (a dev-time console warning fires when it's
-     * missing). Off by default, matching every other opt-in behavior here.
-     */
-    virtualized?: boolean | undefined;
-    /**
-     * Rows rendered outside the visible range on each side, to reduce
-     * blank-frame flashes on fast scrolling. Only meaningful with `virtualized`
-     * on.
-     */
-    overscan?: number | undefined;
-    /**
-     * Assumed height for a row never yet measured — only matters for the very
-     * first paint and for `scrollToRow`'s initial jump before it corrects
-     * itself against that row's real, measured height. Only meaningful with
-     * `virtualized` on.
-     */
-    estimatedRowHeight?: number | 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;
+    /** Draws the toolbar's custom entries — `{ type: "custom", id }` — by id. */
+    renderToolbarItem?: ((id: string) => ReactNode) | undefined;
+}
+/**
+ * Every grid setting in `@gridkitjs/core`'s `GridOptions`, plus what only
+ * React can express: render slots, selection callbacks carrying React-bound
+ * columns, and the `ref`.
+ */
+interface DataGridProps<Row> extends GridOptions<Row>, ReactRenderSlots<Row>, SelectionCallbacks<Row> {
     /** Imperative handle for reading live grid state and triggering actions. */
     ref?: Ref<DataGridApi<Row>> | undefined;
 }
-declare function DataGridComponent<Row>({ dataSource, columns, getRowId, borders, hoverable, selectable, defaultRowSelection, defaultColumnSelection, defaultCellSelection, resizableColumns, reorderableColumns, resizeMode, defaultColumnSizing, defaultColumnOrder, columnSizeDefaults, onColumnResize, onColumnOrderChange, sortableColumns, defaultColumnSort, onColumnSortChange, groupableColumns, groupToggleIconColumns, groupByDraggableColumns, groupByBarVisibility, defaultGroupBy, onGroupByChange, defaultGroupExpansion, onGroupExpansionChange, defaultFilter, paginated, defaultPagination, pager, onPaginationChange, infiniteScroll, aggregates, groupAggregateDisplay, height, virtualized, overscan, estimatedRowHeight, label, labelledBy, ref, ...callbacks }: DataGridProps<Row>): react.JSX.Element;
+declare function DataGrid<Row>(props: DataGridProps<Row>): react.JSX.Element;
 
 interface PaginationStateApi {
     pagination: PaginationState;
@@ -440,7 +331,7 @@ interface PaginationStateApi {
     setPageSize: (pageSize: number) => void;
 }
 /**
- * Reactive pagination state read off a mounted `DataGridComponent`'s `ref`,
+ * Reactive pagination state read off a mounted `DataGrid`'s `ref`,
  * for building a pager entirely outside the grid's own DOM — a toolbar or
  * sidebar `pager.template` can't reach. Updates on every pagination change,
  * including the silent page-0 reset a filter/sort/group change triggers,
@@ -459,12 +350,12 @@ interface GroupByStateApi {
 }
 /**
  * Reactive group-by and group-expansion state read off a mounted
- * `DataGridComponent`'s `ref`, for a group-by bar or summary sidebar living
+ * `DataGrid`'s `ref`, for a group-by bar or summary sidebar living
  * outside the grid's own DOM.
  *
- * `DataGridApi` has no per-group toggle action today, only
- * `expandAllGroups`/`collapseAllGroups` — a custom group-by UI needing to
- * toggle a single group has no imperative action to call yet. A specific
+ * The ref's `setGroupBy` and `setGroupExpansion` change the grouping and the
+ * collapsed groups for a custom group-by UI; this hook carries only the
+ * all-at-once expansion actions. A specific
  * group's own computed aggregates are read off `getDisplayRows()`'s
  * per-header `aggregates` field instead of a getter here — see
  * `useAggregateState` for the grand-total equivalent.
@@ -475,12 +366,11 @@ interface GroupByStateApi {
 declare function useGroupByState<Row>(gridRef: RefObject<DataGridApi<Row> | null>): GroupByStateApi;
 
 /**
- * Reactive column-sort state read off a mounted `DataGridComponent`'s `ref`,
+ * Reactive column-sort state read off a mounted `DataGrid`'s `ref`,
  * for a sort indicator living outside the grid's own DOM.
  *
- * `DataGridApi` has no sort-mutating action today — sort stays uncontrolled
- * via `defaultColumnSort`/the grid's own header UI, the same gap
- * `useGroupByState` has for group-by. Reads only.
+ * Reads only; change the sort through the ref's `setColumnSort`, or hold it
+ * yourself with the controlled `columnSort` prop.
  *
  * Before the grid mounts, reads as an empty array.
  */
@@ -495,7 +385,7 @@ interface SelectionStateApi {
 }
 /**
  * Reactive row/column/cell selection state read off a mounted
- * `DataGridComponent`'s `ref`, for a "N rows selected" toolbar living
+ * `DataGrid`'s `ref`, for a "N rows selected" toolbar living
  * outside the grid's own DOM. One combined hook rather than three, matching
  * how `useGridSelection` already treats all three as one concern
  * internally.
@@ -507,7 +397,7 @@ declare function useSelectionState<Row>(gridRef: RefObject<DataGridApi<Row> | nu
 
 /**
  * Reactive grand-total aggregate results read off a mounted
- * `DataGridComponent`'s `ref`, for a summary footer or bar living outside
+ * `DataGrid`'s `ref`, for a summary footer or bar living outside
  * the grid's own DOM — mirroring the built-in one the grid renders itself.
  *
  * Read-only: `getAggregates` is already read-only on `DataGridApi`, computed
@@ -520,21 +410,46 @@ declare function useSelectionState<Row>(gridRef: RefObject<DataGridApi<Row> | nu
 declare function useAggregateState<Row>(gridRef: RefObject<DataGridApi<Row> | null>): AggregateResults;
 
 /**
- * Reactive column-sizing state read off a mounted `DataGridComponent`'s
- * `ref`. Read-only — sizing stays uncontrolled via `defaultColumnSizing`/the
- * grid's own resize handles, the same gap `useColumnSortState` has for sort.
+ * Reactive column-sizing state read off a mounted `DataGrid`'s
+ * `ref`. Reads only; change the widths through the ref's `setColumnSizing`,
+ * or hold them yourself with the controlled `columnSizing` prop.
  *
  * Before the grid mounts, reads as an empty object.
  */
 declare function useColumnSizingState<Row>(gridRef: RefObject<DataGridApi<Row> | null>): ColumnSizingState;
 
 /**
- * Reactive column-order state read off a mounted `DataGridComponent`'s
- * `ref`. Read-only — order stays uncontrolled via `defaultColumnOrder`/the
- * grid's own header drag, the same gap `useColumnSortState` has for sort.
+ * Reactive column-order state read off a mounted `DataGrid`'s
+ * `ref`. Reads only; change the order through the ref's `setColumnOrder`,
+ * or hold it yourself with the controlled `columnOrder` prop.
  *
  * Before the grid mounts, reads as an empty array.
  */
 declare function useColumnOrderState<Row>(gridRef: RefObject<DataGridApi<Row> | null>): ColumnOrderState;
 
-export { type Borders, type CellSelectEvent, type CellSelectionChangeEvent, type ColumnDefinition, type ColumnSelectEvent, type ColumnSelectionChangeEvent, type ColumnsSelectEvent, type DataGridApi, DataGridComponent, type DataGridProps, type GroupByBarVisibility, type GroupByStateApi, type HoverableConfig, type InfiniteScrollConfig, type PagerConfig, type PagerTemplateContext, type PaginationStateApi, type ResizeMode, type ResolvedColumn, type SelectedCell, type SelectedColumn, type SelectionStateApi, useAggregateState, useColumnOrderState, useColumnSizingState, useColumnSortState, useGroupByState, usePaginationState, useSelectionState };
+/**
+ * Reactive column-visibility state read off a mounted `DataGrid`'s `ref` —
+ * the columns shown or hidden since it mounted, keyed by id. Read-only:
+ * change it through the ref's `showColumns`/`hideColumns`. A column absent
+ * from it follows its definition's `hidden`.
+ *
+ * Before the grid mounts, reads as an empty object.
+ */
+declare function useColumnVisibilityState<Row>(gridRef: RefObject<DataGridApi<Row> | null>): ColumnVisibilityState;
+
+interface FilterStateApi<Row> {
+    filter: FilterState<Row>;
+    setFilter: (filter: FilterState<Row>) => void;
+}
+/**
+ * Reactive filter state read off a mounted `DataGrid`'s `ref`, for a filter
+ * bar or search box living outside the grid's own DOM — which, while the grid
+ * has no filter UI of its own, is where filtering happens. `setFilter`
+ * replaces the whole filter and sends the grid back to its first page.
+ *
+ * Before the grid mounts, `filter` reads as an empty array and `setFilter`
+ * is a no-op.
+ */
+declare function useFilterState<Row>(gridRef: RefObject<DataGridApi<Row> | null>): FilterStateApi<Row>;
+
+export { type CellSelectEvent, type CellSelectionChangeEvent, type ColumnDefinition, type ColumnSelectEvent, type ColumnSelectionChangeEvent, type ColumnsSelectEvent, type DataColumn, DataGrid, type DataGridApi, type DataGridProps, type FilterStateApi, type GroupByStateApi, type InfiniteScrollConfig, type PagerConfig, type PagerTemplateContext, type PaginationStateApi, type ReactRenderSlots, type ResolvedColumn, type SelectedCell, type SelectedColumn, type SelectionStateApi, useAggregateState, useColumnOrderState, useColumnSizingState, useColumnSortState, useColumnVisibilityState, useFilterState, useGroupByState, usePaginationState, useSelectionState };