@bmsuisse/datagrid 0.27.0 → 0.29.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ReactNode, ReactElement, ComponentType } from 'react';
+import { ReactNode, ReactElement, ComponentType, RefObject } from 'react';
 import { ColumnSizingState, RowData } from '@tanstack/react-table';
 export { ColumnSizingState } from '@tanstack/react-table';
 
@@ -1103,10 +1103,29 @@ interface DataGridProps<TRow> {
      * split across pages. Omit entirely to disable — no grouping, no header
      * rows, unchanged default rendering.
      *
-     * Not supported together with `virtualize` yet — when both are set,
-     * virtualization is silently disabled and the grid renders as a plain,
-     * fully-rendered (but still grouped) `<table>` instead. See AGENTS.md's
-     * "Known limitations."
+     * Composes with `virtualize` — header rows and member rows are flattened
+     * into one virtualizable list together, so a large grouped dataset windows
+     * the same way an ungrouped one does. `virtualize.threshold` still gates
+     * on the real row count (`groupBy`'s synthetic header entries never push a
+     * grid over a threshold its actual data didn't cross), and
+     * `virtualize.onEndReached`'s own "won't fire again for the same data"
+     * dedup is keyed off that same real row count too — a pure expand/collapse
+     * click, with no new data loaded, never re-fires it.
+     *
+     * Two gaps this doesn't close, both pre-existing/out of scope for this
+     * pass rather than introduced by composing with `virtualize`: `zebra`'s
+     * odd/even striping is keyed off a row's position in the flat, ungrouped
+     * row list, not its rendered position within its own bucket, so grouped
+     * rows can stripe unevenly (`groupBy` alone already had this, virtualizing
+     * doesn't fix or worsen it); and a sticky group header stays pinned below
+     * the real `<thead>` only while its own `<tbody>` (or one of its member
+     * rows') is actually mounted in the virtualized window — scrolling deep
+     * into one bucket whose row count itself exceeds `virtualize`'s overscan
+     * will eventually unmount that bucket's header and let it scroll away
+     * rather than staying pinned, since `position: sticky` needs the element
+     * mounted to stick at all. Both are harmless for the common case (buckets
+     * no bigger than a couple dozen rows); see AGENTS.md's "Known limitations"
+     * for the full writeup.
      */
     groupBy?: (row: TRow) => string;
     /** Customizes a group-header row's content. Defaults to `` `${key} (${rows.length})` ``. */
@@ -1226,6 +1245,54 @@ interface DebouncedCallback<TArgs extends unknown[]> {
  */
 declare function useDebouncedCallback<TArgs extends unknown[]>(callback: (...args: TArgs) => void, delayMs: number): DebouncedCallback<TArgs>;
 
+interface GroupExpansionController {
+    /** The resolved (controlled-or-internal) expand state, keyed by group key. */
+    expandedGroups: Record<string, boolean>;
+    /** A key absent from `expandedGroups` (a group never toggled since it was first seen) falls back to `defaultGroupsExpanded`, not `false`. */
+    isGroupExpanded: (key: string) => boolean;
+    toggleGroupExpanded: (key: string) => void;
+}
+/**
+ * Same controlled/uncontrolled pattern as `<DataGrid>`'s/`<TreeDataGrid>`'s
+ * own `selectedIds`/`columnSizing`: both `controlledExpandedGroups` and
+ * `onExpandedGroupsChange` must be supplied together to actually control
+ * this state — omit both to let this hook own it internally. Shared between
+ * the two grids' `groupBy` support so a fix to the fallback/toggle logic
+ * never has to be made twice.
+ *
+ * `isGroupExpanded`/`toggleGroupExpanded` are stable (`useCallback`-wrapped)
+ * across renders as long as `expandedGroups`/`defaultGroupsExpanded`/
+ * `onExpandedGroupsChange` don't change — callers can safely list them in a
+ * `useMemo`/`useEffect` dependency array without defeating memoization.
+ */
+declare function useGroupExpansion(defaultGroupsExpanded: boolean, controlledExpandedGroups: Record<string, boolean> | undefined, onExpandedGroupsChange: ((expanded: Record<string, boolean>) => void) | undefined): GroupExpansionController;
+
+interface StickyGroupHeaderTop {
+    /** Attach to the grid's own `<thead>`. */
+    theadRef: RefObject<HTMLTableSectionElement>;
+    /** The measured `<thead>` height in pixels — `0` until first measured, or whenever `enabled` is false. */
+    groupHeaderTop: number;
+}
+/**
+ * Measures the real header height so a sticky group-header row can sit
+ * exactly below it (its own `top` style) while member rows scroll past
+ * underneath. `ResizeObserver` rather than a one-off measurement since
+ * header height can change after mount (e.g. a column's header content
+ * wrapping to a second line, or a resizable column changing the header
+ * row's layout). Shared between `<DataGrid>` and `<TreeDataGrid>`'s own
+ * `groupBy` support.
+ */
+declare function useStickyGroupHeaderTop(enabled: boolean): StickyGroupHeaderTop;
+
+/**
+ * Single source of truth for "which columns actually render" — filters
+ * `columns` down to whatever `columnVisibility` marks visible, or returns
+ * `columns` unchanged when `columnVisibility` is omitted. Shared between
+ * `<DataGrid>` and `<TreeDataGrid>` so both read `columnVisibility` (e.g.
+ * driven by a `<ColumnSelector>`) the same way.
+ */
+declare function useVisibleColumns<TRow>(columns: ColumnDef<TRow>[], columnVisibility: ColumnVisibility | undefined): ColumnDef<TRow>[];
+
 /**
  * Accessor-based node shape, matching `<DataGrid>`'s `getRowId` convention
  * rather than requiring `TRow` to carry specific field names.
@@ -1258,6 +1325,16 @@ interface TreeDataGridProps<TRow> extends TreeAccessors<TRow> {
      * chevron prepended. Defaults to the first column in `columns`.
      */
     treeColumnId?: string;
+    /**
+     * Controlled column visibility, e.g. driven by a `<ColumnSelector>` next
+     * to the grid — same convention as `<DataGrid>`'s own `columnVisibility`.
+     * `<TreeDataGrid>` never owns this state itself; omit to render every
+     * column in `columns`. Note that hiding `treeColumnId` itself (or the
+     * first column, when `treeColumnId` is omitted) hides the indentation/
+     * expand-collapse chevron along with it, since those are only ever
+     * attached to that one column's cell.
+     */
+    columnVisibility?: ColumnVisibility;
     /**
      * Fetches a node's children on demand. Omit this entirely for a fully
      * eager tree (all children already present via `getChildren`) — a node
@@ -1389,6 +1466,35 @@ interface TreeDataGridProps<TRow> extends TreeAccessors<TRow> {
     } | undefined;
     /** Disables just the checkbox for a specific row. Defaults to `() => false`. */
     isRowSelectionDisabled?: (row: TRow) => boolean;
+    /**
+     * Buckets the *root-level* rows in `data` into groups, rendering one
+     * full-width `colSpan`'d group-header row before each bucket's own
+     * (recursively flattened, depth-first) rows — same convention as
+     * `<DataGrid>`'s own `groupBy`. Single level only, and only ever applied
+     * to roots: a node's children are never split across groups from their
+     * parent, since grouping an already-hierarchical tree by anything other
+     * than "which root it belongs to" wouldn't have a sensible rendering.
+     * Groups appear in first-seen bucket order — roots are never re-sorted to
+     * cluster a group together. Omit entirely to disable — no grouping, no
+     * header rows, unchanged default rendering.
+     *
+     * Not supported together with virtualization — when both are set,
+     * virtualization is silently disabled and the tree renders as a plain,
+     * fully-rendered (but still grouped) `<table>` instead, same limitation
+     * `<DataGrid>` has.
+     */
+    groupBy?: (row: TRow) => string;
+    /** Customizes a group-header row's content. Defaults to `` `${key} (${rootCount})` `` — `rootCount` counts only that group's root rows, not their descendants. */
+    renderGroupHeader?: (key: string, roots: TRow[], expanded: boolean) => ReactNode;
+    /** Whether a newly-seen group starts expanded. Defaults to true. */
+    defaultGroupsExpanded?: boolean;
+    /**
+     * Controlled per-group expand/collapse state, keyed by the `groupBy` key.
+     * Both must be supplied together to control it — omit both for
+     * `<TreeDataGrid>` to own this state internally.
+     */
+    expandedGroups?: Record<string, boolean>;
+    onExpandedGroupsChange?: (expanded: Record<string, boolean>) => void;
     /** Alternates body row backgrounds for readability on wide/dense tables. Defaults to true. */
     zebra?: boolean;
     /**
@@ -1419,7 +1525,7 @@ interface TreeDataGridProps<TRow> extends TreeAccessors<TRow> {
  * column's cell matches `treeColumnId` (defaults to `columns[0]`); every
  * other column renders exactly like it would in `<DataGrid>`.
  */
-declare function TreeDataGrid<TRow>({ columns, data, treeColumnId, getRowId, getChildren, hasChildren, onLoadChildren, initialExpandedLevel, expanded: controlledExpanded, onExpandedChange, childrenMap: controlledChildrenMap, onChildrenMapChange, indentSize, getRowProps, getRowTestId, rowActions, virtualizeThreshold, estimatedRowHeight, maxBodyHeight, selectedIds: controlledSelectedIds, onSelectedIdsChange, getRowSelectionState, isRowSelectionDisabled, zebra, editing, }: TreeDataGridProps<TRow>): ReactElement;
+declare function TreeDataGrid<TRow>({ columns, data, treeColumnId, columnVisibility, getRowId, getChildren, hasChildren, onLoadChildren, initialExpandedLevel, expanded: controlledExpanded, onExpandedChange, childrenMap: controlledChildrenMap, onChildrenMapChange, indentSize, getRowProps, getRowTestId, rowActions, virtualizeThreshold, estimatedRowHeight, maxBodyHeight, selectedIds: controlledSelectedIds, onSelectedIdsChange, getRowSelectionState, isRowSelectionDisabled, groupBy, renderGroupHeader, defaultGroupsExpanded, expandedGroups: controlledExpandedGroups, onExpandedGroupsChange, zebra, editing, }: TreeDataGridProps<TRow>): ReactElement;
 
 interface FlatTreeRow<TRow> {
     row: TRow;
@@ -1475,4 +1581,4 @@ interface UseTreeStateOptions<TRow> extends TreeAccessors<TRow> {
  */
 declare function useTreeState<TRow>({ data, getRowId, getChildren, hasChildren, onLoadChildren, expanded: controlledExpanded, onExpandedChange, childrenMap: controlledChildrenMap, onChildrenMapChange, }: UseTreeStateOptions<TRow>): TreeStateController<TRow>;
 
-export { ActionsMenu, type BaseColumn, type BooleanColumn, BooleanEditor, BooleanFilter, type ClientProcessingResult, type ColumnAlign, type ColumnDef, type ColumnGroup, ColumnSelector, type ColumnSelectorProps, type ColumnVisibility, type CompositeFilterDescriptor, DataGrid, type DataGridProps, type DataSource, type DateColumn, DateEditor, DateRangeFilter, type DebouncedCallback, EditFieldError, type EditWidgetProps, type EditedRow, EditingBar, type EditingBarProps, type EditingCellContext, type EditingOptions, type EditingState, type EnumColumn, EnumEditor, EnumFilter, type EnumOption, type FilterDescriptor, type FilterOperator, type FilterWidgetProps, type FlatTreeRow, type GridState, type GridStateController, type MenuItem, type MenuItemContext, type NumberColumn, NumberComparisonFilter, NumberEditor, NumberHistogramFilter, type NumberHistogramFilterProps, NumberRangeFilter, type PendingRowEdit, type ResolvedMenuItem, type SortDescriptor, type StringColumn, StringEditor, StringFilter, type TreeAccessors, TreeDataGrid, type TreeDataGridProps, type TreeStateController, UNARY_OPERATORS, type UseTreeStateOptions, alignClassName, canHideColumn, canHideGroup, countVisible, defaultAlign, defaultFormat, editErrorId, evaluateFilter, facetedNumberValues, fieldKey, flattenTree, getColumnValue, groupColumns, isColumnVisible, isCompositeFilterDescriptor, isEditable, isFilterDescriptor, isFilterable, isSortable, processClientData, renderDefaultEditWidget, renderDefaultFilterWidget, renderEditableCell, resolveMenuItems, storageKeyFor, toDate, useDebouncedCallback, useEditingState, useGridState, useTreeState };
+export { ActionsMenu, type BaseColumn, type BooleanColumn, BooleanEditor, BooleanFilter, type ClientProcessingResult, type ColumnAlign, type ColumnDef, type ColumnGroup, ColumnSelector, type ColumnSelectorProps, type ColumnVisibility, type CompositeFilterDescriptor, DataGrid, type DataGridProps, type DataSource, type DateColumn, DateEditor, DateRangeFilter, type DebouncedCallback, EditFieldError, type EditWidgetProps, type EditedRow, EditingBar, type EditingBarProps, type EditingCellContext, type EditingOptions, type EditingState, type EnumColumn, EnumEditor, EnumFilter, type EnumOption, type FilterDescriptor, type FilterOperator, type FilterWidgetProps, type FlatTreeRow, type GridState, type GridStateController, type GroupExpansionController, type MenuItem, type MenuItemContext, type NumberColumn, NumberComparisonFilter, NumberEditor, NumberHistogramFilter, type NumberHistogramFilterProps, NumberRangeFilter, type PendingRowEdit, type ResolvedMenuItem, type SortDescriptor, type StickyGroupHeaderTop, type StringColumn, StringEditor, StringFilter, type TreeAccessors, TreeDataGrid, type TreeDataGridProps, type TreeStateController, UNARY_OPERATORS, type UseTreeStateOptions, alignClassName, canHideColumn, canHideGroup, countVisible, defaultAlign, defaultFormat, editErrorId, evaluateFilter, facetedNumberValues, fieldKey, flattenTree, getColumnValue, groupColumns, isColumnVisible, isCompositeFilterDescriptor, isEditable, isFilterDescriptor, isFilterable, isSortable, processClientData, renderDefaultEditWidget, renderDefaultFilterWidget, renderEditableCell, resolveMenuItems, storageKeyFor, toDate, useDebouncedCallback, useEditingState, useGridState, useGroupExpansion, useStickyGroupHeaderTop, useTreeState, useVisibleColumns };