Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
15.4 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file useTableGroupedRows.tsx
 * @input React, StyleX, Icon, Table types + the flat data array
 * @output Exports useTableGroupedRows hook + config/result types with layout-safe group headers
 * @position Grouped-rows plugin; consumed by Table via plugins prop
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/Table/index.ts (exports)
 */

import {useCallback, useMemo, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
  spacingVars,
  colorVars,
  fontWeightVars,
} from '../../../theme/tokens.stylex';
import {Icon} from '../../../Icon';
import type {TablePlugin} from '../../types';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../../../i18n/useComponentTranslator';
import english from '../../../i18n/generated-english/Table/plugins/groupedRows/useTableGroupedRows.generated';

registerEnglishFallback(english);

// A synthetic group-header row injected into the flattened data. Real rows
// never carry this marker.
const GROUP_HEADER = Symbol('tableGroupHeader');

interface GroupHeader {
  [GROUP_HEADER]: true;
  groupKey: string;
  count: number;
}

function isGroupHeader(item: unknown): item is GroupHeader {
  return (
    typeof item === 'object' &&
    item !== null &&
    (item as Record<symbol, unknown>)[GROUP_HEADER] === true
  );
}

// Proxy handler: any field access beyond the marker fields resolves to `''`,
// which keeps anything that reads a header's data — the sortable and filtering
// plugins, a consumer's own row handler — off `undefined`. Cell renderers are
// handled at render time instead (see `transformBodyCell` below); the Proxy
// never protected them, because `''` fails a lookup exactly as `undefined` does.
const HEADER_PROXY_HANDLER: ProxyHandler<Record<string | symbol, unknown>> = {
  // eslint-disable-next-line @typescript-eslint/promise-function-async -- Proxy get trap, not a promise-returning fn
  get(t: Record<string | symbol, unknown>, prop: string | symbol): unknown {
    if (prop === GROUP_HEADER || prop === 'groupKey' || prop === 'count') {
      return t[prop];
    }
    return prop in t ? t[prop] : '';
  },
};

/**
 * Build a synthetic header row wrapped in a Proxy so field access resolves to
 * `''` instead of `undefined`. `transformBodyRow` then discards the row's
 * cells and renders a single full-width header cell.
 */
function makeHeader<T extends Record<string, unknown>>(
  groupKey: string,
  count: number,
): T {
  const target: Record<string | symbol, unknown> = {
    [GROUP_HEADER]: true,
    groupKey,
    count,
  };
  return new Proxy(target, HEADER_PROXY_HANDLER) as unknown as T;
}

/** Configuration for {@link useTableGroupedRows}. */
export interface UseTableGroupedRowsConfig<T extends Record<string, unknown>> {
  /** The flat data to group. */
  data: T[];
  /** Derive the group key for a row. Rows with the same key share a section. */
  groupBy: (item: T) => string;
  /** Set of currently-collapsed group keys. */
  collapsedGroups: Set<string>;
  /** Called with a group key when its header is toggled. */
  onToggleGroup: (groupKey: string) => void;
  /**
   * Custom renderer for a group header's content (right of the chevron).
   * Defaults to `<groupKey> (<count>)`.
   */
  renderGroupHeader?: (
    groupKey: string,
    count: number,
    collapsed: boolean,
  ) => ReactNode;
  /** Stable key for a real row. Falls back to a positional key when omitted. */
  getRowKey?: (item: T) => string;
  /** Explicit group ordering; groups not listed keep first-seen order after these. */
  groupOrder?: string[];
}

export interface UseTableGroupedRowsResult<T extends Record<string, unknown>> {
  /** Ready-to-use plugin for `<Table plugins>`. */
  plugin: TablePlugin<T>;
  /** Flattened rows: `[header, ...visibleRows, header, ...visibleRows]`. */
  data: T[];
  /**
   * Row-key resolver (also keys synthetic headers as `__group_<key>`). Pass to
   * `<Table idKey>` — named for parallelism with the Table prop:
   * `<Table idKey={grouped.idKey} />`.
   */
  idKey: (item: T) => string;
}

