@bmsuisse/datagrid 0.27.0 → 0.28.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';
 
@@ -1226,6 +1226,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 +1306,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 +1447,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 +1506,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 +1562,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 };