@cdx-ui/data-grid 0.3.12 → 0.3.14

package/src/styles.ts

@@ -180,8 +180,21 @@ export const dataGridBodyVariants = cva(
 
 export const dataGridFilterInputVariants = cva('min-w-24');
 
+// The toolbar panel sits at a fixed spot in the grid root. A panel opened from a column is anchored
+// to its opener in a portal, so its position and width cap come from the anchored overlay instead.
 export const dataGridFilterPanelVariants = cva(
-  'absolute start-4 top-16 z-30 w-max max-w-[calc(100%-2rem)] gap-3 rounded-lg border border-stroke-secondary bg-surface-primary px-3 pb-2 pt-3 shadow-lg',
+  'w-max gap-3 rounded-lg border border-stroke-secondary bg-surface-primary px-3 pb-2 pt-3 shadow-lg',
+  {
+    variants: {
+      anchored: {
+        true: '',
+        false: 'absolute start-4 top-16 z-30 max-w-[calc(100%-2rem)]',
+      },
+    },
+    defaultVariants: {
+      anchored: false,
+    },
+  },
 );
 
 // The panel is as wide as one unwrapped row, capped at the grid's width. Below that, fields wrap
@@ -234,6 +247,49 @@ export const dataGridCellVariants = cva([
   }),
 ]);
 
