@gridkitjs/react 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { ReactNode } 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, 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';
+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';
 export { CellSelectionMode, CellSelectionState, CellTemplateContext, ColumnResizeEvent, ColumnSizeDefaults, ColumnSizingState, ResolvedRow, RowSelectEvent, RowSelectionChangeEvent, RowsSelectEvent, SelectableConfig, SelectedCellRef, SelectionMode, SelectionState } from '@gridkitjs/core';
 
 /**
@@ -53,6 +53,54 @@ 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>;
+/**
+ * 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.
+ */
+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, 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;
+    getRowSelection(): SelectionState;
+    getColumnSelection(): SelectionState;
+    getCellSelection(): CellSelectionState;
+    /** The cell currently holding the grid's single tab stop. */
+    getFocusedCell(): {
+        rowIndex: number;
+        columnIndex: number;
+    };
+    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;
+    /** 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;
+}
 type Borders = "horizontal" | "vertical" | "all" | "none";
 /**
  * How a column's width relates to the grid's.
@@ -63,6 +111,17 @@ 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;
@@ -151,6 +210,42 @@ 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;
     /**
@@ -163,7 +258,9 @@ interface DataGridProps<Row> extends SelectionCallbacks<Row> {
      * Takes precedence over `label`, as `aria-labelledby` does.
      */
     labelledBy?: string | undefined;
+    /** 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, ...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, label, labelledBy, ref, ...callbacks }: DataGridProps<Row>): react.JSX.Element;
 
-export { type CellSelectEvent, type CellSelectionChangeEvent, type ColumnDefinition, type ColumnSelectEvent, type ColumnSelectionChangeEvent, type ColumnsSelectEvent, DataGridComponent, type DataGridProps, 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 HoverableConfig, type ResizeMode, type ResolvedColumn, type SelectedCell, type SelectedColumn };