@cdx-ui/data-grid 0.3.11 → 0.3.13

package/src/DataGridFilterPanel.tsx

@@ -0,0 +1,648 @@
+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,
+  DatePicker,
+  IconButton,
+  Input,
+  Select,
+  Text,
+  type DatePickerProps,
+} from '@cdx-ui/components';
+import { Add, Close, Delete } from '@cdx-ui/icons';
+import {
+  filterOperatorNeedsValue,
+  filterValueToInputText,
+  getDefaultFilterOperator,
+  getFilterOperatorLabel,
+  getGridFilterOperators,
+  headerFilterValueFromText,
+  isActiveFilterItem,
+} from './adapter/filterOperators';
+import {
+  dataGridFilterPanelColumnVariants,
+  dataGridFilterPanelFieldVariants,
+  dataGridFilterPanelFooterVariants,
+  dataGridFilterPanelLogicVariants,
+  dataGridFilterPanelOperatorVariants,
+  dataGridFilterPanelRowVariants,
+  dataGridFilterPanelValueVariants,
+  dataGridFilterPanelVariants,
+} from './styles';
+import type {
+  GridColDef,
+  GridFilterItem,
+  GridFilterModel,
+  GridFilterOperator,
+  GridLogicOperator,
+  GridValidRowModel,
+} from './types';
+
+const LOGIC_OPERATORS: readonly { value: GridLogicOperator; label: string }[] = [
+  { value: 'and', label: 'And' },
+  { value: 'or', label: 'Or' },
+];
+
+const BOOLEAN_FILTER_VALUES: readonly { value: 'any' | 'true' | 'false'; label: string }[] = [
+  { value: 'any', label: 'any' },
+  { value: 'true', label: 'true' },
+  { value: 'false', label: 'false' },
+];
+
+function booleanSelectValue(value: unknown): 'any' | 'true' | 'false' {
+  if (value === true || value === 'true') {
+    return 'true';
+  }
+  if (value === false || value === 'false') {
+    return 'false';
+  }
+  return 'any';
+}
+
+function booleanFilterItem(
+  field: string,
+  operator: GridFilterOperator,
+  next: string,
+): GridFilterItem {
+  if (next === 'true') {
+    return { field, operator, value: true };
+  }
+  if (next === 'false') {
+    return { field, operator, value: false };
+  }
+  return { field, operator };
+}
+
+function logicOperatorLabel(operator: GridLogicOperator): string {
+  return operator === 'or' ? 'Or' : 'And';
+}
+
+export function filterPlaceholder<R extends GridValidRowModel>(
+  col: GridColDef<R> | undefined,
+  operator: GridFilterOperator,
+): string {
+  if (operator === 'isAnyOf') {
+    return 'a, b';
+  }
+  switch (col?.type) {
+    case 'number':
+      return '0';
+    case 'date':
+    case 'dateTime':
+      return 'YYYY-MM-DD';
+    case 'boolean':
+      return 'true';
+    default:
+      return 'Filter value';
+  }
+}
+
+function isDateColumn<R extends GridValidRowModel>(col: GridColDef<R> | undefined): boolean {
+  return col?.type === 'date' || col?.type === 'dateTime';
+}
+
+function padDatePart(value: number): string {
+  return String(value).padStart(2, '0');
+}
+
+/** `DatePicker` speaks `YYYY-MM-DD`. The filter model keeps a local `Date`. */
+function dateValueToPickerValue(value: unknown): DatePickerProps['value'] {
+  let wire: string | undefined;
+  if (value instanceof Date && Number.isFinite(value.getTime())) {
+    wire = `${String(value.getFullYear())}-${padDatePart(value.getMonth() + 1)}-${padDatePart(value.getDate())}`;
+  } else if (typeof value === 'string' && pickerValueToDate(value.slice(0, 10))) {
+    wire = value.slice(0, 10);
+  }
+  return wire as DatePickerProps['value'];
+}
+
+function pickerValueToDate(value: string): Date | undefined {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) {
+    return undefined;
+  }
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const date = new Date(year, month - 1, day);
+  return date.getFullYear() === year && date.getMonth() === month - 1 && date.getDate() === day
+    ? date
+    : undefined;
+}
+
+function FilterDateValue({
+  value,
+  accessibilityLabel,
+  onChange,
+}: {
+  value: unknown;
+  accessibilityLabel: string;
+  onChange: (date: Date | undefined) => void;
+}) {
+  return (
+    <DatePicker
+      value={dateValueToPickerValue(value)}
+      onValueChange={(next) => onChange(next === undefined ? undefined : pickerValueToDate(next))}
+      className="w-full gap-0"
+    >
+      <DateField.Group size="small" fullWidth>
+        <DateField.Input />
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DatePicker.Popover>
+        <DatePicker.Calendar aria-label={accessibilityLabel} />
+      </DatePicker.Popover>
+    </DatePicker>
+  );
+}
+
+export function createDefaultFilterItem<R extends GridValidRowModel>(
+  columns: readonly GridColDef<R>[],
+): GridFilterItem | undefined {
+  if (columns.length === 0) {
+    return undefined;
+  }
+  const col = columns[0];
+  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,
+): GridFilterOperator {
+  const operators = getGridFilterOperators(col?.type);
+  return item.operator !== undefined && operators.includes(item.operator)
+    ? item.operator
+    : getDefaultFilterOperator(col?.type);
+}
+
+function itemWithValueText<R extends GridValidRowModel>(
+  col: GridColDef<R> | undefined,
+  field: string,
+  operator: GridFilterOperator,
+  text: string,
+): GridFilterItem {
+  if (!filterOperatorNeedsValue(operator)) {
+    return { field, operator };
+  }
+  return {
+    field,
+    operator,
+    value: text.trim().length > 0 ? headerFilterValueFromText(col, operator, text) : undefined,
+  };
+}
+
+function FilterPanelRow<R extends GridValidRowModel>({
+  index,
+  operatorFieldRef,
+  valueFieldRef,
+  item,
+  columns,
+  logicOperator,
+  onLogicOperatorChange,
+  onChange,
+  onRemove,
+}: {
+  index: number;
+  operatorFieldRef?: RefObject<View | null>;
+  valueFieldRef?: RefObject<View | null>;
+  item: GridFilterItem;
+  columns: readonly GridColDef<R>[];
+  logicOperator: GridLogicOperator;
+  onLogicOperatorChange: (operator: GridLogicOperator) => void;
+  onChange: (item: GridFilterItem) => void;
+  onRemove: () => void;
+}) {
+  const col = columns.find((candidate) => candidate.field === item.field);
+  const operator = resolveItemOperator(col, item);
+  const operators = getGridFilterOperators(col?.type);
+  const valueText = filterValueToInputText(item.value);
+  const rowLabel = `filter ${(index + 1).toString()}`;
+
+  return (
+    <View className={dataGridFilterPanelRowVariants()} accessibilityRole="none">
+      <IconButton
+        as={Close}
+        variant="ghost"
+        color="neutral"
+        size="small"
+        iconClassName="size-4"
+        accessibilityLabel={`Remove ${rowLabel}`}
+        onPress={onRemove}
+      />
+      <View className={dataGridFilterPanelLogicVariants()}>
+        {index === 1 ? (
+          <Select
+            items={[...LOGIC_OPERATORS]}
+            value={logicOperator}
+            onValueChange={(next) => {
+              const nextOperator = LOGIC_OPERATORS.find((candidate) => candidate.value === next);
+              if (nextOperator) {
+                onLogicOperatorChange(nextOperator.value);
+              }
+            }}
+            size="small"
+            className="w-full"
+            accessibilityLabel="Logic operator"
+          >
+            <Select.Trigger>
+              <Select.Value />
+            </Select.Trigger>
+            <Select.Content>
+              {LOGIC_OPERATORS.map((candidate) => (
+                <Select.Item key={candidate.value} value={candidate.value}>
+                  <Select.ItemLabel>{candidate.label}</Select.ItemLabel>
+                </Select.Item>
+              ))}
+            </Select.Content>
+          </Select>
+        ) : index > 1 ? (
+          <Text className="px-3 text-sm text-content-secondary">
+            {logicOperatorLabel(logicOperator)}
+          </Text>
+        ) : null}
+      </View>
+      <View className={dataGridFilterPanelFieldVariants({ size: 'column' })}>
+        <Text className="text-xs text-content-secondary">Columns</Text>
+        <Select
+          items={columns.map((candidate) => ({
+            value: candidate.field,
+            label: candidate.headerName ?? candidate.field,
+          }))}
+          value={item.field}
+          onValueChange={(next) => {
+            const nextCol = columns.find((candidate) => candidate.field === next);
+            if (nextCol && nextCol.field !== item.field) {
+              onChange({ field: nextCol.field, operator: getDefaultFilterOperator(nextCol.type) });
+            }
+          }}
+          size="small"
+          className={dataGridFilterPanelColumnVariants()}
+          accessibilityLabel={`Column for ${rowLabel}`}
+        >
+          <Select.Trigger>
+            <Select.Value />
+          </Select.Trigger>
+          <Select.Content>
+            {columns.map((candidate) => (
+              <Select.Item key={candidate.field} value={candidate.field}>
+                <Select.ItemLabel>{candidate.headerName ?? candidate.field}</Select.ItemLabel>
+              </Select.Item>
+            ))}
+          </Select.Content>
+        </Select>
+      </View>
+      <View
+        ref={operatorFieldRef}
+        className={dataGridFilterPanelFieldVariants({ size: 'operator' })}
+      >
+        <Text className="text-xs text-content-secondary">Operator</Text>
+        <Select
+          items={operators.map((candidate) => ({
+            value: candidate,
+            label: getFilterOperatorLabel(candidate),
+          }))}
+          value={operator}
+          onValueChange={(next) => {
+            const nextOperator = operators.find((candidate) => candidate === next);
+            if (nextOperator === undefined) {
+              return;
+            }
+            if (!filterOperatorNeedsValue(nextOperator)) {
+              onChange({ field: item.field, operator: nextOperator });
+            } else if (isDateColumn(col)) {
+              onChange({ field: item.field, operator: nextOperator, value: item.value });
+            } else if (col?.type === 'boolean') {
+              onChange(booleanFilterItem(item.field, nextOperator, booleanSelectValue(item.value)));
+            } else {
+              onChange(itemWithValueText(col, item.field, nextOperator, valueText));
+            }
+          }}
+          size="small"
+          className={dataGridFilterPanelOperatorVariants()}
+          accessibilityLabel={`Operator for ${rowLabel}`}
+        >
+          <Select.Trigger>
+            <Select.Value />
+          </Select.Trigger>
+          <Select.Content>
+            {operators.map((candidate) => (
+              <Select.Item key={candidate} value={candidate}>
+                <Select.ItemLabel>{getFilterOperatorLabel(candidate)}</Select.ItemLabel>
+              </Select.Item>
+            ))}
+          </Select.Content>
+        </Select>
+      </View>
+      <View ref={valueFieldRef} className={dataGridFilterPanelFieldVariants({ size: 'value' })}>
+        {filterOperatorNeedsValue(operator) ? (
+          <>
+            <Text className="text-xs text-content-secondary">Value</Text>
+            {isDateColumn(col) ? (
+              <FilterDateValue
+                value={item.value}
+                accessibilityLabel={`Value for ${rowLabel}`}
+                onChange={(date) =>
+                  onChange(
+                    date === undefined
+                      ? { field: item.field, operator }
+                      : { field: item.field, operator, value: date },
+                  )
+                }
+              />
+            ) : col?.type === 'boolean' ? (
+              <Select
+                items={[...BOOLEAN_FILTER_VALUES]}
+                value={booleanSelectValue(item.value)}
+                onValueChange={(next) => onChange(booleanFilterItem(item.field, operator, next))}
+                size="small"
+                className={dataGridFilterPanelValueVariants()}
+                accessibilityLabel={`Value for ${rowLabel}`}
+              >
+                <Select.Trigger>
+                  <Select.Value />
+                </Select.Trigger>
+                <Select.Content>
+                  {BOOLEAN_FILTER_VALUES.map((candidate) => (
+                    <Select.Item key={candidate.value} value={candidate.value}>
+                      <Select.ItemLabel>{candidate.label}</Select.ItemLabel>
+                    </Select.Item>
+                  ))}
+                </Select.Content>
+              </Select>
+            ) : (
+              <Input size="small" className={dataGridFilterPanelValueVariants()}>
+                <Input.Field
+                  value={valueText}
+                  onChangeText={(text) =>
+                    onChange(itemWithValueText(col, item.field, operator, text))
+                  }
+                  placeholder={filterPlaceholder(col, operator)}
+                  accessibilityLabel={`Value for ${rowLabel}`}
+                />
+              </Input>
+            )}
+          </>
+        ) : null}
+      </View>
+    </View>
+  );
+}
+
+export interface DataGridFilterPanelProps<R extends GridValidRowModel> {
+  columns: readonly GridColDef<R>[];
+  filterModel: GridFilterModel;
+  onFilterModelChange: (model: GridFilterModel) => void;
+  logicOperator: GridLogicOperator;
+  onLogicOperatorChange: (operator: GridLogicOperator) => void;
+  /** `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>({
+  columns,
+  filterModel,
+  onFilterModelChange,
+  logicOperator,
+  onLogicOperatorChange,
+  onClose,
+  opener,
+}: DataGridFilterPanelProps<R>) {
+  const anchored = opener.field !== undefined;
+  const panelRef = useRef<View>(null);
+  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 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)));
+  };
+  const removeItem = (index: number) => {
+    const next = items.filter((_, itemIndex) => itemIndex !== index);
+    onFilterModelChange(next);
+    if (next.length === 0) {
+      closeAndRestoreFocus();
+    }
+  };
+
+  const panel = (
+    <View
+      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"
+    >
+      {items.map((item, index) => (
+        <FilterPanelRow
+          key={index}
+          index={index}
+          operatorFieldRef={index === targetIndex ? operatorFieldRef : undefined}
+          valueFieldRef={index === targetIndex ? valueFieldRef : undefined}
+          item={item}
+          columns={columns}
+          logicOperator={logicOperator}
+          onLogicOperatorChange={onLogicOperatorChange}
+          onChange={(next) => replaceItem(index, next)}
+          onRemove={() => removeItem(index)}
+        />
+      ))}
+      <View className={dataGridFilterPanelFooterVariants()}>
+        <Button
+          variant="ghost"
+          color="action"
+          size="small"
+          isDisabled={defaultItem === undefined}
+          onPress={() => {
+            if (defaultItem) {
+              onFilterModelChange([...items, defaultItem]);
+            }
+          }}
+        >
+          <Button.Icon as={Add} />
+          <Button.Label>Add filter</Button.Label>
+        </Button>
+        <Button
+          variant="ghost"
+          color="action"
+          size="small"
+          onPress={() => {
+            onFilterModelChange([]);
+            closeAndRestoreFocus();
+          }}
+        >
+          <Button.Icon as={Delete} />
+          <Button.Label>Remove all</Button.Label>
+        </Button>
+      </View>
+    </View>
+  );
+
+  return anchored ? <OverlayContainer onDismiss={dismiss}>{panel}</OverlayContainer> : panel;
+}