+export const dataGridDetailToggleCellVariants = cva([
+  'w-12 px-2',
+  Platform.select({
+    web: 'border-b border-stroke-secondary',
+    default: '',
+  }),
+]);
+
+// Header labels and depth-0 content line up because both reserve the toggle slot.
+export const dataGridTreeCellInnerVariants = cva('min-w-0 flex-1 flex-row items-center gap-2');
+
+export const dataGridTreeToggleSlotVariants = cva('size-8 shrink-0 items-center justify-center');
+
+export const dataGridTreeContentVariants = cva('min-w-0 flex-1 flex-row items-center');
+
+export const dataGridDetailPanelCellVariants = cva([
+  'px-4 py-3',
+  Platform.select({
+    web: 'border-b border-stroke-secondary bg-surface-primary',
+    default: '',
+  }),
+]);
+
+// Same `w-0 min-w-full` trick as the header label: a declared column width truncates the value
+// with an ellipsis instead of wrapping it onto a second line and growing the fixed-height row.
+export const dataGridCellTextVariants = cva('min-w-0', {
+  variants: {
+    align: {
+      start: 'text-start',
+      center: 'text-center',
+      end: 'text-end',
+    },
+    fitToColumn: {
+      true: 'w-0 min-w-full',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    align: 'start',
+    fitToColumn: false,
+  },
+});
+
 export const dataGridSelectCellVariants = cva([
   'w-14 px-4',
   Platform.select({

package/src/types.ts

@@ -166,6 +166,31 @@ export type GridFeatureMode = 'client' | 'server';
 
 export type GridPaginationMode = GridFeatureMode;
 
+/** Maps a column `field` to `false` to hide it. Fields that are missing or `true` stay visible. */
+export type GridColumnVisibilityModel = Record<string, boolean>;
+
+export interface GridRowParams<R extends GridValidRowModel = GridValidRowModel> {
+  id: GridRowId;
+  row: R;
+}
+
+export interface GridTreeNodeParams<
+  R extends GridValidRowModel = GridValidRowModel,
+> extends GridRowParams<R> {
+  /** `0` for top-level rows. */
+  depth: number;
+}
+
+/**
+ * How a selection change spreads through `treeData`. Both default to `true`, as in MUI.
+ */
+export interface GridRowSelectionPropagation {
+  /** Selecting or deselecting a parent applies to its descendants that pass the current filter. */
+  descendants?: boolean;
+  /** A parent is selected exactly when all of its children are selected. */
+  parents?: boolean;
+}
+
 export interface DataGridProps<R extends GridValidRowModel = GridValidRowModel> {
   rows: GridRowsProp<R>;
   columns: readonly GridColDef<R>[];
@@ -225,7 +250,53 @@ export interface DataGridProps<R extends GridValidRowModel = GridValidRowModel>
    * MUI X Community ships no column pinning; this is a Pro feature.
    */
   pinnedColumns?: GridPinnedColumnFields;
+  /**
+   * Hides columns without removing them from `columns`. Hidden columns still sort, filter, and
+   * match the quick filter, and the filter panel still lists them. The grid has no built-in
+   * control that changes visibility, so keep the model in your own state.
+   */
+  columnVisibilityModel?: GridColumnVisibilityModel;
   headerFilters?: boolean;
+  /**
+   * Renders `rows` as a tree. Each row's position comes from `getTreeDataPath`. The first column
+   * becomes the tree column: it indents by depth and holds the expand toggle and, with
+   * `checkboxSelection`, the row checkbox. Search and filters keep the ancestors of every match
+   * and expand them while the filter is active.
+   *
+   * Client mode only: server pagination, sorting, and filtering are not supported with tree data.
+   * Pagination counts top-level rows, so a group never splits across pages.
+   * @default false
+   */
+  treeData?: boolean;
+  /**
+   * Path from the root to the row, for example `['Accounts', 'OAuth V1', 'List accounts']`.
+   * Paths must be unique. A row whose parent path has no row attaches to its nearest existing
+   * ancestor. Keep the function reference stable.
+   */
+  getTreeDataPath?: (row: R) => readonly string[];
+  /**
+   * Overrides the tree column (the first column) when `treeData` is on: header name, width,
+   * `renderCell`, and so on. `field` stays the first column's field.
+   */
+  groupingColDef?: Partial<Omit<GridBaseColDef<R>, 'field'>>;
+  /** Depth expanded on first render. `0` collapses every group; `-1` expands all. @default 0 */
+  defaultGroupingExpansionDepth?: number;
+  /** Takes priority over `defaultGroupingExpansionDepth` for the initial state of a group. */
+  isGroupExpandedByDefault?: (node: GridTreeNodeParams<R>) => boolean;
+  /**
+   * How selection spreads between parents and children with `treeData`. Unlike MUI, rows hidden
+   * by a filter stay selected, so a search-then-pick form keeps earlier picks.
+   */
+  rowSelectionPropagation?: GridRowSelectionPropagation;
+  /**
+   * Content of the expandable panel under a row (master-detail). Adds a toggle column at the
+   * start. Rows for which this returns `null` or `undefined` get no toggle.
+   */
+  getDetailPanelContent?: (params: GridRowParams<R>) => ReactNode;
+  /** Ids of rows whose detail panel is open (controlled). */
+  detailPanelExpandedRowIds?: ReadonlySet<GridRowId>;
+  defaultDetailPanelExpandedRowIds?: ReadonlySet<GridRowId>;
+  onDetailPanelExpandedRowIdsChange?: (ids: Set<GridRowId>) => void;
   /** Replaces the default centered "No rows" message. Shown when `rows` is empty and not loading. */
   noRowsOverlay?: ReactNode;
   /** Replaces the default skeleton rows shown when `loading` is true. */
@@ -239,6 +310,11 @@ export interface DataGridProps<R extends GridValidRowModel = GridValidRowModel>
 
 export const SELECT_COLUMN_ID = '__select__';
 
+/** Same id as MUI X's master-detail toggle column. */
+export const DETAIL_PANEL_TOGGLE_ID = '__detail_panel_toggle__';
+
+export const EMPTY_ROW_ID_SET: ReadonlySet<GridRowId> = new Set();
+
 /** MUI X Data Grid checkbox-column field; accepted as an alias for {@link SELECT_COLUMN_ID}. */
 export const MUI_CHECKBOX_FIELD = '__check__';
 

package/src/useDataGridTable.ts

@@ -1,12 +1,14 @@
-import { useMemo } from 'react';
+import { useMemo, useState } from 'react';
 import {
   columnFilteringFeature,
   columnPinningFeature,
+  columnVisibilityFeature,
   createFilteredRowModel,
   createPaginatedRowModel,
   createSortedRowModel,
   filterFn_includesString,
   globalFilteringFeature,
+  rowExpandingFeature,
   rowPaginationFeature,
   rowSelectionFeature,
   rowSortingFeature,
@@ -20,7 +22,16 @@ import {
   type RowSelectionState,
   type SortingState,
 } from '@tanstack/react-table';
-import { createSelectColumn } from './adapter/selectColumn';
+import { createDetailPanelToggleColumn, createSelectColumn } from './adapter/selectColumn';
+import {
+  applyTreeSelection,
+  buildTreeIndex,
+  computeTreeSelection,
+  keepMatchesWithAncestors,
+  selectionScope,
+  type GridTreeRowLike,
+  type GridTreeSelectionStatus,
+} from './adapter/treeData';
 import { applyUpdater, gridColDefToColumnDef } from './adapter/columns';
 import {
   filterFn_displayText,
@@ -42,6 +53,7 @@ import {
 } from './adapter/filterOperators';
 import type {
   GridColDef,
+  GridColumnVisibilityModel,
   GridFeatureMode,
   GridFilterItem,
   GridFilterModel,
@@ -49,18 +61,20 @@ import type {
   GridPaginationModel,
   GridRowId,
   GridRowSelectionModel,
+  GridRowSelectionPropagation,
   GridRowsProp,
   GridSortModel,
+  GridTreeNodeParams,
   GridValidRowModel,
 } from './types';
-import { SELECT_COLUMN_ID } from './types';
+import { DETAIL_PANEL_TOGGLE_ID, SELECT_COLUMN_ID } from './types';
 
 function gridGlobalFilterFn(
   row: Parameters<typeof filterFn_displayText>[0],
   columnId: string,
   filterValue: unknown,
 ): boolean {
-  if (columnId === SELECT_COLUMN_ID) {
+  if (columnId === SELECT_COLUMN_ID || columnId === DETAIL_PANEL_TOGGLE_ID) {
     return false;
   }
   const meta = row.getAllCells().find((cell) => cell.column.id === columnId)?.column.columnDef.meta;
@@ -73,7 +87,9 @@ function gridGlobalFilterFn(
 const features = tableFeatures({
   columnFilteringFeature,
   columnPinningFeature,
+  columnVisibilityFeature,
   globalFilteringFeature,
+  rowExpandingFeature,
   rowSortingFeature,
   rowPaginationFeature,
   rowSelectionFeature,
@@ -275,8 +291,30 @@ interface UseDataGridTableParams<R extends GridValidRowModel> {
   rowSelectionModel: GridRowSelectionModel;
   onRowSelectionModelChange: (model: GridRowSelectionModel) => void;
   columnPinning: ColumnPinningState;
+  columnVisibility?: GridColumnVisibilityModel;
+  detailPanel?: boolean;
+  treeData?: boolean;
+  getTreeDataPath?: (row: R) => readonly string[];
+  defaultGroupingExpansionDepth?: number;
+  isGroupExpandedByDefault?: (node: GridTreeNodeParams<R>) => boolean;
+  rowSelectionPropagation?: GridRowSelectionPropagation;
+}
+
+export interface DataGridTreeState {
+  isRowExpanded: (key: string) => boolean;
+  toggleRowExpanded: (key: string) => void;
+  selectionStatus: (key: string) => GridTreeSelectionStatus;
+  toggleRowSelected: (row: GridTreeRowLike) => void;
+  toggleAllRowsSelected: () => void;
+  headerSelection: { checked: boolean; indeterminate: boolean };
 }
 
+const EMPTY_EXPANSION: Readonly<Record<string, boolean>> = {};
+const EMPTY_FILTER_EXPANSION: Readonly<Partial<Record<string, boolean>>> = {};
+const EMPTY_VISIBILITY: GridColumnVisibilityModel = {};
+
+let warnedMissingTreeDataPath = false;
+
 export function useDataGridTable<R extends GridValidRowModel>({
   rows,
   columns,
@@ -299,7 +337,22 @@ export function useDataGridTable<R extends GridValidRowModel>({
   rowSelectionModel,
   onRowSelectionModelChange,
   columnPinning,
+  columnVisibility = EMPTY_VISIBILITY,
+  detailPanel = false,
+  treeData: treeDataProp = false,
+  getTreeDataPath,
+  defaultGroupingExpansionDepth = 0,
+  isGroupExpandedByDefault,
+  rowSelectionPropagation,
 }: UseDataGridTableParams<R>) {
+  const treeData = treeDataProp && getTreeDataPath !== undefined;
+  if (__DEV__ && treeDataProp && getTreeDataPath === undefined && !warnedMissingTreeDataPath) {
+    warnedMissingTreeDataPath = true;
+    console.warn('[DataGrid] `treeData` needs `getTreeDataPath`. Rendering flat rows.');
+  }
+  const propagateDescendants = rowSelectionPropagation?.descendants ?? true;
+  const propagateParents = rowSelectionPropagation?.parents ?? true;
+
   const orFilterItems = useMemo(() => {
     if (filterLogicOperator !== 'or' || filterMode === 'server') {
       return undefined;
@@ -308,6 +361,13 @@ export function useDataGridTable<R extends GridValidRowModel>({
     return active.length > 1 ? active : undefined;
   }, [filterLogicOperator, filterMode, filterModel]);
 
+  const keyOf = useMemo(() => (row: R) => selectionIdKey(resolveRowId(row, getRowId)), [getRowId]);
+
+  const fullTree = useMemo(
+    () => (treeData ? buildTreeIndex(rows, getTreeDataPath, keyOf) : undefined),
+    [getTreeDataPath, keyOf, rows, treeData],
+  );
+
   const data = useMemo(() => {
     if (!orFilterItems) {
       return [...rows];
@@ -315,14 +375,24 @@ export function useDataGridTable<R extends GridValidRowModel>({
     const filterableColumns = new Map(
       columns.filter((col) => col.filterable !== false).map((col) => [col.field, col]),
     );
-    return rows.filter((row) =>
+    const matches = (row: R) =>
       orFilterItems.some((item) => {
         const col = filterableColumns.get(item.field);
         return col !== undefined && rowMatchesFilterItem(col, row, item);
-      }),
-    );
-  }, [columns, orFilterItems, rows]);
+      });
+    return fullTree
+      ? keepMatchesWithAncestors(rows, fullTree, keyOf, matches)
+      : rows.filter(matches);
+  }, [columns, fullTree, keyOf, orFilterItems, rows]);
   const allIds = useMemo(() => data.map((row) => resolveRowId(row, getRowId)), [data, getRowId]);
+  const allRowIds = useMemo(() => rows.map((row) => resolveRowId(row, getRowId)), [rows, getRowId]);
+
+  const tree = useMemo(() => {
+    if (!fullTree || !getTreeDataPath) {
+      return undefined;
+    }
+    return data.length === rows.length ? fullTree : buildTreeIndex(data, getTreeDataPath, keyOf);
+  }, [data, fullTree, getTreeDataPath, keyOf, rows.length]);
 
   const columnDefs = useMemo(() => {
     const mapped = columns.map((col) => {
@@ -332,8 +402,12 @@ export function useDataGridTable<R extends GridValidRowModel>({
       }
       return def;
     });
-    return checkboxSelection ? [createSelectColumn(), ...mapped] : mapped;
-  }, [checkboxSelection, columns, disableColumnSorting]);
+    return [
+      ...(checkboxSelection && !treeData ? [createSelectColumn()] : []),
+      ...(detailPanel ? [createDetailPanelToggleColumn()] : []),
+      ...mapped,
+    ];
+  }, [checkboxSelection, columns, detailPanel, disableColumnSorting, treeData]);
 
   const sortingState = useMemo(() => sortModelToSortingState(sortModel), [sortModel]);
   const paginationState = useMemo(() => paginationModelToState(paginationModel), [paginationModel]);
@@ -342,10 +416,79 @@ export function useDataGridTable<R extends GridValidRowModel>({
     [filterModel, orFilterItems],
   );
   const rowSelectionState = useMemo(
-    () => selectionModelToRowSelection(rowSelectionModel, allIds),
-    [rowSelectionModel, allIds],
+    () => selectionModelToRowSelection(rowSelectionModel, treeData ? allRowIds : allIds),
+    [rowSelectionModel, treeData, allRowIds, allIds],
   );
 
+  const filterSignature =
+    treeData &&
+    filterMode === 'client' &&
+    (quickFilter.trim().length > 0 || filterModel.some(isActiveFilterItem))
+      ? JSON.stringify([quickFilter, filterModel, filterLogicOperator])
+      : '';
+  const [userExpanded, setUserExpanded] = useState<Partial<Record<string, boolean>>>({});
+  const [filterExpansion, setFilterExpansion] = useState<{
+    signature: string;
+    expanded: Partial<Record<string, boolean>>;
+  }>({ signature: '', expanded: {} });
+  const filterExpanded =
+    filterSignature !== '' && filterExpansion.signature === filterSignature
+      ? filterExpansion.expanded
+      : EMPTY_FILTER_EXPANSION;
+
+  const expandedState = useMemo(() => {
+    if (!tree) {
+      return EMPTY_EXPANSION;
+    }
+    const isExpanded = (key: string): boolean => {
+      if (filterSignature !== '') {
+        return filterExpanded[key] ?? true;
+      }
+      const own = userExpanded[key];
+      if (own !== undefined) {
+        return own;
+      }
+      const row = tree.rowOf.get(key);
+      const depth = fullTree?.depthOf.get(key) ?? tree.depthOf.get(key) ?? 0;
+      if (row !== undefined && isGroupExpandedByDefault) {
+        return isGroupExpandedByDefault({ id: resolveRowId(row, getRowId), row, depth });
+      }
+      return defaultGroupingExpansionDepth === -1 || depth < defaultGroupingExpansionDepth;
+    };
+    const state: Record<string, boolean> = {};
+    for (const key of tree.childKeysOf.keys()) {
+      if (isExpanded(key)) {
+        state[key] = true;
+      }
+    }
+    return state;
+  }, [
+    tree,
+    fullTree,
+    filterSignature,
+    filterExpanded,
+    userExpanded,
+    isGroupExpandedByDefault,
+    defaultGroupingExpansionDepth,
+    getRowId,
+  ]);
+  const isRowExpanded = (key: string) => key in expandedState;
+
+  const toggleRowExpanded = (key: string) => {
+    const next = !isRowExpanded(key);
+    if (filterSignature !== '') {
+      setFilterExpansion((previous) => ({
+        signature: filterSignature,
+        expanded: {
+          ...(previous.signature === filterSignature ? previous.expanded : {}),
+          [key]: next,
+        },
+      }));
+      return;
+    }
+    setUserExpanded((previous) => ({ ...previous, [key]: next }));
+  };
+
   const resetPaginationPage = () => {
     if (paginationModel.page !== 0) {
       onPaginationModelChange({ ...paginationModel, page: 0 });
@@ -369,8 +512,11 @@ export function useDataGridTable<R extends GridValidRowModel>({
   const table = useTable({
     features,
     columns: columnDefs,
-    data,
-    getRowId: (row) => selectionIdKey(resolveRowId(row, getRowId)),
+    data: tree ? tree.roots : data,
+    getRowId: (row) => keyOf(row),
+    getSubRows: tree ? (row) => tree.childrenOf.get(row) : undefined,
+    filterFromLeafRows: treeData,
+    paginateExpandedRows: false,
     enableMultiSort: false,
     enableMultiRowSelection: true,
     globalFilterFn: gridGlobalFilterFn,
@@ -386,6 +532,8 @@ export function useDataGridTable<R extends GridValidRowModel>({
       globalFilter: quickFilter,
       rowSelection: rowSelectionState,
       columnPinning,
+      columnVisibility,
+      expanded: expandedState,
     },
     onSortingChange: (updater) => {
       const next = applyUpdater(updater, sortingState);
@@ -416,5 +564,59 @@ export function useDataGridTable<R extends GridValidRowModel>({
     resetPaginationPage();
   };
 
-  return { table, setQuickFilter, setColumnFilter, setFilterModel };
+  const treeSelection = useMemo(() => {
+    if (!fullTree) {
+      return undefined;
+    }
+    const selectedKeys = new Set(Object.keys(rowSelectionState));
+    return {
+      selectedKeys,
+      statuses: computeTreeSelection(fullTree, selectedKeys, propagateParents),
+    };
+  }, [fullTree, propagateParents, rowSelectionState]);
+
+  let treeState: DataGridTreeState | undefined;
+  if (fullTree && treeSelection) {
+    const { selectedKeys, statuses } = treeSelection;
+    const selectionStatus = (key: string) => statuses.get(key) ?? 'none';
+    const commit = (scope: { targets: string[]; units: string[] }) => {
+      const value = !scope.units.every((key) => selectionStatus(key) === 'all');
+      const next = applyTreeSelection(
+        fullTree,
+        selectedKeys,
+        scope.targets,
+        value,
+        propagateParents,
+      );
+      onRowSelectionModelChange(
+        rowSelectionToModel(
+          Object.fromEntries([...next].map((key) => [key, true])),
+          rowSelectionModel,
+          allRowIds,
+        ),
+      );
+    };
+    const filtered = table.getFilteredRowModel();
+    const headerScope = propagateDescendants
+      ? selectionScope(filtered.rows, fullTree, true)
+      : selectionScope(filtered.flatRows, fullTree, false);
+    const selectedUnits = headerScope.units.filter((key) => selectionStatus(key) !== 'none');
+    const allUnitsSelected =
+      headerScope.units.length > 0 &&
+      headerScope.units.every((key) => selectionStatus(key) === 'all');
+
+    treeState = {
+      isRowExpanded,
+      toggleRowExpanded,
+      selectionStatus,
+      toggleRowSelected: (row) => commit(selectionScope([row], fullTree, propagateDescendants)),
+      toggleAllRowsSelected: () => commit(headerScope),
+      headerSelection: {
+        checked: allUnitsSelected,
+        indeterminate: !allUnitsSelected && selectedUnits.length > 0,
+      },
+    };
+  }
+
+  return { table, setQuickFilter, setColumnFilter, setFilterModel, tree: treeState };
 }