@cdx-ui/data-grid 0.3.12 → 0.3.13

package/src/DataGridFilterPanel.tsx

@@ -1,6 +1,12 @@
-import { useRef, type RefObject } from 'react';
-import { View } from 'react-native';
-import { useDismissOverlay, useEscapeKey } from '@cdx-ui/primitives';
+import { useCallback, useEffect, useRef, useState, type RefObject } from 'react';
+import { Platform, View } from 'react-native';
+import {
+  OverlayContainer,
+  useAnchoredOverlay,
+  useDismissOverlay,
+  useEscapeKey,
+} from '@cdx-ui/primitives';
+import { mergeRefs } from '@cdx-ui/utils';
 import {
   Button,
   DateField,
@@ -19,6 +25,7 @@ import {
   getFilterOperatorLabel,
   getGridFilterOperators,
   headerFilterValueFromText,
+  isActiveFilterItem,
 } from './adapter/filterOperators';
 import {
   dataGridFilterPanelColumnVariants,
@@ -171,6 +178,108 @@ export function createDefaultFilterItem<R extends GridValidRowModel>(
   return { field: col.field, operator: getDefaultFilterOperator(col.type) };
 }
 
+function createFilterItemForField<R extends GridValidRowModel>(
+  columns: readonly GridColDef<R>[],
+  field: string | undefined,
+): GridFilterItem | undefined {
+  const col =
+    field === undefined ? undefined : columns.find((candidate) => candidate.field === field);
+  return col && col.filterable !== false
+    ? { field: col.field, operator: getDefaultFilterOperator(col.type) }
+    : undefined;
+}
+
+const FOCUSABLE_SELECTOR = 'input, textarea, button, [tabindex]:not([tabindex="-1"])';
+
+function focusFirstControl(container: View | null): boolean {
+  const element = container as unknown as HTMLElement | null;
+  const control = element?.querySelector<HTMLElement>(FOCUSABLE_SELECTOR);
+  if (!control) {
+    return false;
+  }
+  control.focus();
+  return true;
+}
+
+function focusOpener(ref: RefObject<View | null>) {
+  const element = ref.current as unknown as HTMLElement | null;
+  if (Platform.OS === 'web' && typeof element?.focus === 'function') {
+    element.focus();
+  }
+}
+
+/** The control that opened the panel and, for a column opener, the field it targets. */
+export interface DataGridFilterPanelOpener {
+  ref: RefObject<View | null>;
+  field?: string;
+  /** Changes on every open-for-field call, so a repeat call moves focus again. */
+  request?: number;
+}
+
+export interface UseDataGridFilterPanelParams<R extends GridValidRowModel> {
+  /** The panel's columns. A field that is missing or has `filterable: false` does not open it. */
+  columns: readonly GridColDef<R>[];
+  filterModel: GridFilterModel;
+  /** Receives the appended item. It filters nothing, so callers should not reset the page. */
+  onFilterModelChange: (model: GridFilterModel) => void;
+}
+
+export interface UseDataGridFilterPanelResult {
+  opener: DataGridFilterPanelOpener | null;
+  /** Opens the panel on `field`, or retargets it when already open. Header filter cells and the
+   * column menu call this; the column menu passes its trigger, since the menu item unmounts. */
+  openForField: (field: string, ref: RefObject<View | null>) => void;
+  /** The toolbar button: opens the panel on the model as it is, or closes it. */
+  toggle: (ref: RefObject<View | null>) => void;
+  close: (options: { restoreFocus: boolean }) => void;
+}
+
+/**
+ * Open state for the filter panel. Opening for a field shows the field's first item, even a
+ * value-less one, and leaves the model alone. When the field has none, it appends
+ * `{ field, operator }` and drops value-less items on other fields, as the append branch of MUI X
+ * `showFilterPanel(field)` does. MUI also rewrites the model when the field has an item.
+ */
+export function useDataGridFilterPanel<R extends GridValidRowModel>({
+  columns,
+  filterModel,
+  onFilterModelChange,
+}: UseDataGridFilterPanelParams<R>): UseDataGridFilterPanelResult {
+  const [opener, setOpener] = useState<DataGridFilterPanelOpener | null>(null);
+  const requestRef = useRef(0);
+
+  const openForField = useCallback(
+    (field: string, ref: RefObject<View | null>) => {
+      const item = createFilterItemForField(columns, field);
+      if (!item) {
+        return;
+      }
+      if (!filterModel.some((candidate) => candidate.field === field)) {
+        onFilterModelChange([...filterModel.filter(isActiveFilterItem), item]);
+      }
+      requestRef.current += 1;
+      setOpener({ ref, field, request: requestRef.current });
+    },
+    [columns, filterModel, onFilterModelChange],
+  );
+
+  const toggle = useCallback((ref: RefObject<View | null>) => {
+    setOpener((current) => (current?.ref === ref ? null : { ref }));
+  }, []);
+
+  const close = useCallback(
+    ({ restoreFocus }: { restoreFocus: boolean }) => {
+      if (opener && restoreFocus) {
+        focusOpener(opener.ref);
+      }
+      setOpener(null);
+    },
+    [opener],
+  );
+
+  return { opener, openForField, toggle, close };
+}
+
 function resolveItemOperator<R extends GridValidRowModel>(
   col: GridColDef<R> | undefined,
   item: GridFilterItem,
@@ -199,6 +308,8 @@ function itemWithValueText<R extends GridValidRowModel>(
 
 function FilterPanelRow<R extends GridValidRowModel>({
   index,
+  operatorFieldRef,
+  valueFieldRef,
   item,
   columns,
   logicOperator,
@@ -207,6 +318,8 @@ function FilterPanelRow<R extends GridValidRowModel>({
   onRemove,
 }: {
   index: number;
+  operatorFieldRef?: RefObject<View | null>;
+  valueFieldRef?: RefObject<View | null>;
   item: GridFilterItem;
   columns: readonly GridColDef<R>[];
   logicOperator: GridLogicOperator;
@@ -293,7 +406,10 @@ function FilterPanelRow<R extends GridValidRowModel>({
           </Select.Content>
         </Select>
       </View>
-      <View className={dataGridFilterPanelFieldVariants({ size: 'operator' })}>
+      <View
+        ref={operatorFieldRef}
+        className={dataGridFilterPanelFieldVariants({ size: 'operator' })}
+      >
         <Text className="text-xs text-content-secondary">Operator</Text>
         <Select
           items={operators.map((candidate) => ({
@@ -332,7 +448,7 @@ function FilterPanelRow<R extends GridValidRowModel>({
           </Select.Content>
         </Select>
       </View>
-      <View className={dataGridFilterPanelFieldVariants({ size: 'value' })}>
+      <View ref={valueFieldRef} className={dataGridFilterPanelFieldVariants({ size: 'value' })}>
         {filterOperatorNeedsValue(operator) ? (
           <>
             <Text className="text-xs text-content-secondary">Value</Text>
@@ -393,9 +509,10 @@ export interface DataGridFilterPanelProps<R extends GridValidRowModel> {
   onFilterModelChange: (model: GridFilterModel) => void;
   logicOperator: GridLogicOperator;
   onLogicOperatorChange: (operator: GridLogicOperator) => void;
-  onClose: () => void;
-  /** The control that toggles the panel; presses on it are not treated as outside presses. */
-  triggerRef?: RefObject<View | null>;
+  /** `restoreFocus` is false for an outside press, which leaves focus where the user pressed. */
+  onClose: (options: { restoreFocus: boolean }) => void;
+  /** Presses on the opener are not outside presses. A column opener also anchors the panel. */
+  opener: DataGridFilterPanelOpener;
 }
 
 export function DataGridFilterPanel<R extends GridValidRowModel>({
@@ -405,14 +522,58 @@ export function DataGridFilterPanel<R extends GridValidRowModel>({
   logicOperator,
   onLogicOperatorChange,
   onClose,
-  triggerRef,
+  opener,
 }: DataGridFilterPanelProps<R>) {
+  const anchored = opener.field !== undefined;
   const panelRef = useRef<View>(null);
-  useDismissOverlay(true, panelRef, triggerRef ? [triggerRef] : [], onClose);
-  useEscapeKey(true, onClose);
+  const operatorFieldRef = useRef<View>(null);
+  const valueFieldRef = useRef<View>(null);
+  const focusedRequestRef = useRef<number | undefined>(undefined);
+  const {
+    floatingRef,
+    onFloatingLayout,
+    style: anchoredStyle,
+    position,
+  } = useAnchoredOverlay(opener.ref, anchored, {
+    placement: 'bottom-start',
+    collisionBehavior: 'flip-shift',
+    width: 'content',
+  });
+  const dismiss = () => onClose({ restoreFocus: false });
+  const closeAndRestoreFocus = () => onClose({ restoreFocus: true });
+  useDismissOverlay(true, panelRef, [opener.ref], dismiss);
+  useEscapeKey(true, closeAndRestoreFocus);
 
   const defaultItem = createDefaultFilterItem(columns);
-  const items = filterModel.length > 0 ? filterModel : defaultItem ? [defaultItem] : [];
+  const placeholderItem = createFilterItemForField(columns, opener.field) ?? defaultItem;
+  const items = filterModel.length > 0 ? filterModel : placeholderItem ? [placeholderItem] : [];
+  const targetIndex =
+    opener.field === undefined ? -1 : items.findIndex((item) => item.field === opener.field);
+  const targetItem = targetIndex >= 0 ? items[targetIndex] : undefined;
+  const targetNeedsValue =
+    targetItem !== undefined &&
+    filterOperatorNeedsValue(
+      resolveItemOperator(
+        columns.find((candidate) => candidate.field === targetItem.field),
+        targetItem,
+      ),
+    );
+
+  // Rows are keyed by index, so an appended target row can mount a render after the open request.
+  // Retry on each commit until the target control exists, then stop for that request.
+  useEffect(() => {
+    if (
+      Platform.OS !== 'web' ||
+      opener.request === undefined ||
+      focusedRequestRef.current === opener.request ||
+      targetItem === undefined
+    ) {
+      return;
+    }
+    if (focusFirstControl((targetNeedsValue ? valueFieldRef : operatorFieldRef).current)) {
+      focusedRequestRef.current = opener.request;
+    }
+  });
 
   const replaceItem = (index: number, next: GridFilterItem) => {
     onFilterModelChange(items.map((item, itemIndex) => (itemIndex === index ? next : item)));
@@ -421,14 +582,20 @@ export function DataGridFilterPanel<R extends GridValidRowModel>({
     const next = items.filter((_, itemIndex) => itemIndex !== index);
     onFilterModelChange(next);
     if (next.length === 0) {
-      onClose();
+      closeAndRestoreFocus();
     }
   };
 
-  return (
+  const panel = (
     <View
-      ref={panelRef}
-      className={dataGridFilterPanelVariants()}
+      ref={anchored ? mergeRefs(panelRef, floatingRef) : panelRef}
+      className={dataGridFilterPanelVariants({ anchored })}
+      style={
+        anchored
+          ? [anchoredStyle, position ? { maxWidth: position.availableWidth } : undefined]
+          : undefined
+      }
+      onLayout={anchored ? onFloatingLayout : undefined}
       accessibilityLabel="Filters"
       testID="data-grid-filter-panel"
     >
@@ -436,6 +603,8 @@ export function DataGridFilterPanel<R extends GridValidRowModel>({
         <FilterPanelRow
           key={index}
           index={index}
+          operatorFieldRef={index === targetIndex ? operatorFieldRef : undefined}
+          valueFieldRef={index === targetIndex ? valueFieldRef : undefined}
           item={item}
           columns={columns}
           logicOperator={logicOperator}
@@ -465,7 +634,7 @@ export function DataGridFilterPanel<R extends GridValidRowModel>({
           size="small"
           onPress={() => {
             onFilterModelChange([]);
-            onClose();
+            closeAndRestoreFocus();
           }}
         >
           <Button.Icon as={Delete} />
@@ -474,4 +643,6 @@ export function DataGridFilterPanel<R extends GridValidRowModel>({
       </View>
     </View>
   );
+
+  return anchored ? <OverlayContainer onDismiss={dismiss}>{panel}</OverlayContainer> : panel;
 }

package/src/adapter/columns.ts

@@ -1,6 +1,7 @@
 import type { TableAlignment } from '@cdx-ui/components';
 import type { ColumnPinningState } from '@tanstack/react-table';
 import {
+  DETAIL_PANEL_TOGGLE_ID,
   MUI_CHECKBOX_FIELD,
   SELECT_COLUMN_ID,
   type GridAlignment,
@@ -116,6 +117,7 @@ export function normalizePinnedColumns(
   pinnedColumns: GridPinnedColumnFields | undefined,
   knownFields: ReadonlySet<string>,
   checkboxSelection: boolean,
+  detailPanel = false,
 ): ColumnPinningState {
   if (pinnedColumns == null) {
     return { start: [], end: [] };
@@ -134,8 +136,7 @@ export function normalizePinnedColumns(
       if (seen.has(field)) {
         continue;
       }
-      const isSelect = field === SELECT_COLUMN_ID;
-      if (isSelect ? !checkboxSelection : !knownFields.has(field)) {
+      if (!isKnownPinField(field)) {
         warnUnknownPinnedField(raw);
         continue;
       }
@@ -144,6 +145,16 @@ export function normalizePinnedColumns(
     }
   };
 
+  const isKnownPinField = (field: string) => {
+    if (field === SELECT_COLUMN_ID) {
+      return checkboxSelection;
+    }
+    if (field === DETAIL_PANEL_TOGGLE_ID) {
+      return detailPanel;
+    }
+    return knownFields.has(field);
+  };
+
   const startSeen = new Set<string>();
   const start: string[] = [];
   appendUnique(start, startSeen, pinnedColumns.start);
@@ -166,8 +177,7 @@ export function normalizePinnedColumns(
       if (endSeen.has(field)) {
         continue;
       }
-      const isSelect = field === SELECT_COLUMN_ID;
-      if (isSelect ? !checkboxSelection : !knownFields.has(field)) {
+      if (!isKnownPinField(field)) {
         warnUnknownPinnedField(raw);
         continue;
       }
@@ -179,10 +189,14 @@ export function normalizePinnedColumns(
   // eslint-disable-next-line @typescript-eslint/no-deprecated -- alias merge
   appendEnd(pinnedColumns.right);
 
-  if (checkboxSelection && start.length > 0) {
-    const withoutSelect = start.filter((field) => field !== SELECT_COLUMN_ID);
+  if (start.length > 0) {
+    const leading = [
+      ...(checkboxSelection ? [SELECT_COLUMN_ID] : []),
+      ...(detailPanel ? [DETAIL_PANEL_TOGGLE_ID] : []),
+    ];
+    const rest = start.filter((field) => !leading.includes(field));
     start.length = 0;
-    start.push(SELECT_COLUMN_ID, ...withoutSelect);
+    start.push(...leading, ...rest);
   }
 
   return { start, end };

package/src/adapter/pinning.ts

@@ -1,9 +1,15 @@
 import type { ViewStyle } from 'react-native';
 import type { ColumnPinningState } from '@tanstack/react-table';
-import { SELECT_COLUMN_ID, type GridColDef, type GridValidRowModel } from '../types';
+import {
+  DETAIL_PANEL_TOGGLE_ID,
+  SELECT_COLUMN_ID,
+  type GridColDef,
+  type GridValidRowModel,
+} from '../types';
 
 export const DEFAULT_PINNED_COLUMN_WIDTH = 100;
 export const SELECT_COLUMN_WIDTH = 56;
+export const DETAIL_PANEL_TOGGLE_WIDTH = 48;
 
 export type ColumnPinEdge = 'start' | 'end';
 
@@ -22,6 +28,9 @@ export function pinnedColumnPixelWidth<R extends GridValidRowModel>(
   if (columnId === SELECT_COLUMN_ID) {
     return SELECT_COLUMN_WIDTH;
   }
+  if (columnId === DETAIL_PANEL_TOGGLE_ID) {
+    return DETAIL_PANEL_TOGGLE_WIDTH;
+  }
   return Math.max(col?.width ?? DEFAULT_PINNED_COLUMN_WIDTH, col?.minWidth ?? 0);
 }
 

package/src/adapter/selectColumn.ts

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

package/src/adapter/treeData.ts

@@ -0,0 +1,228 @@
+export interface GridTreeIndex<R> {
+  roots: R[];
+  childrenOf: Map<R, R[]>;
+  rowOf: Map<string, R>;
+  parentKeyOf: Map<string, string>;
+  childKeysOf: Map<string, string[]>;
+  depthOf: Map<string, number>;
+  /** Deepest rows first, so a parent is visited after all of its descendants. */
+  keysDeepestFirst: string[];
+}
+
+export type GridTreeSelectionStatus = 'all' | 'some' | 'none';
+
+/** The shape TanStack rows share; filtered and sorted rows carry their filtered `subRows`. */
+export interface GridTreeRowLike {
+  id: string;
+  subRows: readonly GridTreeRowLike[];
+}
+
+const pathKey = (path: readonly string[]) => JSON.stringify(path);
+
+const warnedDuplicatePaths = new Set<string>();
+
+export function buildTreeIndex<R>(
+  rows: readonly R[],
+  getTreeDataPath: (row: R) => readonly string[],
+  keyOf: (row: R) => string,
+): GridTreeIndex<R> {
+  const byPath = new Map<string, R>();
+  const paths = new Map<R, readonly string[]>();
+  for (const row of rows) {
+    const path = getTreeDataPath(row);
+    const key = pathKey(path);
+    if (__DEV__ && byPath.has(key) && !warnedDuplicatePaths.has(key)) {
+      warnedDuplicatePaths.add(key);
+      console.warn(`[DataGrid] Duplicate tree data path ${key}. Paths must be unique.`);
+    }
+    byPath.set(key, row);
+    paths.set(row, path);
+  }
+
+  const roots: R[] = [];
+  const childrenOf = new Map<R, R[]>();
+  const rowOf = new Map<string, R>();
+  const parentKeyOf = new Map<string, string>();
+  const childKeysOf = new Map<string, string[]>();
+
+  for (const row of rows) {
+    const path = paths.get(row) ?? [];
+    const key = keyOf(row);
+    rowOf.set(key, row);
+    let parent: R | undefined;
+    for (let length = path.length - 1; length > 0 && parent === undefined; length -= 1) {
+      parent = byPath.get(pathKey(path.slice(0, length)));
+    }
+    if (parent === undefined || parent === row) {
+      roots.push(row);
+      continue;
+    }
+    const parentKey = keyOf(parent);
+    parentKeyOf.set(key, parentKey);
+    const siblings = childrenOf.get(parent);
+    if (siblings) {
+      siblings.push(row);
+    } else {
+      childrenOf.set(parent, [row]);
+    }
+    const siblingKeys = childKeysOf.get(parentKey);
+    if (siblingKeys) {
+      siblingKeys.push(key);
+    } else {
+      childKeysOf.set(parentKey, [key]);
+    }
+  }
+
+  const depthOf = new Map<string, number>();
+  const breadthFirst = roots.map((row) => keyOf(row));
+  for (const key of breadthFirst) {
+    depthOf.set(key, 0);
+  }
+  // The array iterator also visits children pushed during the loop.
+  for (const key of breadthFirst) {
+    for (const child of childKeysOf.get(key) ?? []) {
+      depthOf.set(child, (depthOf.get(key) ?? 0) + 1);
+      breadthFirst.push(child);
+    }
+  }
+
+  return {
+    roots,
+    childrenOf,
+    rowOf,
+    parentKeyOf,
+    childKeysOf,
+    depthOf,
+    keysDeepestFirst: breadthFirst.reverse(),
+  };
+}
+
+/**
+ * With `propagateParents`, a parent is `all` exactly when every child is `all`, whatever the model
+ * says about the parent itself. Without it, a parent's own selection decides, and partly selected
+ * descendants show as `some`.
+ */
+export function computeTreeSelection<R>(
+  index: GridTreeIndex<R>,
+  selected: ReadonlySet<string>,
+  propagateParents: boolean,
+): Map<string, GridTreeSelectionStatus> {
+  const status = new Map<string, GridTreeSelectionStatus>();
+  for (const key of index.keysDeepestFirst) {
+    const isSelected = selected.has(key);
+    const children = index.childKeysOf.get(key);
+    if (!children?.length) {
+      status.set(key, isSelected ? 'all' : 'none');
+      continue;
+    }
+    let all = true;
+    let some = false;
+    for (const child of children) {
+      const childStatus = status.get(child) ?? 'none';
+      if (childStatus !== 'all') {
+        all = false;
+      }
+      if (childStatus !== 'none') {
+        some = true;
+      }
+    }
+    if (propagateParents) {
+      status.set(key, all ? 'all' : some || isSelected ? 'some' : 'none');
+    } else {
+      status.set(key, isSelected ? 'all' : some ? 'some' : 'none');
+    }
+  }
+  return status;
+}
+
+export function applyTreeSelection<R>(
+  index: GridTreeIndex<R>,
+  selected: ReadonlySet<string>,
+  targets: readonly string[],
+  value: boolean,
+  propagateParents: boolean,
+): Set<string> {
+  const next = new Set(selected);
+  for (const key of targets) {
+    if (value) {
+      next.add(key);
+    } else {
+      next.delete(key);
+    }
+  }
+  if (propagateParents) {
+    for (const key of index.keysDeepestFirst) {
+      const children = index.childKeysOf.get(key);
+      if (!children?.length) {
+        continue;
+      }
+      if (children.every((child) => next.has(child))) {
+        next.add(key);
+      } else {
+        next.delete(key);
+      }
+    }
+  }
+  return next;
+}
+
+/**
+ * Rows a toggle writes (`targets`) and the rows whose state decides the toggle direction
+ * (`units`). With `descendants`, a row's filtered sub-rows are included; a row whose children were
+ * all filtered out takes its whole subtree, so a matching group can still be picked.
+ */
+export function selectionScope<R>(
+  rows: readonly GridTreeRowLike[],
+  index: GridTreeIndex<R>,
+  descendants: boolean,
+): { targets: string[]; units: string[] } {
+  const targets: string[] = [];
+  const units: string[] = [];
+  const visitFullSubtree = (key: string) => {
+    targets.push(key);
+    const children = index.childKeysOf.get(key);
+    if (!children?.length) {
+      units.push(key);
+      return;
+    }
+    children.forEach(visitFullSubtree);
+  };
+  const visit = (row: GridTreeRowLike) => {
+    if (!descendants) {
+      targets.push(row.id);
+      units.push(row.id);
+      return;
+    }
+    if (row.subRows.length === 0) {
+      visitFullSubtree(row.id);
+      return;
+    }
+    targets.push(row.id);
+    row.subRows.forEach(visit);
+  };
+  rows.forEach(visit);
+  return { targets, units };
+}
+
+/** Keeps every row that matches and every ancestor of a match. */
+export function keepMatchesWithAncestors<R>(
+  rows: readonly R[],
+  index: GridTreeIndex<R>,
+  keyOf: (row: R) => string,
+  matches: (row: R) => boolean,
+): R[] {
+  const keep = new Set<string>();
+  for (const row of rows) {
+    if (!matches(row)) {
+      continue;
+    }
+    for (let key: string | undefined = keyOf(row); key !== undefined; ) {
+      if (keep.has(key)) {
+        break;
+      }
+      keep.add(key);
+      key = index.parentKeyOf.get(key);
+    }
+  }
+  return rows.filter((row) => keep.has(keyOf(row)));
+}

package/src/index.ts

@@ -13,6 +13,7 @@ export type {
   GridBaseColDef,
   GridColDef,
   GridColType,
+  GridColumnVisibilityModel,
   GridFeatureMode,
   GridFilterItem,
   GridFilterModel,
@@ -22,12 +23,15 @@ export type {
   GridPinnedColumnFields,
   GridRenderCellParams,
   GridRowId,
+  GridRowParams,
   GridRowSelectionModel,
+  GridRowSelectionPropagation,
   GridRowsProp,
   GridSingleSelectColDef,
   GridSortDirection,
   GridSortItem,
   GridSortModel,
+  GridTreeNodeParams,
   GridValidRowModel,
   GridValueOption,
 } from './types';