@cdx-ui/data-grid 0.3.11 → 0.3.13

package/src/styles.ts

@@ -38,6 +38,51 @@ export const dataGridMainVariants = cva(
   },
 );
 
+/**
+ * Opaque sticky fill so pinned cells cover scrolled content.
+ * Body hover matches the row's 50% secondary tint, mixed over the primary surface
+ * so the cell stays opaque while content scrolls underneath.
+ */
+export const dataGridPinnedSurfaceVariants = cva(
+  Platform.select({
+    web: 'bg-surface-primary',
+    default: '',
+  }),
+  {
+    variants: {
+      header: {
+        true: 'bg-neutral-50',
+        false: Platform.select({
+          web: 'web:[tr:hover_&]:bg-[color-mix(in_srgb,var(--color-surface-secondary)_50%,var(--color-surface-primary))]',
+          default: '',
+        }),
+      },
+    },
+    defaultVariants: {
+      header: false,
+    },
+  },
+);
+
+export const dataGridPinnedEdgeVariants = cva('', {
+  variants: {
+    edge: {
+      start: Platform.select({
+        web: 'border-e border-stroke-secondary',
+        default: '',
+      }),
+      end: Platform.select({
+        web: 'border-s border-stroke-secondary',
+        default: '',
+      }),
+      none: '',
+    },
+  },
+  defaultVariants: {
+    edge: 'none',
+  },
+});
+
 export const dataGridToolbarVariants = cva(
   'shrink-0 flex-row items-center gap-3 border-b border-stroke-secondary px-4 py-4',
 );