const styles = stylex.create({
  headerRow: {
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
    userSelect: 'none',
    backgroundColor: colorVars['--color-background-muted'],
    // Divider beneath each group header row (Ernest review #2).
    borderBottomWidth: '1px',
    borderBottomStyle: 'solid',
    borderBottomColor: colorVars['--color-border'],
  },
  headerCell: {
    paddingBlock: spacingVars['--spacing-2'],
    // The start gutter lives on headerInner instead, so that it travels with
    // the heading when the heading pins. Left here, the heading would sit one
    // gutter in at rest and jump flush the moment it stuck.
    paddingInlineStart: 0,
    paddingInlineEnd: spacingVars['--spacing-3'],
  },
  // Shared row layout. Custom renderers keep this full-width so their layout
  // continues to use the full spanning cell.
  headerInner: {
    display: 'flex',
    alignItems: 'center',
    gap: spacingVars['--spacing-1'],
    // No inline start padding on the cell, so the chevron aligns with the
    // table's leading edge (Ernest review #1).
    paddingInlineStart: spacingVars['--spacing-1'],
  },
  // The built-in heading moves with its chevron and can safely shrink-wrap.
  headerInnerPinned: {
    insetInlineStart: 0,
    position: 'sticky',
    width: 'fit-content',
  },
  // A custom header may rely on the full row width. Pin only the plugin-owned
  // control so custom content keeps its original containing block.
  customHeaderChevronPinned: {
    insetInlineStart: spacingVars['--spacing-1'],
    position: 'sticky',
    zIndex: 1,
  },
  // Standalone chevron button with no heavy chrome (transparent, borderless,
  // zero padding) so the icon sits flush with the start of the table
  // (Ernest review #1) while staying keyboard-operable.
  chevron: {
    display: 'inline-flex',
    alignItems: 'center',
    justifyContent: 'center',
    flexShrink: '0',
    padding: 0,
    margin: 0,
    backgroundColor: 'transparent',
    borderWidth: 0,
    borderStyle: 'none',
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
    color: {
      default: colorVars['--color-icon-secondary'],
      ':hover:where(:not(:disabled,[aria-disabled="true"]))':
        colorVars['--color-icon-primary'],
    },
  },
  chevronIcon: {
    transitionProperty: 'transform',
    transitionDuration: '150ms',
  },
  // The RTL mirror is folded into each state's transform rather than living on
  // a parent span. Both are `transform`, so on one element the later value
  // would win — spelling out `scaleX(-1) rotate(...)` per state composes them
  // exactly as the nested elements did, while leaving a single element to
  // carry the glyph's theme target.
  chevronIconCollapsed: {
    transform: {
      default: 'rotate(0deg)',
      ':is([dir="rtl"] *)': 'scaleX(-1) rotate(0deg)',
    },
  },
  chevronIconExpanded: {
    transform: {
      default: 'rotate(90deg)',
      ':is([dir="rtl"] *)': 'scaleX(-1) rotate(90deg)',
    },
  },
  // Emphasized body text — same size as body, heavier weight (Ernest #3).
  label: {
    fontWeight: fontWeightVars['--font-weight-semibold'],
    color: colorVars['--color-text-primary'],
  },
  count: {
    fontWeight: fontWeightVars['--font-weight-normal'],
    color: colorVars['--color-text-secondary'],
  },
});

/**
 * Groups a flat data array into collapsible section rows. Each distinct
 * `groupBy` value becomes a full-width section-header row with a chevron
 * toggle, the group label, and a member count; collapsing hides that group's
 * data rows while keeping the header visible.
 *
 * Mirrors other controlled Table state helpers: the consumer owns the
 * `collapsedGroups` set and this hook returns `{data, plugin, idKey}`:
 * pass all three to `<Table>`.
 *
 * @example
 * ```
 * const [collapsed, setCollapsed] = useState<Set<string>>(new Set());
 * const grouped = useTableGroupedRows({
 *   data: rows,
 *   groupBy: r => r.team,
 *   collapsedGroups: collapsed,
 *   onToggleGroup: key =>
 *     setCollapsed(prev => {
 *       const next = new Set(prev);
 *       next.has(key) ? next.delete(key) : next.add(key);
 *       return next;
 *     }),
 *   getRowKey: r => r.id,
 * });
 * <Table
 *   data={grouped.data}
 *   columns={columns}
 *   idKey={grouped.idKey}
 *   plugins={{grouped: grouped.plugin}}
 * />;
 * ```
 *
 * ## Pairing with pagination
 *
 * Grouping runs on the rows it is handed, so the order is filter, sort, slice,
 * then group. Sort by the group key first and the reader's own keys second —
 * the same `ORDER BY group, sort` a backend would run. That keeps a section's
 * rows contiguous in the result set, so pages fill sections in order and new
 * rows always land at the bottom of the table. Slice a differently-ordered
 * list and every page holds a scatter of sections instead, so loading more
 * splices rows into the middle and new headings appear above the fold.
 *
 * @example
 * ```
 * const ordered = useMemo(
 *   () => [...filtered].sort((a, b) => byTeam(a, b) || bySortKeys(a, b)),
 *   [filtered, sortKeys],
 * );
 * const page = ordered.slice(0, loadedCount);
 *
 * const grouped = useTableGroupedRows({
 *   data: page,
 *   groupBy: r => r.team,
 *   collapsedGroups,
 *   onToggleGroup,
 * });
 * ```
 */
