@astryxdesign/core 0.1.5-canary.efe7cc3 → 0.1.5

package/src/Table/plugins/groupedRows/useTableGroupedRows.test.tsx

@@ -1,231 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, it, expect} from 'vitest';
-import {render, screen, fireEvent, within} from '@testing-library/react';
-import {useState, useCallback} from 'react';
-import {Table} from '../../Table';
-import type {TableColumn} from '../../types';
-import {useTableGroupedRows} from './useTableGroupedRows';
-
-interface Person extends Record<string, unknown> {
-  id: string;
-  name: string;
-  team: string;
-}
-
-const people: Person[] = [
-  {id: 'a', name: 'Alice', team: 'Core'},
-  {id: 'b', name: 'Bob', team: 'Core'},
-  {id: 'c', name: 'Carol', team: 'Infra'},
-];
-
-const columns: TableColumn<Person>[] = [{key: 'name', header: 'Name'}];
-
-const EMPTY = new Set<string>();
-
-function Harness({
-  rows = people,
-  initialCollapsed = EMPTY,
-  renderGroupHeader,
-}: {
-  rows?: Person[];
-  initialCollapsed?: Set<string>;
-  renderGroupHeader?: (
-    groupKey: string,
-    count: number,
-    collapsed: boolean,
-  ) => React.ReactNode;
-}) {
-  const [collapsedGroups, setCollapsed] = useState(initialCollapsed);
-  const onToggleGroup = useCallback((key: string) => {
-    setCollapsed(prev => {
-      const next = new Set(prev);
-      if (next.has(key)) {
-        next.delete(key);
-      } else {
-        next.add(key);
-      }
-      return next;
-    });
-  }, []);
-  const grouped = useTableGroupedRows<Person>({
-    data: rows,
-    groupBy: p => p.team,
-    collapsedGroups,
-    onToggleGroup,
-    getRowKey: p => p.id,
-    renderGroupHeader,
-  });
-  return (
-    <Table
-      data={grouped.data}
-      columns={columns}
-      idKey={grouped.idKey}
-      plugins={{grouped: grouped.plugin}}
-    />
-  );
-}
-
-describe('useTableGroupedRows', () => {
-  it('renders a header row per group with label and count', () => {
-    render(<Harness />);
-    // Two groups: Core (2), Infra (1).
-    expect(screen.getByText('Core')).toBeInTheDocument();
-    expect(screen.getByText('(2)')).toBeInTheDocument();
-    expect(screen.getByText('Infra')).toBeInTheDocument();
-    expect(screen.getByText('(1)')).toBeInTheDocument();
-  });
-
-  it('shows group members when expanded', () => {
-    render(<Harness />);
-    expect(screen.getByText('Alice')).toBeInTheDocument();
-    expect(screen.getByText('Bob')).toBeInTheDocument();
-    expect(screen.getByText('Carol')).toBeInTheDocument();
-  });
-
-  it('hides members of a collapsed group but keeps the header', () => {
-    render(<Harness initialCollapsed={new Set(['Core'])} />);
-    expect(screen.getByText('Core')).toBeInTheDocument();
-    expect(screen.queryByText('Alice')).not.toBeInTheDocument();
-    expect(screen.queryByText('Bob')).not.toBeInTheDocument();
-    // Other group unaffected.
-    expect(screen.getByText('Carol')).toBeInTheDocument();
-  });
-
-  it('toggles a group via its chevron and back again', () => {
-    render(<Harness />);
-    expect(screen.getByText('Alice')).toBeInTheDocument();
-    // The standalone chevron button toggles the group; its accessible name is
-    // qualified with the group key.
-    fireEvent.click(screen.getByRole('button', {name: 'Collapse group Core'}));
-    expect(screen.queryByText('Alice')).not.toBeInTheDocument();
-    expect(screen.queryByText('Bob')).not.toBeInTheDocument();
-    expect(screen.getByText('Core')).toBeInTheDocument();
-    expect(screen.getByText('Carol')).toBeInTheDocument();
-    // Toggle back: the Core chevron now says "Expand group Core".
-    fireEvent.click(screen.getByRole('button', {name: 'Expand group Core'}));
-    expect(screen.getByText('Alice')).toBeInTheDocument();
-    expect(screen.getByText('Bob')).toBeInTheDocument();
-  });
-
-  it('exposes each group toggle as a named, keyboard-operable button', () => {
-    render(<Harness />);
-    // Native <button>: focusable and operable without a custom key handler.
-    const coreToggle = screen.getByRole('button', {
-      name: 'Collapse group Core',
-    });
-    expect(coreToggle.tagName).toBe('BUTTON');
-    expect(coreToggle).toHaveAttribute('aria-expanded', 'true');
-  });
-
-  it('sets aria-expanded on the header row reflecting collapse state', () => {
-    render(<Harness initialCollapsed={new Set(['Core'])} />);
-    const rows = screen.getAllByRole('row');
-    // rows[1] = Core header (collapsed), rows[2] = Infra header (expanded).
-    expect(rows[1]).toHaveAttribute('aria-expanded', 'false');
-    expect(rows[2]).toHaveAttribute('aria-expanded', 'true');
-  });
-
-  it('respects groupOrder in the flattened data', () => {
-    function OrderedHarness() {
-      const [collapsed, setCollapsed] = useState<Set<string>>(new Set());
-      const grouped = useTableGroupedRows<Person>({
-        data: people,
-        groupBy: p => p.team,
-        collapsedGroups: collapsed,
-        onToggleGroup: k => setCollapsed(new Set([k])),
-        getRowKey: p => p.id,
-        groupOrder: ['Infra', 'Core'],
-      });
-      expect(grouped.data.length).toBeGreaterThan(0);
-      return (
-        <Table
-          data={grouped.data}
-          columns={columns}
-          idKey={grouped.idKey}
-          plugins={{grouped: grouped.plugin}}
-        />
-      );
-    }
-    render(<OrderedHarness />);
-    const rows = screen.getAllByRole('row');
-    // rows[0] = column header; rows[1] = first group header (Infra).
-    expect(within(rows[1]).getByText('Infra')).toBeInTheDocument();
-  });
-
-  it('renders custom group header content via renderGroupHeader', () => {
-    render(
-      <Harness
-        renderGroupHeader={(key, count, collapsed) => (
-          <span>{`${key}::${count}::${collapsed ? 'closed' : 'open'}`}</span>
-        )}
-      />,
-    );
-    expect(screen.getByText('Core::2::open')).toBeInTheDocument();
-    expect(screen.getByText('Infra::1::open')).toBeInTheDocument();
-  });
-
-  it('renders nothing (no group headers) for empty data', () => {
-    render(<Harness rows={[]} />);
-    // Column header row still renders; no group header rows.
-    expect(screen.queryByText('Core')).not.toBeInTheDocument();
-    expect(screen.queryByText('Infra')).not.toBeInTheDocument();
-    expect(
-      screen.queryByRole('button', {name: /group/i}),
-    ).not.toBeInTheDocument();
-  });
-
-  it('keeps a group collapsed across a data change (state keyed by group)', () => {
-    function ChangingHarness() {
-      const [collapsed, setCollapsed] = useState<Set<string>>(
-        new Set(['Core']),
-      );
-      const [rows, setRows] = useState(people);
-      const onToggleGroup = useCallback((key: string) => {
-        setCollapsed(prev => {
-          const next = new Set(prev);
-          if (next.has(key)) {
-            next.delete(key);
-          } else {
-            next.add(key);
-          }
-          return next;
-        });
-      }, []);
-      const grouped = useTableGroupedRows<Person>({
-        data: rows,
-        groupBy: p => p.team,
-        collapsedGroups: collapsed,
-        onToggleGroup,
-        getRowKey: p => p.id,
-      });
-      return (
-        <>
-          <button
-            type="button"
-            onClick={() =>
-              setRows([...people, {id: 'd', name: 'Dave', team: 'Core'}])
-            }>
-            add
-          </button>
-          <Table
-            data={grouped.data}
-            columns={columns}
-            idKey={grouped.idKey}
-            plugins={{grouped: grouped.plugin}}
-          />
-        </>
-      );
-    }
-    render(<ChangingHarness />);
-    // Core collapsed initially: Alice hidden.
-    expect(screen.queryByText('Alice')).not.toBeInTheDocument();
-    // Add a new Core member; Core must stay collapsed (keyed by group value).
-    fireEvent.click(screen.getByText('add'));
-    expect(screen.queryByText('Alice')).not.toBeInTheDocument();
-    expect(screen.queryByText('Dave')).not.toBeInTheDocument();
-    // Count reflects the new member (3), header still present.
-    expect(screen.getByText('Core')).toBeInTheDocument();
-    expect(screen.getByText('(3)')).toBeInTheDocument();
-  });
-});