@@ -135,6 +180,49 @@ 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(
+  '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
+// onto new lines and grow to fill them, so the layout follows the grid's width, not the viewport.
+export const dataGridFilterPanelRowVariants = cva('flex-row flex-wrap items-end gap-2');
+
+export const dataGridFilterPanelLogicVariants = cva('min-h-8 w-24 shrink-0 justify-center');
+
+export const dataGridFilterPanelFieldVariants = cva('min-w-0 shrink grow gap-1', {
+  variants: {
+    size: {
+      column: 'w-40',
+      operator: 'w-40',
+      value: 'w-56',
+    },
+  },
+});
+
+export const dataGridFilterPanelColumnVariants = cva('w-full');
+
+export const dataGridFilterPanelOperatorVariants = cva('w-full');
+
+export const dataGridFilterPanelValueVariants = cva('w-full');
+
+export const dataGridFilterPanelFooterVariants = cva(
+  'flex-row items-center justify-between gap-2 border-t border-stroke-secondary pt-2',
+);
+
 export const dataGridHeadVariants = cva([
   'h-12 bg-neutral-50 px-4',
   Platform.select({
@@ -159,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

@@ -28,21 +28,92 @@ export interface GridRowSelectionModel {
   ids: Set<GridRowId>;
 }
 
+/**
+ * Filter operators. Names match MUI Data Grid Community so server handlers written for
+ * MUI keep working. Which operators a column accepts depends on its `type`.
+ */
+export type GridFilterOperator =
+  | 'contains'
+  | 'doesNotContain'
+  | 'equals'
+  | 'doesNotEqual'
+  | 'startsWith'
+  | 'endsWith'
+  | 'isEmpty'
+  | 'isNotEmpty'
+  | 'isAnyOf'
+  | '='
+  | '!='
+  | '>'
+  | '>='
+  | '<'
+  | '<='
+  | 'is'
+  | 'not'
+  | 'after'
+  | 'onOrAfter'
+  | 'before'
+  | 'onOrBefore';
+
 export interface GridFilterItem {
   field: string;
-  value: string;
+  /** Defaults to `'contains'`, a case-insensitive substring match on the displayed text. */
+  operator?: GridFilterOperator;
+  /**
+   * Operand for `operator`: a string for text, a number for `number`, a `Date` for `date` /
+   * `dateTime`, a boolean for `boolean`, a `singleSelect` option value, or an array for
+   * `isAnyOf`. `isEmpty` and `isNotEmpty` ignore it.
+   */
+  value?: unknown;
 }
 
 export type GridFilterModel = GridFilterItem[];
 
+/**
+ * Columns pinned to the logical start and end edges while the grid scrolls
+ * horizontally.
+ *
+ * `left` and `right` are deprecated compatibility aliases for `start` and `end`
+ * (same mapping as `GridColDef.align`).
+ */
+export interface GridPinnedColumnFields {
+  start?: string[];
+  end?: string[];
+  /**
+   * @deprecated Use `start` instead.
+   */
+  left?: string[];
+  /**
+   * @deprecated Use `end` instead.
+   */
+  right?: string[];
+}
+
+/** How `filterModel` items combine: every item must match (`'and'`) or any one item (`'or'`). */
+export type GridLogicOperator = 'and' | 'or';
+
 export interface GridRenderCellParams<R extends GridValidRowModel = GridValidRowModel> {
   value: unknown;
   row: R;
   field: string;
   id: GridRowId;
+  /** The column being rendered, including props spread after a column preset. */
+  col: GridColDef<R>;
 }
 
-export interface GridColDef<R extends GridValidRowModel = GridValidRowModel> {
+/**
+ * Built-in column types. Names and defaults match MUI Data Grid Community.
+ * Omit `type` to keep untyped display, alignment, and sort.
+ */
+export type GridColType = 'string' | 'number' | 'date' | 'dateTime' | 'boolean' | 'singleSelect';
+
+/**
+ * A `singleSelect` choice: a primitive (value and label are the same) or an
+ * explicit `{ value, label }` pair.
+ */
+export type GridValueOption = string | number | { value: string | number; label: string };
+
+export interface GridBaseColDef<R extends GridValidRowModel = GridValidRowModel> {
   field: string;
   headerName?: string;
   width?: number;
@@ -52,28 +123,74 @@ export interface GridColDef<R extends GridValidRowModel = GridValidRowModel> {
    * Logical cell-content alignment.
    *
    * `left` and `right` are deprecated compatibility aliases for `start` and `end`.
-   * @default 'start'
+   * When omitted, `number` defaults to `end`, `boolean` to `center`, and every
+   * other type (including omitted `type`) to `start`.
    */
   align?: GridAlignment;
   /**
-   * Logical header-content alignment. Defaults to `align`.
+   * Logical header-content alignment. Defaults to `align`, then the type default.
    *
    * `left` and `right` are deprecated compatibility aliases for `start` and `end`.
    */
   headerAlign?: GridAlignment;
   sortable?: boolean;
   filterable?: boolean;
-  type?: 'string';
+  /**
+   * Column value type. Drives default alignment, display formatting, and client
+   * sort/filter. Omitted `type` keeps the untyped defaults from the current release.
+   */
+  type?: Exclude<GridColType, 'singleSelect'>;
   valueGetter?: (value: unknown, row: R, col: GridColDef<R>) => unknown;
   valueFormatter?: (value: unknown, row: R, col: GridColDef<R>) => ReactNode | string;
   renderCell?: (params: GridRenderCellParams<R>) => ReactNode;
   renderHeader?: () => ReactNode;
 }
 
+export interface GridSingleSelectColDef<
+  R extends GridValidRowModel = GridValidRowModel,
+> extends Omit<GridBaseColDef<R>, 'type'> {
+  type: 'singleSelect';
+  /**
+   * Choices for a `singleSelect` column. Use `{ value, label }` when the stored
+   * value differs from the displayed text. A function receives the row when labels
+   * depend on other fields.
+   */
+  valueOptions: readonly GridValueOption[] | ((params: { row?: R }) => readonly GridValueOption[]);
+}
+
+export type GridColDef<R extends GridValidRowModel = GridValidRowModel> =
+  | GridBaseColDef<R>
+  | GridSingleSelectColDef<R>;
+
 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>[];
@@ -114,14 +231,72 @@ export interface DataGridProps<R extends GridValidRowModel = GridValidRowModel>
   filterModel?: GridFilterModel;
   defaultFilterModel?: GridFilterModel;
   onFilterModelChange?: (model: GridFilterModel) => void;
+  /** Combines `filterModel` items. Defaults to `'and'`. The quick filter always applies on top. */
+  filterLogicOperator?: GridLogicOperator;
+  defaultFilterLogicOperator?: GridLogicOperator;
+  onFilterLogicOperatorChange?: (operator: GridLogicOperator) => void;
   quickFilter?: string;
   defaultQuickFilter?: string;
   onQuickFilterChange?: (value: string) => void;
-  /** Shows the toolbar search field. Off by default, same as MUI Community. */
+  /** Shows the toolbar search field and filter button. Off by default, same as MUI Community. */
   showToolbar?: boolean;
-  /** Consumer-owned toolbar controls beside search (export, density, toggles, etc.). Wire actions to app state that drives grid props — DataGrid does not ship toolbar buttons. */
+  /** Consumer-owned toolbar controls beside search and the filter button (export, density, toggles, etc.). Wire actions to app state that drives grid props. */
   toolbarActions?: ReactNode;
+  /**
+   * Pins columns to the logical start and/or end edge while the grid scrolls
+   * horizontally. Replaces MUI X Pro `pinnedColumns` (including deprecated
+   * `left` / `right` aliases). MUI X `initialState.pinnedColumns` maps here.
+   *
+   * 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. */
@@ -135,6 +310,14 @@ 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__';
+
 export const DEFAULT_PAGE_SIZE_OPTIONS = [25, 50, 100] as const;
 
 export const DEFAULT_PAGINATION_MODEL: GridPaginationModel = {

package/src/useDataGridTable.test.ts

@@ -2,10 +2,79 @@ import type { RowSelectionState } from '@tanstack/react-table';
 import type { GridRowId } from './types';
 import {
   columnFiltersToFilterModel,
+  filterModelToColumnFilters,
   rowSelectionToModel,
   selectionModelToRowSelection,
 } from './useDataGridTable';
 
+describe('filterModelToColumnFilters', () => {
+  it('keeps items without an operator as text filters and drops blank ones', () => {
+    expect(
+      filterModelToColumnFilters([
+        { field: 'name', value: 'alice' },
+        { field: 'status', value: '  ' },
+        { field: 'age' },
+      ]),
+    ).toEqual([{ id: 'name', value: 'alice' }]);
+  });
+
+  it('groups several items on one field and round-trips them', () => {
+    const model = [
+      { field: 'amount', operator: '>' as const, value: 1 },
+      { field: 'amount', operator: '<' as const, value: 9 },
+    ];
+    const state = filterModelToColumnFilters(model);
+
+    expect(state).toEqual([
+      {
+        id: 'amount',
+        value: {
+          items: [
+            { operator: '>', value: 1 },
+            { operator: '<', value: 9 },
+          ],
+        },
+      },
+    ]);
+    expect(columnFiltersToFilterModel(state)).toEqual(model);
+  });
+
+  it('carries the operator and typed operand', () => {
+    expect(filterModelToColumnFilters([{ field: 'amount', operator: '>', value: 100 }])).toEqual([
+      { id: 'amount', value: { operator: '>', value: 100 } },
+    ]);
+  });
+
+  it('keeps isEmpty and isNotEmpty without a value', () => {
+    expect(
+      filterModelToColumnFilters([
+        { field: 'a', operator: 'isEmpty' },
+        { field: 'b', operator: 'isNotEmpty', value: '' },
+      ]),
+    ).toEqual([
+      { id: 'a', value: { operator: 'isEmpty', value: undefined } },
+      { id: 'b', value: { operator: 'isNotEmpty', value: '' } },
+    ]);
+  });
+
+  it('drops value operators whose operand is blank', () => {
+    expect(
+      filterModelToColumnFilters([
+        { field: 'a', operator: '>' },
+        { field: 'b', operator: 'isAnyOf', value: [] },
+        { field: 'c', operator: 'contains', value: ' ' },
+      ]),
+    ).toEqual([]);
+  });
+});
+
+describe('columnFiltersToFilterModel with operators', () => {
+  it('round-trips operator filters', () => {
+    const model = [{ field: 'amount', operator: '<=' as const, value: 5 }];
+    expect(columnFiltersToFilterModel(filterModelToColumnFilters(model))).toEqual(model);
+  });
+});
+
 describe('columnFiltersToFilterModel', () => {
   it('keeps string filter values', () => {
     expect(columnFiltersToFilterModel([{ id: 'name', value: 'alice' }])).toEqual([