@gridkitjs/react 0.7.0 → 0.9.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, DisplayRow, ResolvedColumn as ResolvedColumn$1, ColumnSizingState, ColumnOrderState, ColumnSortState, GroupByState, GroupExpansionState, SelectionState, CellSelectionState, SelectableConfig, ColumnSizeDefaults, ColumnResizeEvent, ColumnOrderEvent, ColumnSortEvent, GroupByEvent, GroupExpansionEvent, 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,12 +59,21 @@ 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. */
+    /**
+     * The grid's row-area `<table>` element — the one holding `<tbody>`. The
+     * header and, when aggregates are active, footer render as their own
+     * sibling `<table>`s outside this one; use `element` to reach the whole
+     * scrollable viewport instead.
+     */
     readonly table: HTMLTableElement | null;
     /** Rows as currently filtered and sorted — what's rendered, ungrouped. */
     getRows(): readonly ResolvedRow<Row>[];
@@ -81,6 +90,17 @@ interface DataGridApi<Row> {
     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;
@@ -96,10 +116,27 @@ interface DataGridApi<Row> {
     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";
 /**
@@ -127,6 +164,65 @@ interface HoverableConfig {
     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;
+}
+/**
+ * Loads more rows as the user scrolls near the bottom, in place of paging.
+ * Appends only — there is no equivalent of `paginated`'s reset-to-page-0 for
+ * a result set that shrinks out from under the current position.
+ */
+interface InfiniteScrollConfig {
+    /** Whether a further `onLoadMore` could still return more rows. `false` removes the sentinel entirely, so no further scrolling can trigger a load. */
+    readonly hasMore: boolean;
+    /**
+     * Called at most once per genuine threshold-crossing: fires when the
+     * sentinel comes within `rootMargin` of the body's viewport, and not again
+     * until `isLoadingMore` has gone back to `false`.
+     */
+    readonly onLoadMore: () => void;
+    /** 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"`.
+     */
+    readonly rootMargin?: string | undefined;
+    /** Replaces the built-in "Loading more…" row. */
+    readonly loadingTemplate?: (() => ReactNode) | undefined;
+}
 interface DataGridProps<Row> extends SelectionCallbacks<Row> {
     columns?: readonly ColumnDefinition<Row>[] | undefined;
     dataSource?: readonly Row[] | undefined;
@@ -248,6 +344,78 @@ interface DataGridProps<Row> extends SelectionCallbacks<Row> {
     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
+     * `console.error` and only `paginated` takes effect. Recommended (not
+     * required) alongside `virtualized` for a dataset that grows without
+     * 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.
@@ -261,6 +429,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, groupableColumns, groupToggleIconColumns, groupByDraggableColumns, groupByBarVisibility, defaultGroupBy, onGroupByChange, defaultGroupExpansion, onGroupExpansionChange, 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, infiniteScroll, aggregates, groupAggregateDisplay, height, virtualized, overscan, estimatedRowHeight, 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 GroupByBarVisibility, 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 InfiniteScrollConfig, type PagerConfig, type PagerTemplateContext, type PaginationStateApi, type ResizeMode, type ResolvedColumn, type SelectedCell, type SelectedColumn, type SelectionStateApi, useAggregateState, useColumnOrderState, useColumnSizingState, useColumnSortState, useGroupByState, usePaginationState, useSelectionState };