package/src/Table/plugins/groupedRows/useTableGroupedRows.tsx

@@ -1,349 +0,0 @@
-// 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
- * @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';
-
-// 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 `''`
-// so user cell renderers (`item.name.toUpperCase()`) never throw on a header.
-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 arbitrary field access
- * from user cell renderers (e.g. `item.name.toUpperCase()`) resolves to `''`
- * instead of throwing — BaseTable evaluates `col.renderCell(item)` on every
- * row (including synthetic headers) before `transformBodyRow` can replace the
- * row's cells. `transformBodyRow` then discards those 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: 'pointer',
-    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'],
-    // No inline start padding so the chevron aligns with the table's leading
-    // edge (Ernest review #1).
-    paddingInlineStart: spacingVars['--spacing-1'],
-    paddingInlineEnd: spacingVars['--spacing-3'],
-  },
-  headerInner: {
-    display: 'flex',
-    alignItems: 'center',
-    gap: spacingVars['--spacing-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,
-    background: 'transparent',
-    border: 'none',
-    cursor: 'pointer',
-    color: {
-      default: colorVars['--color-icon-secondary'],
-      ':hover': colorVars['--color-icon-primary'],
-    },
-  },
-  chevronIcon: {
-    display: 'inline-flex',
-    transitionProperty: 'transform',
-    transitionDuration: '150ms',
-  },
-  chevronExpanded: {
-    transform: '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 {@link useTableRowExpansionState}: the consumer owns the
- * `collapsedGroups` set and this hook returns `{data, plugin, idKey}` —
- * pass all three to `<Table>`.
- *
- * @example
- * ```tsx
- * 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}}
- * />;
- * ```
- */
-export function useTableGroupedRows<T extends Record<string, unknown>>(
-  config: UseTableGroupedRowsConfig<T>,
-): UseTableGroupedRowsResult<T> {
-  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> => ({
-      // 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 is the accessible, keyboard-operable control, so the
-            // row keeps its implicit `row` role (no role override here).
-            onClick: toggle,
-            'aria-expanded': !collapsed,
-          },
-          styles: [...props.styles, 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)}>
-                {/* Standalone chevron button, flush with the table's start
-                    edge (no heavy button chrome) — the keyboard control. */}
-                <button
-                  type="button"
-                  {...stylex.props(styles.chevron)}
-                  onClick={e => {
-                    e.stopPropagation();
-                    toggle();
-                  }}
-                  aria-label={
-                    collapsed
-                      ? `Expand group ${header.groupKey}`
-                      : `Collapse group ${header.groupKey}`
-                  }
-                  aria-expanded={!collapsed}>
-                  <span
-                    {...stylex.props(
-                      styles.chevronIcon,
-                      !collapsed && styles.chevronExpanded,
-                    )}>
-                    <Icon icon="chevronRight" size="xsm" />
-                  </span>
-                </button>
-                {content}
-              </span>
-            </td>
-          ),
-        };
-      },
-    }),
-    [collapsedGroups, onToggleGroup, renderGroupHeader],
-  );
-
-  return {plugin, data: flattened, idKey};
-}

