@cdx-ui/data-grid 0.3.10 → 0.3.12

package/src/numberCells.tsx

@@ -0,0 +1,379 @@
+import type { ReactNode } from 'react';
+import { View } from 'react-native';
+import { Text } from '@cdx-ui/components';
+import {
+  ArrowDropDown,
+  ArrowDropUp,
+  TrendingDown,
+  TrendingFlat,
+  TrendingUp,
+  type ForgeIcon,
+} from '@cdx-ui/icons';
+import { cn } from '@cdx-ui/utils';
+import type { GridBaseColDef, GridColDef, GridValidRowModel } from './types';
+
+/** Unicode minus (U+2212). The spec requires this character, not a hyphen. */
+const MINUS = '\u2212';
+
+const defaultNumberFormat = new Intl.NumberFormat(undefined, { maximumFractionDigits: 20 });
+
+export type GridNumberCellDensity = 'default' | 'compact';
+
+export type GridDeltaNumberSymbol = 'arrow' | 'trendline' | 'sign';
+
+export interface GridPolarityNumberColDefOptions {
+  /**
+   * `default` uses body-md. `compact` uses body-sm.
+   * @default 'default'
+   */
+  density?: GridNumberCellDensity;
+  /**
+   * Formats the raw signed number. The cell turns a leading hyphen into −.
+   * Sorting uses the raw number. The header filter matches the number column's
+   * formatted value, not this string.
+   */
+  valueFormatter?: (value: number) => string;
+}
+
+export interface GridDeltaNumberColDefOptions {
+  /**
+   * Whether an increase is a favorable change. Color follows this together with
+   * the value's direction: an increase is success when this is true and danger
+   * when it is false; a decrease flips that. Zero stays primary either way.
+   * @default true
+   */
+  increaseIsGood?: boolean;
+  /**
+   * `arrow` uses drop arrows and leaves flat values blank. `trendline` uses
+   * trending icons, including a flat icon at zero. `sign` writes + or − in
+   * front of the value. Arrow and trendline hide the minus sign.
+   * @default 'arrow'
+   */
+  symbol?: GridDeltaNumberSymbol;
+  /**
+   * `default` uses body-md. `compact` uses body-sm.
+   * @default 'default'
+   */
+  density?: GridNumberCellDensity;
+  /**
+   * Formats the raw signed number. The cell applies the symbol's sign treatment
+   * on top of this string. Sorting uses the raw number. The header filter matches
+   * the number column's formatted value, not this string.
+   */
+  valueFormatter?: (value: number) => string;
+}
+
+type NumberTone = 'success' | 'danger' | 'neutral';
+type DeltaDirection = 'increase' | 'decrease' | 'flat';
+
+const TONE_CLASS: Record<NumberTone, string> = {
+  success: 'text-content-success',
+  danger: 'text-content-danger',
+  neutral: 'text-content-primary',
+};
+
+const ARROW_SLOT: Record<GridNumberCellDensity, string> = {
+  default: 'h-5 w-3.5 items-center justify-center overflow-hidden',
+  compact: 'h-4 w-3 items-center justify-center overflow-hidden',
+};
+
+const ARROW_SIZE: Record<GridNumberCellDensity, number> = {
+  default: 20,
+  compact: 16,
+};
+
+const TREND_SIZE: Record<GridNumberCellDensity, number> = {
+  default: 14,
+  compact: 12,
+};
+
+function toFiniteNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function columnValueFormatter<R extends GridValidRowModel>(
+  format: ((value: number) => string) | undefined,
+): GridColDef<R>['valueFormatter'] {
+  if (!format) {
+    return undefined;
+  }
+  return (value) => {
+    const numeric = toFiniteNumber(value);
+    return numeric == null ? '' : format(numeric);
+  };
+}
+
+function formatRaw<R extends GridValidRowModel>(value: number, row: R, col: GridColDef<R>): string {
+  const formatted = col.valueFormatter?.(value, row, col);
+  if (typeof formatted === 'string' && formatted.length > 0) {
+    return formatted;
+  }
+  return defaultNumberFormat.format(value);
+}
+
+function unsigned(formatted: string): string {
+  const withoutSign = formatted.replace(/^[-−+]\s*/, '');
+  if (withoutSign.startsWith('(') && withoutSign.endsWith(')')) {
+    return withoutSign.slice(1, -1);
+  }
+  return withoutSign;
+}
+
+function polarityOf(value: number): 'positive' | 'negative' | 'neutral' {
+  if (value > 0) {
+    return 'positive';
+  }
+  if (value < 0) {
+    return 'negative';
+  }
+  return 'neutral';
+}
+
+function directionOf(value: number): DeltaDirection {
+  if (value > 0) {
+    return 'increase';
+  }
+  if (value < 0) {
+    return 'decrease';
+  }
+  return 'flat';
+}
+
+function polarityTone(polarity: 'positive' | 'negative' | 'neutral'): NumberTone {
+  if (polarity === 'positive') {
+    return 'success';
+  }
+  if (polarity === 'negative') {
+    return 'danger';
+  }
+  return 'neutral';
+}
+
+function deltaTone(direction: DeltaDirection, increaseIsGood: boolean): NumberTone {
+  if (direction === 'flat') {
+    return 'neutral';
+  }
+  const favorable = direction === 'increase' ? increaseIsGood : !increaseIsGood;
+  return favorable ? 'success' : 'danger';
+}
+
+function polarityLabel(polarity: 'positive' | 'negative' | 'neutral'): string {
+  if (polarity === 'positive') {
+    return 'Positive';
+  }
+  if (polarity === 'negative') {
+    return 'Negative';
+  }
+  return 'Neutral';
+}
+
+function directionLabel(direction: DeltaDirection): string {
+  if (direction === 'increase') {
+    return 'Increase';
+  }
+  if (direction === 'decrease') {
+    return 'Decrease';
+  }
+  return 'No change';
+}
+
+function NumberReadout({
+  label,
+  display,
+  tone,
+  density,
+  children,
+}: {
+  label: string;
+  display: string;
+  tone: NumberTone;
+  density: GridNumberCellDensity;
+  children?: ReactNode;
+}) {
+  return (
+    <View className="relative flex-row items-center gap-0.5">
+      <Text className="absolute h-px w-px overflow-hidden opacity-0">{label}</Text>
+      <View
+        aria-hidden
+        accessibilityElementsHidden
+        importantForAccessibility="no-hide-descendants"
+        className="flex-row items-center gap-0.5"
+      >
+        {children}
+        <Text
+          color={tone === 'neutral' ? 'primary' : tone}
+          size={density === 'compact' ? 'sm' : 'md'}
+        >
+          {display}
+        </Text>
+      </View>
+    </View>
+  );
+}
+
+function ToneIcon({
+  icon: Icon,
+  tone,
+  size,
+  slotClassName,
+}: {
+  icon: ForgeIcon;
+  tone: NumberTone;
+  size: number;
+  slotClassName?: string;
+}) {
+  return (
+    <View className={cn(TONE_CLASS[tone], slotClassName)}>
+      <Icon size={size} />
+    </View>
+  );
+}
+
+function PolarityNumberCell<R extends GridValidRowModel>({
+  value,
+  row,
+  col,
+  density,
+}: {
+  value: unknown;
+  row: R;
+  col: GridColDef<R>;
+  density: GridNumberCellDensity;
+}) {
+  const numeric = toFiniteNumber(value);
+  if (numeric == null) {
+    return null;
+  }
+
+  const polarity = polarityOf(numeric);
+  const magnitude = unsigned(formatRaw(numeric, row, col));
+  const display = polarity === 'negative' ? `${MINUS}${magnitude}` : magnitude;
+
+  return (
+    <NumberReadout
+      label={`${polarityLabel(polarity)} ${magnitude}`}
+      display={display}
+      tone={polarityTone(polarity)}
+      density={density}
+    />
+  );
+}
+
+function DeltaSymbol({
+  direction,
+  tone,
+  density,
+  symbol,
+}: {
+  direction: DeltaDirection;
+  tone: NumberTone;
+  density: GridNumberCellDensity;
+  symbol: GridDeltaNumberSymbol;
+}) {
+  if (symbol === 'sign') {
+    return null;
+  }
+
+  if (symbol === 'arrow') {
+    if (direction === 'flat') {
+      return <View className={ARROW_SLOT[density]} />;
+    }
+    return (
+      <ToneIcon
+        icon={direction === 'increase' ? ArrowDropUp : ArrowDropDown}
+        tone={tone}
+        size={ARROW_SIZE[density]}
+        slotClassName={ARROW_SLOT[density]}
+      />
+    );
+  }
+
+  const icon =
+    direction === 'increase' ? TrendingUp : direction === 'decrease' ? TrendingDown : TrendingFlat;
+  return <ToneIcon icon={icon} tone={tone} size={TREND_SIZE[density]} />;
+}
+
+function DeltaNumberCell<R extends GridValidRowModel>({
+  value,
+  row,
+  col,
+  density,
+  increaseIsGood,
+  symbol,
+}: {
+  value: unknown;
+  row: R;
+  col: GridColDef<R>;
+  density: GridNumberCellDensity;
+  increaseIsGood: boolean;
+  symbol: GridDeltaNumberSymbol;
+}) {
+  const numeric = toFiniteNumber(value);
+  if (numeric == null) {
+    return null;
+  }
+
+  const direction = directionOf(numeric);
+  const tone = deltaTone(direction, increaseIsGood);
+  const magnitude = unsigned(formatRaw(numeric, row, col));
+  let display = magnitude;
+  if (symbol === 'sign' && direction === 'increase') {
+    display = `+${magnitude}`;
+  } else if (symbol === 'sign' && direction === 'decrease') {
+    display = `${MINUS}${magnitude}`;
+  }
+
+  return (
+    <NumberReadout
+      label={`${directionLabel(direction)} ${magnitude}`}
+      display={display}
+      tone={tone}
+      density={density}
+    >
+      <DeltaSymbol direction={direction} tone={tone} density={density} symbol={symbol} />
+    </NumberReadout>
+  );
+}
+
+export function gridPolarityNumberColDef<R extends GridValidRowModel>(
+  options: GridPolarityNumberColDefOptions = {},
+): Pick<GridBaseColDef<R>, 'type' | 'align' | 'headerAlign' | 'renderCell' | 'valueFormatter'> {
+  const density = options.density ?? 'default';
+  return {
+    type: 'number',
+    align: 'end',
+    headerAlign: 'end',
+    ...(options.valueFormatter
+      ? { valueFormatter: columnValueFormatter<R>(options.valueFormatter) }
+      : {}),
+    renderCell: ({ value, row, col }) => (
+      <PolarityNumberCell value={value} row={row} col={col} density={density} />
+    ),
+  };
+}
+
+export function gridDeltaNumberColDef<R extends GridValidRowModel>(
+  options: GridDeltaNumberColDefOptions = {},
+): Pick<GridBaseColDef<R>, 'type' | 'align' | 'headerAlign' | 'renderCell' | 'valueFormatter'> {
+  const density = options.density ?? 'default';
+  const increaseIsGood = options.increaseIsGood ?? true;
+  const symbol = options.symbol ?? 'arrow';
+  return {
+    type: 'number',
+    align: 'end',
+    headerAlign: 'end',
+    ...(options.valueFormatter
+      ? { valueFormatter: columnValueFormatter<R>(options.valueFormatter) }
+      : {}),
+    renderCell: ({ value, row, col }) => (
+      <DeltaNumberCell
+        value={value}
+        row={row}
+        col={col}
+        density={density}
+        increaseIsGood={increaseIsGood}
+        symbol={symbol}
+      />
+    ),
+  };
+}

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,36 @@ export const dataGridBodyVariants = cva(
 
 export const dataGridFilterInputVariants = cva('min-w-24');
 
+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',
+);
+
+// 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({

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,24 +123,45 @@ 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;
@@ -114,13 +206,25 @@ 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;
   headerFilters?: boolean;
   /** Replaces the default centered "No rows" message. Shown when `rows` is empty and not loading. */
   noRowsOverlay?: ReactNode;
@@ -135,6 +239,9 @@ export interface DataGridProps<R extends GridValidRowModel = GridValidRowModel>
 
 export const SELECT_COLUMN_ID = '__select__';
 
+/** 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 = {