@gridkitjs/react 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { ReactNode, Ref } 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, ResolvedColumn as ResolvedColumn$1, ColumnSizingState, ColumnOrderState, ColumnSortState, SelectionState, CellSelectionState, SelectableConfig, ColumnSizeDefaults, ColumnResizeEvent, ColumnOrderEvent, ColumnSortEvent, FilterState, SelectedCell as SelectedCell$1, SelectedColumn as SelectedColumn$1 } from '@gridkitjs/core';
+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';
 
 /**
@@ -59,20 +59,43 @@ type CellSelectionChangeEvent<Row> = CellSelectionChangeEvent$1<Row, ReactNode>;
  * 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.
+ * 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.
  */
 interface DataGridApi<Row> {
     /** The grid's scrollable viewport element. */
     readonly element: HTMLDivElement | null;
     /** The grid's `<table>` element. */
     readonly table: HTMLTableElement | null;
-    /** Rows as currently filtered and sorted — what's rendered. */
+    /** Rows as currently filtered and sorted — what's rendered, ungrouped. */
     getRows(): readonly ResolvedRow<Row>[];
+    /**
+     * `getRows()` regrouped into the active `groupBy` — group headers
+     * interleaved with data rows, in render order. Identical to `getRows()`
+     * when `groupBy` is empty.
+     */
+    getDisplayRows(): readonly DisplayRow<Row>[];
     /** Columns as currently sized and ordered — what's rendered. */
     getColumns(): readonly ResolvedColumn<Row>[];
     getColumnSizing(): ColumnSizingState;
     getColumnOrder(): ColumnOrderState;
     getColumnSort(): ColumnSortState;
+    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. */
+    getPagination(): PaginationState;
+    /** How many pages the current `pagination.pageSize` splits the grid's rows into — `1` whenever `paginated` is off. */
+    getPageCount(): number;
+    /**
+     * The grand-total aggregate results — every active aggregate computed over
+     * the whole filtered/sorted dataset, ungrouped and unpaginated. A specific
+     * group's own results are read off `getDisplayRows()` instead, on that
+     * group header's `aggregates` field.
+     */
+    getAggregates(): AggregateResults;
     getRowSelection(): SelectionState;
     getColumnSelection(): SelectionState;
     getCellSelection(): CellSelectionState;
@@ -84,10 +107,31 @@ interface DataGridApi<Row> {
     focusCell(rowIndex: number, columnIndex: number): void;
     clearSelection(): void;
     selectAllRows(): 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. */
+    collapseAllGroups(): void;
+    /** Moves to the given page, clamped into range. */
+    goToPage(pageIndex: number): void;
+    /** Moves to the next page. A no-op on the last page. */
+    nextPage(): void;
+    /** Moves to the previous page. A no-op on the first page. */
+    previousPage(): void;
+    /** Changes the page size, resetting to the first page. */
+    setPageSize(pageSize: number): void;
     /** 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. */
     scrollToColumn(columnId: string, options?: ScrollIntoViewOptions): void;
+    /**
+     * Registers `listener` to be called after any render in which the grid's
+     * internal state may have changed — every getter above may return a
+     * different value once `listener` fires, not just one. Returns an
+     * unsubscribe function. The primitive the `use*State` hooks under
+     * `packages/react/src/DataGrid/hooks/` build on; most consumers should
+     * reach for one of those instead of calling `subscribe` directly.
+     */
+    subscribe(listener: () => void): () => void;
 }
 type Borders = "horizontal" | "vertical" | "all" | "none";
 /**
@@ -99,11 +143,56 @@ type Borders = "horizontal" | "vertical" | "all" | "none";
  * 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
+ * state changed, so it's current by construction — unlike `DataGridApi`'s
+ * imperative methods and snapshot getters, which carry no "something
+ * changed, re-render" signal of their own.
+ */
+interface PagerTemplateContext {
+    /** Same shape as `DataGridApi.getPagination()` — 0-based `pageIndex`. */
+    pagination: PaginationState;
+    /** `pagination.pageIndex + 1`, clamped — the display-ready page number. */
+    currentPage: number;
+    pageCount: number;
+    /** Passthrough of `pager.sizeOptions`, undefined when not given. */
+    pageSizeOptions: readonly number[] | undefined;
+    /** 0-based, same as `DataGridApi.goToPage` — not `currentPage`'s numbering. */
+    goToPage: (pageIndex: number) => void;
+    nextPage: () => void;
+    previousPage: () => void;
+    setPageSize: (pageSize: number) => void;
+}
+/** Presentation options for the grid's built-in pager. */
+interface PagerConfig {
+    /** Page sizes offered by the built-in pager's page-size control. */
+    sizeOptions?: readonly number[] | undefined;
+    /** Defaults to `"compact"` — today's Prev/status/Next. */
+    variant?: "compact" | "numbered" | undefined;
+    /** Numbered variant only. How many pages to always show at each end. Defaults to 1. */
+    boundaryCount?: number | undefined;
+    /** Numbered variant only. How many pages to show on each side of the current page. Defaults to 1. */
+    siblingCount?: number | undefined;
+    /** Replaces the built-in pager entirely when given. `variant` is ignored. */
+    template?: ((context: PagerTemplateContext) => ReactNode) | undefined;
+}
 interface DataGridProps<Row> extends SelectionCallbacks<Row> {
     columns?: readonly ColumnDefinition<Row>[] | undefined;
     dataSource?: readonly Row[] | undefined;
@@ -187,8 +276,79 @@ interface DataGridProps<Row> extends SelectionCallbacks<Row> {
      * 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;
+    /**
+     * 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;
     /**
      * 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.
@@ -202,6 +362,112 @@ interface DataGridProps<Row> extends 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, defaultFilter, label, labelledBy, ref, ...callbacks }: 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, groupableColumns, groupToggleIconColumns, groupByDraggableColumns, groupByBarVisibility, defaultGroupBy, onGroupByChange, defaultGroupExpansion, onGroupExpansionChange, defaultFilter, paginated, defaultPagination, pager, onPaginationChange, aggregates, groupAggregateDisplay, label, labelledBy, ref, ...callbacks }: DataGridProps<Row>): react.JSX.Element;
+
+interface PaginationStateApi {
+    pagination: PaginationState;
+    pageCount: number;
+    goToPage: (pageIndex: number) => void;
+    nextPage: () => void;
+    previousPage: () => void;
+    setPageSize: (pageSize: number) => void;
+}
+/**
+ * Reactive pagination state read off a mounted `DataGridComponent`'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,
+ * which carries no `onPaginationChange` of its own.
+ *
+ * Before the grid mounts, `pagination` reads `{ pageIndex: 0, pageSize: 0 }`
+ * and `pageCount` reads `0`; the actions are no-ops until then.
+ */
+declare function usePaginationState<Row>(gridRef: RefObject<DataGridApi<Row> | null>): PaginationStateApi;
+
+interface GroupByStateApi {
+    groupBy: GroupByState;
+    groupExpansion: GroupExpansionState;
+    expandAllGroups: () => void;
+    collapseAllGroups: () => void;
+}
+/**
+ * Reactive group-by and group-expansion state read off a mounted
+ * `DataGridComponent`'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
+ * 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.
+ *
+ * Before the grid mounts, both fields read as empty and the actions are
+ * no-ops.
+ */
+declare function useGroupByState<Row>(gridRef: RefObject<DataGridApi<Row> | null>): GroupByStateApi;
+
+/**
+ * Reactive column-sort state read off a mounted `DataGridComponent`'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.
+ *
+ * Before the grid mounts, reads as an empty array.
+ */
+declare function useColumnSortState<Row>(gridRef: RefObject<DataGridApi<Row> | null>): ColumnSortState;
+
+interface SelectionStateApi {
+    rowSelection: SelectionState;
+    columnSelection: SelectionState;
+    cellSelection: CellSelectionState;
+    clearSelection: () => void;
+    selectAllRows: () => void;
+}
+/**
+ * Reactive row/column/cell selection state read off a mounted
+ * `DataGridComponent`'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.
+ *
+ * Before the grid mounts, the row/column fields read as empty arrays and
+ * the cell field reads `null`; the actions are no-ops.
+ */
+declare function useSelectionState<Row>(gridRef: RefObject<DataGridApi<Row> | null>): SelectionStateApi;
+
+/**
+ * Reactive grand-total aggregate results read off a mounted
+ * `DataGridComponent`'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
+ * over the whole filtered/sorted dataset rather than driven by any action.
+ * A specific group's own subtotal is read off `getDisplayRows()`'s
+ * per-header `aggregates` field instead — see `useGroupByState`.
+ *
+ * Before the grid mounts, reads as an empty map.
+ */
+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.
+ *
+ * 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.
+ *
+ * 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 HoverableConfig, type ResizeMode, type ResolvedColumn, type SelectedCell, type SelectedColumn };
+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 PagerConfig, type PagerTemplateContext, type PaginationStateApi, type ResizeMode, type ResolvedColumn, type SelectedCell, type SelectedColumn, type SelectionStateApi, useAggregateState, useColumnOrderState, useColumnSizingState, useColumnSortState, useGroupByState, usePaginationState, useSelectionState };