package/src/Table/useTableGroupedRows.doc.mjs

@@ -1,71 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('../docs-types').ComponentDoc} */
-
-export const docs = {
-  name: 'useTableGroupedRows',
-  subComponentOf: 'Table',
-  displayName: 'useTableGroupedRows',
-  description:
-    'Hook that 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\u2019s data rows while keeping the header visible. Mirrors useTableRowExpansionState: the consumer owns the collapsedGroups set and the hook returns {data, plugin, idKey} \u2014 pass all three to Table (data, plugins, and idKey respectively).',
-  props: [
-    {
-      name: 'data',
-      type: 'T[]',
-      description: 'The flat data to group.',
-      required: true,
-    },
-    {
-      name: 'groupBy',
-      type: '(item: T) => string',
-      description:
-        'Derive the group key for a row. Rows with the same key share a section.',
-      required: true,
-    },
-    {
-      name: 'collapsedGroups',
-      type: 'Set<string>',
-      description: 'Set of currently-collapsed group keys.',
-      required: true,
-    },
-    {
-      name: 'onToggleGroup',
-      type: '(groupKey: string) => void',
-      description: 'Called with a group key when its header is toggled.',
-      required: true,
-    },
-    {
-      name: 'renderGroupHeader',
-      type: '(groupKey: string, count: number, collapsed: boolean) => ReactNode',
-      description:
-        "Custom renderer for a group header's content (right of the chevron). Defaults to `<groupKey> (<count>)`.",
-    },
-    {
-      name: 'getRowKey',
-      type: '(item: T) => string',
-      description:
-        'Stable key for a real row. Falls back to a positional key when omitted.',
-    },
-    {
-      name: 'groupOrder',
-      type: 'string[]',
-      description:
-        'Explicit group ordering; groups not listed keep first-seen order after these.',
-    },
-  ],
-};
-
-/** @type {import('../docs-types').TranslationDoc} */
-export const docsDense = {
-  description:
-    'Groups a flat data array into collapsible section rows. Each groupBy value becomes a full-width header (chevron + label + count); collapsing hides its rows. Returns {data, plugin, idKey} \u2014 pass to Table data / plugins / idKey. Consumer owns the collapsedGroups set.',
-  propDescriptions: {
-    data: 'The flat data to group.',
-    groupBy: 'Derive a row\u2019s group key. Same key = same section.',
-    collapsedGroups: 'Set of currently-collapsed group keys.',
-    onToggleGroup: 'Called with the group key when a header is toggled.',
-    renderGroupHeader: "Custom header content (right of chevron). Default '<key> (<count>)'.",
-    getRowKey: 'Stable key for a real row; positional fallback when omitted.',
-    groupOrder: 'Pin these group keys first; others keep first-seen order.',
-  },
-};