@cdx-ui/data-grid 0.0.1-beta.185

package/src/adapter/selectColumn.ts

@@ -0,0 +1,12 @@
+import { SELECT_COLUMN_ID } from '../types';
+
+export function createSelectColumn() {
+  return {
+    id: SELECT_COLUMN_ID,
+    header: SELECT_COLUMN_ID,
+    enableSorting: false,
+    enableColumnFilter: false,
+    enableGlobalFilter: false,
+    size: 48,
+  } as const;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export { DataGrid } from './DataGrid';
+export type {
+  DataGridProps,
+  GridAlignment,
+  GridColDef,
+  GridFilterItem,
+  GridFilterModel,
+  GridPaginationModel,
+  GridRenderCellParams,
+  GridRowId,
+  GridRowSelectionModel,
+  GridRowsProp,
+  GridSortDirection,
+  GridSortItem,
+  GridSortModel,
+  GridValidRowModel,
+} from './types';

package/src/styles.ts

@@ -0,0 +1,104 @@
+import { Platform } from 'react-native';
+import { cva } from '@cdx-ui/utils';
+
+export const dataGridRootVariants = cva(
+  'h-[300px] w-full min-w-0 max-w-full flex-col overflow-hidden rounded-2xl border border-stroke-secondary bg-surface-primary',
+);
+
+export const dataGridMainVariants = cva(
+  'relative min-h-0 w-full min-w-0 max-w-full flex-1 overflow-auto',
+);
+
+export const dataGridToolbarVariants = cva(
+  'shrink-0 flex-row items-center gap-3 border-b border-stroke-secondary px-4 py-4',
+);
+
+export const dataGridToolbarSearchVariants = cva('max-w-80 min-w-0 flex-1');
+
+export const dataGridToolbarActionsVariants = cva('ms-auto flex-row items-center gap-3');
+
+export const dataGridFooterVariants = cva(
+  'min-h-[52px] shrink-0 flex-row items-center justify-end gap-2 border-t border-stroke-secondary py-0 pe-0.5 ps-6',
+);
+
+export const dataGridOverlayVariants = cva(
+  'absolute inset-x-0 bottom-0 items-center justify-center bg-surface-primary',
+  {
+    variants: {
+      headerFilters: {
+        true: 'top-24',
+        false: 'top-12',
+      },
+    },
+    defaultVariants: {
+      headerFilters: false,
+    },
+  },
+);
+
+export const dataGridEmptyOverlayVariants = cva(
+  'pointer-events-none absolute inset-0 items-center justify-center',
+);
+
+export const dataGridHeaderCellInnerVariants = cva('flex-row items-center gap-3');
+
+// Collapsed table borders scroll away from sticky headers; separated cell borders stick.
+export const dataGridTableVariants = cva(
+  Platform.select({
+    web: 'border-separate border-spacing-0',
+    default: '',
+  }),
+);
+
+export const dataGridHeaderVariants = cva([
+  'bg-neutral-50',
+  Platform.select({
+    web: 'sticky top-0 z-20',
+    default: '',
+  }),
+]);
+
+export const dataGridBodyVariants = cva(
+  Platform.select({
+    web: '[&_tr:last-child>*]:border-b-0',
+    default: '',
+  }),
+);
+
+export const dataGridFilterInputVariants = cva('min-w-24');
+
+export const dataGridHeadVariants = cva([
+  'h-12 bg-neutral-50 px-4',
+  Platform.select({
+    web: 'border-b border-stroke-secondary',
+    default: '',
+  }),
+]);
+
+export const dataGridSelectHeadVariants = cva([
+  'w-14 bg-neutral-50 px-4',
+  Platform.select({
+    web: 'border-b border-stroke-secondary',
+    default: '',
+  }),
+]);
+
+export const dataGridCellVariants = cva([
+  'h-12 px-4',
+  Platform.select({
+    web: 'border-b border-stroke-secondary',
+    default: '',
+  }),
+]);
+
+export const dataGridSelectCellVariants = cva([
+  'w-14 px-4',
+  Platform.select({
+    web: 'border-b border-stroke-secondary',
+    default: '',
+  }),
+]);
+
+export const dataGridPaginationVariants = cva('flex-row flex-wrap items-center justify-end gap-0');
+
+export const dataGridPaginationRangeVariants = cva('mx-5 shrink-0');

package/src/types.ts

@@ -0,0 +1,133 @@
+import type { ReactNode } from 'react';
+import type { ViewStyle } from 'react-native';
+
+export type GridRowId = string | number;
+
+export type GridValidRowModel = Record<string, unknown>;
+
+export type GridRowsProp<R extends GridValidRowModel = GridValidRowModel> = readonly R[];
+
+export type GridSortDirection = 'asc' | 'desc';
+
+export type GridAlignment = 'start' | 'center' | 'end' | 'left' | 'right';
+
+export interface GridSortItem {
+  field: string;
+  sort: GridSortDirection;
+}
+
+export type GridSortModel = GridSortItem[];
+
+export interface GridPaginationModel {
+  page: number;
+  pageSize: number;
+}
+
+export interface GridRowSelectionModel {
+  type: 'include' | 'exclude';
+  ids: Set<GridRowId>;
+}
+
+export interface GridFilterItem {
+  field: string;
+  value: string;
+}
+
+export type GridFilterModel = GridFilterItem[];
+
+export interface GridRenderCellParams<R extends GridValidRowModel = GridValidRowModel> {
+  value: unknown;
+  row: R;
+  field: string;
+  id: GridRowId;
+}
+
+export interface GridColDef<R extends GridValidRowModel = GridValidRowModel> {
+  field: string;
+  headerName?: string;
+  width?: number;
+  minWidth?: number;
+  flex?: number;
+  /**
+   * Logical cell-content alignment.
+   *
+   * `left` and `right` are deprecated compatibility aliases for `start` and `end`.
+   * @default 'start'
+   */
+  align?: GridAlignment;
+  /**
+   * Logical header-content alignment. Defaults to `align`.
+   *
+   * `left` and `right` are deprecated compatibility aliases for `start` and `end`.
+   */
+  headerAlign?: GridAlignment;
+  sortable?: boolean;
+  filterable?: boolean;
+  type?: 'string';
+  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 type GridPaginationMode = 'client' | 'server';
+
+export interface DataGridProps<R extends GridValidRowModel = GridValidRowModel> {
+  rows: GridRowsProp<R>;
+  columns: readonly GridColDef<R>[];
+  getRowId?: (row: R) => GridRowId;
+  /** Shows the loading overlay, disables pagination, and suppresses the empty state. */
+  loading?: boolean;
+  checkboxSelection?: boolean;
+  hideFooter?: boolean;
+  hideFooterPagination?: boolean;
+  disableColumnSorting?: boolean;
+  paginationMode?: GridPaginationMode;
+  sortingMode?: GridPaginationMode;
+  rowCount?: number;
+  sortModel?: GridSortModel;
+  defaultSortModel?: GridSortModel;
+  onSortModelChange?: (model: GridSortModel) => void;
+  paginationModel?: GridPaginationModel;
+  defaultPaginationModel?: GridPaginationModel;
+  onPaginationModelChange?: (model: GridPaginationModel) => void;
+  /** Options for the footer rows-per-page control. Defaults to 25, 50, 100. */
+  pageSizeOptions?: readonly (number | { value: number; label: string })[];
+  rowSelectionModel?: GridRowSelectionModel;
+  defaultRowSelectionModel?: GridRowSelectionModel;
+  onRowSelectionModelChange?: (model: GridRowSelectionModel) => void;
+  filterModel?: GridFilterModel;
+  defaultFilterModel?: GridFilterModel;
+  onFilterModelChange?: (model: GridFilterModel) => void;
+  quickFilter?: string;
+  defaultQuickFilter?: string;
+  onQuickFilterChange?: (value: string) => void;
+  /** Shows the toolbar search field. 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. */
+  toolbarActions?: ReactNode;
+  headerFilters?: boolean;
+  /** 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. */
+  loadingOverlay?: ReactNode;
+  className?: string;
+  style?: ViewStyle;
+  label?: string;
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+}
+
+export const SELECT_COLUMN_ID = '__select__';
+
+export const DEFAULT_PAGE_SIZE_OPTIONS = [25, 50, 100] as const;
+
+export const DEFAULT_PAGINATION_MODEL: GridPaginationModel = {
+  page: 0,
+  pageSize: 25,
+};
+
+export const EMPTY_SELECTION: GridRowSelectionModel = {
+  type: 'include',
+  ids: new Set(),
+};

package/src/useDataGridTable.test.ts

@@ -0,0 +1,125 @@
+import type { RowSelectionState } from '@tanstack/react-table';
+import type { GridRowId } from './types';
+import {
+  columnFiltersToFilterModel,
+  rowSelectionToModel,
+  selectionModelToRowSelection,
+} from './useDataGridTable';
+
+describe('columnFiltersToFilterModel', () => {
+  it('keeps string filter values', () => {
+    expect(columnFiltersToFilterModel([{ id: 'name', value: 'alice' }])).toEqual([
+      { field: 'name', value: 'alice' },
+    ]);
+  });
+
+  it('drops non-primitive filter values instead of stringifying objects', () => {
+    expect(columnFiltersToFilterModel([{ id: 'name', value: { nested: true } }])).toEqual([
+      { field: 'name', value: '' },
+    ]);
+  });
+
+  it('omits the select column', () => {
+    expect(
+      columnFiltersToFilterModel([
+        { id: '__select__', value: 'x' },
+        { id: 'status', value: 'active' },
+      ]),
+    ).toEqual([{ field: 'status', value: 'active' }]);
+  });
+});
+
+describe('selectionModelToRowSelection', () => {
+  const allIds: GridRowId[] = [1, 2, 3];
+
+  it('maps include models to TanStack row selection keys', () => {
+    const model = { type: 'include' as const, ids: new Set<GridRowId>([1, 2]) };
+    expect(selectionModelToRowSelection(model, allIds)).toEqual({
+      'number:1': true,
+      'number:2': true,
+    });
+  });
+
+  it('does not conflate string and numeric ids in exclude models', () => {
+    const model = { type: 'exclude' as const, ids: new Set<GridRowId>(['1']) };
+    expect(selectionModelToRowSelection(model, allIds)).toEqual({
+      'number:1': true,
+      'number:2': true,
+      'number:3': true,
+    });
+  });
+
+  it('maps exclude models when excluded ids are numeric', () => {
+    const model = { type: 'exclude' as const, ids: new Set<GridRowId>([2]) };
+    expect(selectionModelToRowSelection(model, allIds)).toEqual({
+      'number:1': true,
+      'number:3': true,
+    });
+  });
+
+  it('creates distinct table keys for string and numeric ids', () => {
+    const model = { type: 'include' as const, ids: new Set<GridRowId>([1, '1']) };
+    expect(selectionModelToRowSelection(model, [1, '1'])).toEqual({
+      'number:1': true,
+      'string:1': true,
+    });
+  });
+});
+
+describe('rowSelectionToModel', () => {
+  const allIds: GridRowId[] = [1, 2, 3];
+
+  it('round-trips include models with canonical numeric ids', () => {
+    const model = { type: 'include' as const, ids: new Set<GridRowId>([2, 3]) };
+    const state = selectionModelToRowSelection(model, allIds);
+    expect(rowSelectionToModel(state, model, allIds)).toEqual({
+      type: 'include',
+      ids: new Set([2, 3]),
+    });
+  });
+
+  it('round-trips exclude models preserving type and numeric ids', () => {
+    const model = { type: 'exclude' as const, ids: new Set<GridRowId>([1]) };
+    const state = selectionModelToRowSelection(model, allIds);
+    expect(rowSelectionToModel(state, model, allIds)).toEqual({
+      type: 'exclude',
+      ids: new Set([1]),
+    });
+  });
+
+  it('keeps exclude type after a user deselects a row', () => {
+    const model = { type: 'exclude' as const, ids: new Set<GridRowId>([1]) };
+    const next: RowSelectionState = { 'number:3': true };
+    expect(rowSelectionToModel(next, model, allIds)).toEqual({
+      type: 'exclude',
+      ids: new Set([1, 2]),
+    });
+  });
+
+  it('restores numeric ids after include selection changes', () => {
+    const model = { type: 'include' as const, ids: new Set<GridRowId>() };
+    const next: RowSelectionState = { 'number:1': true };
+    expect(rowSelectionToModel(next, model, allIds)).toEqual({
+      type: 'include',
+      ids: new Set([1]),
+    });
+  });
+
+  it('preserves included selections from unloaded server pages', () => {
+    const model = { type: 'include' as const, ids: new Set<GridRowId>([1]) };
+    const next: RowSelectionState = { 'number:2': true };
+    expect(rowSelectionToModel(next, model, [2])).toEqual({
+      type: 'include',
+      ids: new Set([1, 2]),
+    });
+  });
+
+  it('preserves excluded selections from unloaded server pages', () => {
+    const model = { type: 'exclude' as const, ids: new Set<GridRowId>([1]) };
+    const next: RowSelectionState = { 'number:2': true };
+    expect(rowSelectionToModel(next, model, [2])).toEqual({
+      type: 'exclude',
+      ids: new Set([1]),
+    });
+  });
+});

package/src/useDataGridTable.ts

@@ -0,0 +1,295 @@
+import { useMemo } from 'react';
+import {
+  columnFilteringFeature,
+  createFilteredRowModel,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  filterFn_includesString,
+  globalFilteringFeature,
+  rowPaginationFeature,
+  rowSelectionFeature,
+  rowSortingFeature,
+  sortFn_alphanumeric,
+  sortFn_text,
+  tableFeatures,
+  useTable,
+  type ColumnFiltersState,
+  type PaginationState,
+  type RowSelectionState,
+  type SortingState,
+} from '@tanstack/react-table';
+import { createSelectColumn } from './adapter/selectColumn';
+import { applyUpdater, gridColDefToColumnDef } from './adapter/columns';
+import type {
+  GridColDef,
+  GridFilterModel,
+  GridPaginationModel,
+  GridRowId,
+  GridRowSelectionModel,
+  GridRowsProp,
+  GridSortModel,
+  GridValidRowModel,
+} from './types';
+import { SELECT_COLUMN_ID } from './types';
+
+const features = tableFeatures({
+  columnFilteringFeature,
+  globalFilteringFeature,
+  rowSortingFeature,
+  rowPaginationFeature,
+  rowSelectionFeature,
+  filteredRowModel: createFilteredRowModel(),
+  sortedRowModel: createSortedRowModel(),
+  paginatedRowModel: createPaginatedRowModel(),
+  filterFns: { includesString: filterFn_includesString },
+  sortFns: { alphanumeric: sortFn_alphanumeric, text: sortFn_text },
+});
+
+export function sortModelToSortingState(model: GridSortModel): SortingState {
+  return model.map((item) => ({ id: item.field, desc: item.sort === 'desc' }));
+}
+
+export function sortingStateToSortModel(state: SortingState): GridSortModel {
+  return state
+    .filter((item) => item.id !== SELECT_COLUMN_ID)
+    .slice(0, 1)
+    .map((item) => ({
+      field: item.id,
+      sort: item.desc ? 'desc' : 'asc',
+    }));
+}
+
+export function paginationModelToState(model: GridPaginationModel): PaginationState {
+  return { pageIndex: model.page, pageSize: model.pageSize };
+}
+
+export function paginationStateToModel(state: PaginationState): GridPaginationModel {
+  return { page: state.pageIndex, pageSize: state.pageSize };
+}
+
+function columnFilterValueToString(value: unknown): string {
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (value == null) {
+    return '';
+  }
+  if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+    return String(value);
+  }
+  return '';
+}
+
+export function filterModelToColumnFilters(model: GridFilterModel): ColumnFiltersState {
+  return model
+    .filter((item) => item.value.trim().length > 0)
+    .map((item) => ({ id: item.field, value: item.value }));
+}
+
+export function columnFiltersToFilterModel(state: ColumnFiltersState): GridFilterModel {
+  return state
+    .filter((item) => item.id !== SELECT_COLUMN_ID)
+    .map((item) => ({ field: item.id, value: columnFilterValueToString(item.value) }));
+}
+
+function selectionIdKey(id: GridRowId): string {
+  return `${typeof id}:${String(id)}`;
+}
+
+export function selectionModelToRowSelection(
+  model: GridRowSelectionModel,
+  allIds: GridRowId[],
+): RowSelectionState {
+  const selected = new Set<string>();
+  if (model.type === 'include') {
+    for (const id of model.ids) {
+      selected.add(selectionIdKey(id));
+    }
+  } else {
+    for (const id of allIds) {
+      if (!model.ids.has(id)) {
+        selected.add(selectionIdKey(id));
+      }
+    }
+  }
+  return Object.fromEntries([...selected].map((id) => [id, true]));
+}
+
+export function rowSelectionToModel(
+  state: RowSelectionState,
+  previousModel: GridRowSelectionModel,
+  allIds: GridRowId[],
+): GridRowSelectionModel {
+  const currentIdsByKey = new Map<string, GridRowId>();
+  for (const id of allIds) {
+    currentIdsByKey.set(selectionIdKey(id), id);
+  }
+
+  const selectedKeys = new Set(Object.keys(state).filter((key) => state[key]));
+  const ids = new Set(previousModel.ids);
+
+  if (previousModel.type === 'exclude') {
+    for (const [key, id] of currentIdsByKey) {
+      if (selectedKeys.has(key)) {
+        ids.delete(id);
+      } else {
+        ids.add(id);
+      }
+    }
+    return { type: 'exclude', ids };
+  }
+
+  for (const [key, id] of currentIdsByKey) {
+    if (selectedKeys.has(key)) {
+      ids.add(id);
+    } else {
+      ids.delete(id);
+    }
+  }
+  return { type: 'include', ids };
+}
+
+export function resolveRowId<R extends GridValidRowModel>(
+  row: R,
+  getRowId?: (row: R) => GridRowId,
+): GridRowId {
+  if (getRowId) {
+    return getRowId(row);
+  }
+  const id = row.id;
+  if (typeof id === 'string' || typeof id === 'number') {
+    return id;
+  }
+  if (__DEV__) {
+    console.warn(
+      '[DataGrid] Each row needs an `id` or a `getRowId` function. Missing ids break selection.',
+    );
+  }
+  return '';
+}
+
+interface UseDataGridTableParams<R extends GridValidRowModel> {
+  rows: GridRowsProp<R>;
+  columns: readonly GridColDef<R>[];
+  getRowId?: (row: R) => GridRowId;
+  checkboxSelection: boolean;
+  disableColumnSorting: boolean;
+  paginationMode: 'client' | 'server';
+  sortingMode: 'client' | 'server';
+  rowCount?: number;
+  sortModel: GridSortModel;
+  onSortModelChange: (model: GridSortModel) => void;
+  paginationModel: GridPaginationModel;
+  onPaginationModelChange: (model: GridPaginationModel) => void;
+  filterModel: GridFilterModel;
+  onFilterModelChange: (model: GridFilterModel) => void;
+  quickFilter: string;
+  onQuickFilterChange: (value: string) => void;
+  rowSelectionModel: GridRowSelectionModel;
+  onRowSelectionModelChange: (model: GridRowSelectionModel) => void;
+}
+
+export function useDataGridTable<R extends GridValidRowModel>({
+  rows,
+  columns,
+  getRowId,
+  checkboxSelection,
+  disableColumnSorting,
+  paginationMode,
+  sortingMode,
+  rowCount,
+  sortModel,
+  onSortModelChange,
+  paginationModel,
+  onPaginationModelChange,
+  filterModel,
+  onFilterModelChange,
+  quickFilter,
+  onQuickFilterChange,
+  rowSelectionModel,
+  onRowSelectionModelChange,
+}: UseDataGridTableParams<R>) {
+  const data = useMemo(() => [...rows], [rows]);
+  const allIds = useMemo(() => data.map((row) => resolveRowId(row, getRowId)), [data, getRowId]);
+
+  const columnDefs = useMemo(() => {
+    const mapped = columns.map((col) => {
+      const def = gridColDefToColumnDef(col);
+      if (disableColumnSorting) {
+        def.enableSorting = false;
+      }
+      return def;
+    });
+    return checkboxSelection ? [createSelectColumn(), ...mapped] : mapped;
+  }, [checkboxSelection, columns, disableColumnSorting]);
+
+  const sortingState = useMemo(() => sortModelToSortingState(sortModel), [sortModel]);
+  const paginationState = useMemo(() => paginationModelToState(paginationModel), [paginationModel]);
+  const columnFilterState = useMemo(() => filterModelToColumnFilters(filterModel), [filterModel]);
+  const rowSelectionState = useMemo(
+    () => selectionModelToRowSelection(rowSelectionModel, allIds),
+    [rowSelectionModel, allIds],
+  );
+
+  const resetPaginationPage = () => {
+    onPaginationModelChange({ ...paginationModel, page: 0 });
+  };
+
+  const setQuickFilter = (value: string) => {
+    onQuickFilterChange(value);
+    resetPaginationPage();
+  };
+
+  const setColumnFilter = (field: string, value: string) => {
+    const next = filterModel.filter((item) => item.field !== field);
+    if (value.trim().length > 0) {
+      next.push({ field, value });
+    }
+    onFilterModelChange(next);
+    resetPaginationPage();
+  };
+
+  const table = useTable({
+    features,
+    columns: columnDefs,
+    data,
+    getRowId: (row) => selectionIdKey(resolveRowId(row, getRowId)),
+    enableMultiSort: false,
+    enableMultiRowSelection: true,
+    manualPagination: paginationMode === 'server',
+    manualSorting: sortingMode === 'server',
+    autoResetPageIndex: false,
+    rowCount: paginationMode === 'server' ? rowCount : undefined,
+    state: {
+      sorting: sortingState,
+      pagination: paginationState,
+      columnFilters: columnFilterState,
+      globalFilter: quickFilter,
+      rowSelection: rowSelectionState,
+    },
+    onSortingChange: (updater) => {
+      const next = applyUpdater(updater, sortingState);
+      onSortModelChange(sortingStateToSortModel(next));
+      resetPaginationPage();
+    },
+    onPaginationChange: (updater) => {
+      const next = applyUpdater(updater, paginationState);
+      onPaginationModelChange(paginationStateToModel(next));
+    },
+    onColumnFiltersChange: (updater) => {
+      const next = applyUpdater(updater, columnFilterState);
+      onFilterModelChange(columnFiltersToFilterModel(next));
+      resetPaginationPage();
+    },
+    onGlobalFilterChange: (updater) => {
+      const next = applyUpdater(updater, quickFilter);
+      setQuickFilter(typeof next === 'string' ? next : '');
+    },
+    onRowSelectionChange: (updater) => {
+      const next = applyUpdater(updater, rowSelectionState);
+      onRowSelectionModelChange(rowSelectionToModel(next, rowSelectionModel, allIds));
+    },
+  });
+
+  return { table, setQuickFilter, setColumnFilter };
+}