@bmsuisse/datagrid 0.23.4 → 0.24.1

package/dist/index.d.ts

@@ -762,6 +762,37 @@ interface DataGridProps<TRow> {
      * a page with more than one.
      */
     testId?: string;
+    /**
+     * Buckets the grid's already-filtered/sorted/paginated `rows` into groups,
+     * rendering one full-width `colSpan`'d group-header row before each
+     * bucket's own rows, in first-seen bucket order (rows are never re-sorted
+     * to cluster a group together — the caller's own sort already determines
+     * which key appears first). Single level only — no nested grouping, no
+     * aggregate/summary calculation; a caller wanting a subtotal computes it
+     * themselves in `renderGroupHeader` off that bucket's own row array.
+     * Operates on whatever `rows` already resolved to — i.e. the current page,
+     * if paginated — with no special-casing; pair with a large `pageSize`/
+     * `showPagination: false` if a group's full membership should never be
+     * 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."
+     */
+    groupBy?: (row: TRow) => string;
+    /** Customizes a group-header row's content. Defaults to `` `${key} (${rows.length})` ``. */
+    renderGroupHeader?: (key: string, rows: 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
+     * `<DataGrid>` to own this state internally.
+     */
+    expandedGroups?: Record<string, boolean>;
+    onExpandedGroupsChange?: (expanded: Record<string, boolean>) => void;
 }
 
 /**
@@ -772,7 +803,7 @@ interface DataGridProps<TRow> {
  * (`"server"`). Column filter UI defaults to the type-appropriate widget
  * from `src/filter` unless a column supplies its own `cell` renderer.
  */
-declare function DataGrid<TRow extends RowData>({ columns, dataSource, getRowId, rowActions, headerActions, enableMultiSort, initialState, columnVisibility, renderDetail, enableColumnResizing, columnResizeMode, columnSizing: controlledColumnSizing, onColumnSizingChange, virtualize, showPagination, getRowProps, getRowTestId, gridState, selectedIds: controlledSelectedIds, onSelectedIdsChange, testId, loading: loadingProp, }: DataGridProps<TRow>): ReactElement;
+declare function DataGrid<TRow extends RowData>({ columns, dataSource, getRowId, rowActions, headerActions, enableMultiSort, initialState, columnVisibility, renderDetail, enableColumnResizing, columnResizeMode, columnSizing: controlledColumnSizing, onColumnSizingChange, virtualize, showPagination, getRowProps, getRowTestId, gridState, selectedIds: controlledSelectedIds, onSelectedIdsChange, testId, loading: loadingProp, groupBy, renderGroupHeader, defaultGroupsExpanded, expandedGroups: controlledExpandedGroups, onExpandedGroupsChange, }: DataGridProps<TRow>): ReactElement;
 
 interface GridStateController {
     state: GridState;
@@ -954,6 +985,48 @@ interface TreeDataGridProps<TRow> extends TreeAccessors<TRow> {
     estimatedRowHeight?: number;
     /** Max height of the scrollable table body in pixels. Required for virtualization to have a viewport to scroll within. Defaults to 480. */
     maxBodyHeight?: number;
+    /**
+     * Controlled row selection — same convention as `<DataGrid>`'s own
+     * `selectedIds`/`onSelectedIdsChange`. Both must be supplied together to
+     * render a checkbox column at all; there is no internal/uncontrolled
+     * fallback here, unlike `<DataGrid>` — `<TreeDataGrid>` has no
+     * `headerActions` bulk-toolbar concept that would need selection state
+     * even without external control, so there's nothing for an uncontrolled
+     * default to serve.
+     *
+     * Clicking a row's checkbox always toggles exactly that row's own id in
+     * this set — never its children or parent. Any cascade ("select whole
+     * group" / "select all descendants") is the caller's job, done by
+     * recomputing the desired final set inside `onSelectedIdsChange` before
+     * committing it to their own state.
+     */
+    selectedIds?: ReadonlySet<string>;
+    onSelectedIdsChange?: (ids: ReadonlySet<string>) => void;
+    /**
+     * Fully overrides a row's checked/indeterminate display, replacing the
+     * default derivation below. Needed for selection semantics this component
+     * won't build in — e.g. a "select whole group vs. split into individual
+     * children once loaded" cascade, where a parent should read as checked
+     * even though not every descendant id is literally in `selectedIds`.
+     * Return `undefined` for a given row to fall back to the default
+     * derivation for just that row.
+     *
+     * Omitted (the default): `checked` is exactly `selectedIds.has(getRowId(row))`
+     * — `selectedIds` always stays the single source of truth for "is this id
+     * selected." `indeterminate` is true only when the row itself isn't
+     * checked but at least one *currently loaded* descendant (recursively, via
+     * the same `getChildren`/`onLoadChildren` cache this component already
+     * maintains) is checked or itself indeterminate. A selected descendant
+     * hidden behind a node that's never been expanded (so its children were
+     * never fetched) can't be inspected — that ancestor reads as unchecked,
+     * not indeterminate, until the fetch happens.
+     */
+    getRowSelectionState?: (row: TRow) => {
+        checked: boolean;
+        indeterminate?: boolean;
+    } | undefined;
+    /** Disables just the checkbox for a specific row. Defaults to `() => false`. */
+    isRowSelectionDisabled?: (row: TRow) => boolean;
 }
 
 /**
@@ -970,7 +1043,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, indentSize, getRowProps, getRowTestId, rowActions, virtualizeThreshold, estimatedRowHeight, maxBodyHeight, }: TreeDataGridProps<TRow>): ReactElement;
+declare function TreeDataGrid<TRow>({ columns, data, treeColumnId, getRowId, getChildren, hasChildren, onLoadChildren, initialExpandedLevel, expanded: controlledExpanded, onExpandedChange, indentSize, getRowProps, getRowTestId, rowActions, virtualizeThreshold, estimatedRowHeight, maxBodyHeight, selectedIds: controlledSelectedIds, onSelectedIdsChange, getRowSelectionState, isRowSelectionDisabled, }: TreeDataGridProps<TRow>): ReactElement;
 
 interface FlatTreeRow<TRow> {
     row: TRow;