export function useTableGroupedRows<T extends Record<string, unknown>>(
  config: UseTableGroupedRowsConfig<T>,
): UseTableGroupedRowsResult<T> {
  const t = useComponentTranslator();
  const {
    data,
    groupBy,
    collapsedGroups,
    onToggleGroup,
    renderGroupHeader,
    getRowKey: getRowKeyProp,
    groupOrder,
  } = config;

  const flattened = useMemo((): T[] => {
    if (data.length === 0) {
      return [];
    }

    // Group preserving first-seen order.
    const groups = new Map<string, T[]>();
    for (const item of data) {
      const key = groupBy(item);
      const bucket = groups.get(key);
      if (bucket) {
        bucket.push(item);
      } else {
        groups.set(key, [item]);
      }
    }

    // Determine iteration order.
    let keys = [...groups.keys()];
    if (groupOrder && groupOrder.length > 0) {
      const ordered = groupOrder.filter(k => groups.has(k));
      const rest = keys.filter(k => !groupOrder.includes(k));
      keys = [...ordered, ...rest];
    }

    const out: T[] = [];
    for (const key of keys) {
      const rows = groups.get(key) ?? [];
      out.push(makeHeader<T>(key, rows.length));
      if (!collapsedGroups.has(key)) {
        out.push(...rows);
      }
    }
    return out;
  }, [data, groupBy, collapsedGroups, groupOrder]);

  // Positional fallback index, built once per flattened array so key lookup
  // stays O(1) instead of O(n) per row (which would make table keying O(n²)).
  const positionByItem = useMemo(() => {
    if (getRowKeyProp) {
      return null;
    }
    const map = new Map<T, number>();
    for (let i = 0; i < flattened.length; i++) {
      map.set(flattened[i], i);
    }
    return map;
  }, [flattened, getRowKeyProp]);

  const idKey = useCallback(
    (item: T): string => {
      if (isGroupHeader(item)) {
        return `__group_${item.groupKey}`;
      }
      if (getRowKeyProp) {
        return getRowKeyProp(item);
      }
      return String(positionByItem?.get(item) ?? -1);
    },
    [getRowKeyProp, positionByItem],
  );

  const plugin = useMemo(
    (): TablePlugin<T> => ({
      rowModel: 'grouped',
      // A header row is not one of the caller's rows, so running a cell
      // renderer against it can only misread it or throw — and the cells are
      // discarded by `transformBodyRow` below regardless.
      transformBodyCell(props, _column, item) {
        if (!isGroupHeader(item)) {
          return props;
        }
        return {...props, isContentSuppressed: true};
      },
      // Replace a header row's pre-rendered cells with one full-width cell.
      transformBodyRow(props, item) {
        if (!isGroupHeader(item)) {
          return props;
        }
        const header = item as unknown as GroupHeader;
        const collapsed = collapsedGroups.has(header.groupKey);
        const toggle = () => onToggleGroup(header.groupKey);
        const content: ReactNode = renderGroupHeader ? (
          renderGroupHeader(header.groupKey, header.count, collapsed)
        ) : (
          <span {...stylex.props(styles.label)}>
            {header.groupKey}{' '}
            <span {...stylex.props(styles.count)}>({header.count})</span>
          </span>
        );
        return {
          ...props,
          htmlProps: {
            ...props.htmlProps,
            // Convenience: clicking anywhere on the row toggles it. The chevron
            // button below owns the disclosure state and keyboard interaction;
            // the native row keeps only its implicit row semantics.
            onClick: toggle,
          },
          xstyle: [...props.xstyle, styles.headerRow],
          children: (
            // colSpan larger than the column count is clamped by the browser
            // to the actual number of columns, so the header always spans the
            // full width without the plugin knowing the column count.
            <td colSpan={999} {...stylex.props(styles.headerCell)}>
              <span
                {...stylex.props(
                  styles.headerInner,
                  !renderGroupHeader && styles.headerInnerPinned,
                )}>
                {/* Standalone chevron button, flush with the table's start
                    edge (no heavy button chrome) — the keyboard control. */}
                <button
                  type="button"
                  {...stylex.props(
                    styles.chevron,
                    renderGroupHeader && styles.customHeaderChevronPinned,
                  )}
                  onClick={e => {
                    e.stopPropagation();
                    toggle();
                  }}
                  aria-label={
                    collapsed
                      ? t('@astryx.tableGroupedRows.expandGroup', {
                          groupKey: header.groupKey,
                        })
                      : t('@astryx.tableGroupedRows.collapseGroup', {
                          groupKey: header.groupKey,
                        })
                  }
                  aria-expanded={!collapsed}>
                  <Icon
                    icon="chevronRight"
                    // 16px, not the 12px this started at. The chevron is the
                    // control for the whole section and sits beside a heading,
                    // so at 12 it read as decoration on the label rather than
                    // the thing you press, and it was the smallest hit target
                    // in the table.
                    size="sm"
                    // The rotation rides on the glyph rather than a wrapper
                    // span so the theme target below reaches both the mark and
                    // its open/closed transform.
                    xstyle={[
                      styles.chevronIcon,
                      collapsed
                        ? styles.chevronIconCollapsed
                        : styles.chevronIconExpanded,
                    ]}
                  />
                </button>
                {content}
              </span>
            </td>
          ),
        };
      },
    }),
    [collapsedGroups, onToggleGroup, renderGroupHeader, t],
  );

  return {plugin, data: flattened, idKey};
}