@astryxdesign/core 0.1.7 → 0.1.8-canary.c5fa19b

package/src/Table/index.ts

@@ -32,6 +32,7 @@ export {
   useTableRowExpansion,
   useTableRowExpansionState,
 } from './plugins/rowExpansion';
+export {useTableTreeData, useTableTreeState} from './plugins/tree';
 export {resolveContextActions} from './tableContextMenu';
 export {
   useTableFiltering,
@@ -109,6 +110,12 @@ export type {
   UseTableGroupedRowsConfig,
   UseTableGroupedRowsResult,
 } from './plugins/groupedRows';
+export type {
+  TableTreeRowMeta,
+  UseTableTreeDataConfig,
+  UseTableTreeStateConfig,
+  UseTableTreeStateResult,
+} from './plugins/tree';
 export type {
   UseTableFilteringConfig,
   TableFilterState,

package/src/Table/plugins/rowExpansion/useTableRowExpansion.test.tsx

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {render, renderHook, screen, fireEvent} from '@testing-library/react';
 import {useState} from 'react';
 import {Table} from '../../Table';
 import type {TableColumn} from '../../types';
@@ -153,3 +153,92 @@ describe('useTableRowExpansion', () => {
     expect(screen.queryByText('File B1')).not.toBeInTheDocument();
   });
 });
+
+describe('useTableRowExpansionState cycle guard', () => {
+  /** A row whose children array contains the row itself (plus a real child). */
+  function makeSelfReferential(): TreeItem[] {
+    const x: TreeItem = {id: 'x', name: 'Self', children: []};
+    const y: TreeItem = {id: 'y', name: 'Leaf Y', children: []};
+    x.children.push(x, y);
+    return [x];
+  }
+
+  /** root -> child -> grand, where grand's children point back at root. */
+  function makeDeepCycle(): TreeItem[] {
+    const root: TreeItem = {id: 'root', name: 'Root', children: []};
+    const child: TreeItem = {id: 'child', name: 'Child', children: []};
+    const grand: TreeItem = {id: 'grand', name: 'Grand', children: []};
+    root.children.push(child);
+    child.children.push(grand);
+    grand.children.push(root);
+    return [root];
+  }
+
+  function renderState(baseData: TreeItem[], expandedKeys: Set<string>) {
+    const setExpandedKeys = vi.fn();
+    const hook = renderHook(() =>
+      useTableRowExpansionState<TreeItem>({
+        baseData,
+        getChildren: item => item.children,
+        getRowKey: item => item.id,
+        expandedKeys,
+        setExpandedKeys,
+      }),
+    );
+    return {hook, setExpandedKeys};
+  }
+
+  it('terminates on a self-referential expanded row and flattens each key once', () => {
+    const {hook} = renderState(makeSelfReferential(), new Set(['x']));
+    const {data, expansionConfig} = hook.result.current;
+    expect(data.map(item => item.id)).toEqual(['x', 'y']);
+    expect(expansionConfig.getDepth?.(data[0])).toBe(0);
+    expect(expansionConfig.getDepth?.(data[1])).toBe(1);
+  });
+
+  it('terminates on a deeper cycle back to the root and flattens each key once', () => {
+    const {hook} = renderState(
+      makeDeepCycle(),
+      new Set(['root', 'child', 'grand']),
+    );
+    const {data, expansionConfig} = hook.result.current;
+    expect(data.map(item => item.id)).toEqual(['root', 'child', 'grand']);
+    expect(expansionConfig.getDepth?.(data[0])).toBe(0);
+    expect(expansionConfig.getDepth?.(data[1])).toBe(1);
+    expect(expansionConfig.getDepth?.(data[2])).toBe(2);
+    // The cycle guard keeps isAllExpanded computable — true, not a crash.
+    expect(expansionConfig.isAllExpanded).toBe(true);
+  });
+
+  it('terminates when collecting allExpandableKeys on cyclic data with nothing expanded', () => {
+    const {hook, setExpandedKeys} = renderState(
+      makeDeepCycle(),
+      new Set<string>(),
+    );
+    const {data, expansionConfig} = hook.result.current;
+    expect(data.map(item => item.id)).toEqual(['root']);
+    expansionConfig.onToggleExpandAll?.(true);
+    const nextKeys = setExpandedKeys.mock.calls[0][0] as Set<string>;
+    expect(Array.from(nextKeys)).toEqual(['root', 'child', 'grand']);
+  });
+
+  it('re-walks a shared child under each expanded parent (ancestor-path, not visited-set, semantics)', () => {
+    const leaf: TreeItem = {id: 'leaf', name: 'Leaf', children: []};
+    const shared: TreeItem = {id: 's', name: 'Shared', children: [leaf]};
+    const p1: TreeItem = {id: 'p1', name: 'Parent 1', children: [shared]};
+    const p2: TreeItem = {id: 'p2', name: 'Parent 2', children: [shared]};
+    const {hook} = renderState([p1, p2], new Set(['p1', 'p2', 's']));
+    // 's' is on neither parent's ancestor path, so it must flatten under
+    // both — the guard only skips true cycles, matching pre-guard behavior
+    // for acyclic (DAG-shaped) data.
+    const {data} = hook.result.current;
+    expect(data.map(item => item.id)).toEqual([
+      'p1',
+      's',
+      'leaf',
+      'p2',
+      's',
+      'leaf',
+    ]);
+  });
+});

package/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx

@@ -141,12 +141,19 @@ export function useTableRowExpansionState<T extends Record<string, unknown>>({
 
   const depthMap = useMemo(() => {
     const map = new Map<string, number>();
+    // Ancestor keys on the current walk path — guards against cyclic data.
+    const path = new Set<string>();
     function walk(items: T[], depth: number) {
       for (const item of items) {
         const key = getRowKey(item);
+        if (path.has(key)) {
+          continue; // cyclic edge — skip
+        }
         map.set(key, depth);
         if (expandedKeys.has(key)) {
+          path.add(key);
           walk(getChildren(item), depth + 1);
+          path.delete(key);
         }
       }
     }
@@ -156,12 +163,19 @@ export function useTableRowExpansionState<T extends Record<string, unknown>>({
 
   const data = useMemo(() => {
     const result: T[] = [];
+    // Ancestor keys on the current walk path — guards against cyclic data.
+    const path = new Set<string>();
     function walk(items: T[]) {
       for (const item of items) {
-        result.push(item);
         const key = getRowKey(item);
+        if (path.has(key)) {
+          continue; // cyclic edge — skip
+        }
+        result.push(item);
         if (expandedKeys.has(key)) {
+          path.add(key);
           walk(getChildren(item));
+          path.delete(key);
         }
       }
     }
@@ -172,11 +186,19 @@ export function useTableRowExpansionState<T extends Record<string, unknown>>({
   // Every expandable key across the whole tree (drives expand-all).
   const allExpandableKeys = useMemo(() => {
     const keys: string[] = [];
+    // Ancestor keys on the current walk path — guards against cyclic data.
+    const path = new Set<string>();
     function walk(items: T[]) {
       for (const item of items) {
+        const key = getRowKey(item);
+        if (path.has(key)) {
+          continue; // cyclic edge — skip
+        }
         if (isExpandable(item)) {
-          keys.push(getRowKey(item));
+          keys.push(key);
+          path.add(key);
           walk(getChildren(item));
+          path.delete(key);
         }
       }
     }
@@ -399,7 +421,11 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
           <ExpansionChevron
             isExpanded={isExpanded}
             onToggle={() => onToggle(key)}
-            ariaLabel={isExpanded ? t('@astryx.tableRowExpansion.collapseRow') : t('@astryx.tableRowExpansion.expandRow')}
+            ariaLabel={
+              isExpanded
+                ? t('@astryx.tableRowExpansion.collapseRow')
+                : t('@astryx.tableRowExpansion.expandRow')
+            }
           />
         );
       },
@@ -457,7 +483,11 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
                 <ExpansionChevron
                   isExpanded={isExpanded}
                   onToggle={() => onToggle(key)}
-                  ariaLabel={isExpanded ? t('@astryx.tableRowExpansion.collapseRow') : t('@astryx.tableRowExpansion.expandRow')}
+                  ariaLabel={
+                    isExpanded
+                      ? t('@astryx.tableRowExpansion.collapseRow')
+                      : t('@astryx.tableRowExpansion.expandRow')
+                  }
                 />
               ) : (
                 <span {...stylex.props(expansionStyles.placeholder)} />
@@ -499,7 +529,9 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
                 {...stylex.props(expansionStyles.chevronButton)}
                 onClick={() => onToggleExpandAll(!allExpanded)}
                 aria-label={
-                  allExpanded ? t('@astryx.tableRowExpansion.collapseAllRows') : t('@astryx.tableRowExpansion.expandAllRows')
+                  allExpanded
+                    ? t('@astryx.tableRowExpansion.collapseAllRows')
+                    : t('@astryx.tableRowExpansion.expandAllRows')
                 }>
                 <span
                   {...stylex.props(

package/src/Table/plugins/sortable/useTableSortable.test.tsx

@@ -12,11 +12,9 @@ import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {useState} from 'react';
 import {Table} from '../../Table';
+import {InternationalizationProvider} from '../../../i18n';
 import type {TableColumn} from '../../types';
-import {
-  useTableSortable,
-  type TableSortState,
-} from './useTableSortable';
+import {useTableSortable, type TableSortState} from './useTableSortable';
 
 // =============================================================================
 // Test Data
@@ -73,9 +71,7 @@ function SortableTable({
     isMultiSortEnabled,
   });
 
-  return (
-    <Table data={data} columns={columns} plugins={{sort: sortPlugin}} />
-  );
+  return <Table data={data} columns={columns} plugins={{sort: sortPlugin}} />;
 }
 
 // =============================================================================
@@ -672,11 +668,15 @@ describe('useTableSortable — context menu actions', () => {
 
     // Apply ascending → "Clear sort" now appears.
     fireEvent.click(
-      screen.getAllByRole('menuitem', {name: 'Sort ascending', hidden: true})[0],
+      screen.getAllByRole('menuitem', {
+        name: 'Sort ascending',
+        hidden: true,
+      })[0],
     );
     fireEvent.contextMenu(screen.getByText('Name'));
     expect(
-      screen.getAllByRole('menuitem', {name: 'Clear sort', hidden: true}).length,
+      screen.getAllByRole('menuitem', {name: 'Clear sort', hidden: true})
+        .length,
     ).toBeGreaterThan(0);
   });
 
@@ -709,3 +709,89 @@ describe('useTableSortable — context menu actions', () => {
     expect(onSortChange).toHaveBeenLastCalledWith([]);
   });
 });
+
+// =============================================================================
+// i18n (header-button aria-labels route through the catalog)
+// =============================================================================
+
+describe('useTableSortable — i18n', () => {
+  it('localizes the unsorted sort-by aria-label via @astryx.table.sort.sortBy', () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{
+          fr: {'@astryx.table.sort.sortBy': 'Trier par {label}'},
+        }}>
+        <SortableTable />
+      </InternationalizationProvider>,
+    );
+
+    expect(
+      screen.getByRole('button', {name: 'Trier par Name'}),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('button', {name: 'Trier par Age'}),
+    ).toBeInTheDocument();
+  });
+
+  it('localizes the multi-sort priority aria-label with ICU number args', () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{
+          fr: {
+            '@astryx.table.sort.sortedByWithPriority':
+              'Trier par {label}, tri {direction}, priorité {rank, number} sur {total, number}',
+            '@astryx.table.sort.direction.ascending': 'croissant',
+            '@astryx.table.sort.direction.descending': 'décroissant',
+          },
+        }}>
+        <SortableTable
+          isMultiSortEnabled
+          initialSort={[
+            {sortKey: 'name', direction: 'ascending'},
+            {sortKey: 'age', direction: 'descending'},
+          ]}
+        />
+      </InternationalizationProvider>,
+    );
+
+    // The overridden direction words deliberately differ from the raw enum
+    // values ('ascending'/'descending'), so an implementation interpolating
+    // the enum without translating it cannot pass — for either direction.
+    expect(
+      screen.getByRole('button', {
+        name: 'Trier par Name, tri croissant, priorité 1 sur 2',
+      }),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('button', {
+        name: 'Trier par Age, tri décroissant, priorité 2 sur 2',
+      }),
+    ).toBeInTheDocument();
+  });
+
+  it('localizes the sorted aria-label and direction word via their own keys', () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{
+          fr: {
+            '@astryx.table.sort.sortedBy': 'Trié par {label}, {direction}',
+            '@astryx.table.sort.direction.ascending': 'croissant',
+          },
+        }}>
+        <SortableTable
+          initialSort={[{sortKey: 'name', direction: 'ascending'}]}
+        />
+      </InternationalizationProvider>,
+    );
+
+    // Both the composed template and the direction word resolve through
+    // their own catalog keys; 'croissant' differs from the raw enum value,
+    // so neither a hardcoded English frame nor raw-enum interpolation passes.
+    expect(
+      screen.getByRole('button', {name: 'Trié par Name, croissant'}),
+    ).toBeInTheDocument();
+  });
+});

package/src/Table/plugins/sortable/useTableSortable.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file useTableSortable.tsx
- * @input React, types, Icon, theme tokens
+ * @input React, types, Icon, theme tokens, i18n (useTranslator)
  * @output Exports useTableSortable hook and sort-related types
  * @position Sortable plugin; consumed by Table via plugins prop
  *
@@ -18,7 +18,7 @@ import * as stylex from '@stylexjs/stylex';
 import {colorVars, spacingVars, radiusVars} from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
 import {resolveContextActions} from '../../tableContextMenu';
-import {useTranslator} from '../../../i18n';
+import {useTranslator, type TranslatorFn} from '../../../i18n';
 import type {
   TablePlugin,
   HeaderCellRenderProps,
@@ -184,6 +184,7 @@ function getHeaderLabel<T extends Record<string, unknown>>(
 }
 
 function buildAriaLabel<T extends Record<string, unknown>>(
+  t: TranslatorFn,
   column: TableColumn<T>,
   direction: TableSortDirection | null,
   rank: number | null,
@@ -191,13 +192,21 @@ function buildAriaLabel<T extends Record<string, unknown>>(
 ): string {
   const label = getHeaderLabel(column);
   if (direction == null) {
-    return `Sort by ${label}`;
+    return t('@astryx.table.sort.sortBy', {label});
   }
-  let ariaLabel = `Sort by ${label}, sorted ${direction}`;
+  const directionLabel =
+    direction === 'ascending'
+      ? t('@astryx.table.sort.direction.ascending')
+      : t('@astryx.table.sort.direction.descending');
   if (rank != null && total > 1) {
-    ariaLabel += `, priority ${rank} of ${total}`;
+    return t('@astryx.table.sort.sortedByWithPriority', {
+      label,
+      direction: directionLabel,
+      rank,
+      total,
+    });
   }
-  return ariaLabel;
+  return t('@astryx.table.sort.sortedBy', {label, direction: directionLabel});
 }
 
 function getNextDirection(
@@ -227,6 +236,7 @@ function SortHeaderButton<T extends Record<string, unknown>>({
   children: ReactNode;
   configRef: React.RefObject<UseTableSortableConfig>;
 }) {
+  const t = useTranslator();
   const config = configRef.current;
   const sortKey = resolveSortKey(column) ?? '';
   const entryIndex = config.sort.findIndex(e => e.sortKey === sortKey);
@@ -244,7 +254,13 @@ function SortHeaderButton<T extends Record<string, unknown>>({
         ? 'arrowDown'
         : 'arrowsUpDown';
 
-  const ariaLabel = buildAriaLabel(column, direction, rank, config.sort.length);
+  const ariaLabel = buildAriaLabel(
+    t,
+    column,
+    direction,
+    rank,
+    config.sort.length,
+  );
 
   const handleClick = (e: React.MouseEvent | React.KeyboardEvent) => {
     const cfg = configRef.current;

package/src/Table/plugins/tree/index.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+export {useTableTreeData} from './useTableTreeData';
+export type {
+  TableTreeRowMeta,
+  UseTableTreeDataConfig,
+} from './useTableTreeData';
+export {useTableTreeState} from './useTableTreeState';
+export type {
+  UseTableTreeStateConfig,
+  UseTableTreeStateResult,
+} from './useTableTreeState';

package/src/Table/plugins/tree/useTableTreeData-perf.test.tsx

@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useTableTreeData-perf.test.tsx
+ * @input Table, useTableTreeData, useTableTreeState, React testing utilities
+ * @output Performance tests for tree plugin render behavior
+ * @position Test file; validates toggle render efficiency and DOM cost
+ *
+ * The tree plugin uses an external store so a toggle re-renders only the
+ * affected cells — not the whole table body. Note: expanding inserts rows,
+ * which shifts the rowIndex of every row *after* the insertion point (the
+ * row memo comparator includes rowIndex by design), so the guarantee is
+ * scoped to rows before the toggled row.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen, act} from '@testing-library/react';
+import {useMemo} from 'react';
+import userEvent from '@testing-library/user-event';
+import {Table} from '../../Table';
+import type {TableColumn} from '../../types';
+import {useTableTreeData} from './useTableTreeData';
+import {useTableTreeState} from './useTableTreeState';
+
+interface TreeRow extends Record<string, unknown> {
+  id: string;
+  name: string;
+  children?: TreeRow[];
+}
+
+/** 5 roots; the last root has 2 children. */
+const roots: TreeRow[] = [
+  ...Array.from({length: 4}, (_, i) => ({
+    id: `root-${i}`,
+    name: `Root ${i}`,
+  })),
+  {
+    id: 'root-4',
+    name: 'Root 4',
+    children: [
+      {id: 'child-0', name: 'Child 0'},
+      {id: 'child-1', name: 'Child 1'},
+    ],
+  },
+];
+
+function TreeRenderCountTable({
+  renderCounts,
+}: {
+  renderCounts: Record<string, number>;
+}) {
+  const columns = useMemo<TableColumn<TreeRow>[]>(
+    () => [
+      {
+        key: 'name',
+        header: 'Name',
+        renderCell: (item: TreeRow) => {
+          renderCounts[item.id] = (renderCounts[item.id] ?? 0) + 1;
+          return item.name;
+        },
+      },
+    ],
+    [renderCounts],
+  );
+
+  const {visibleData, treeConfig} = useTableTreeState<TreeRow>({
+    data: roots,
+    idKey: 'id',
+  });
+  const tree = useTableTreeData(treeConfig);
+
+  return (
+    <Table data={visibleData} columns={columns} idKey="id" plugins={{tree}} />
+  );
+}
+
+describe('Tree plugin render performance', () => {
+  it('expanding the last root does not re-render preceding rows', async () => {
+    const user = userEvent.setup();
+    const renderCounts: Record<string, number> = {};
+
+    render(<TreeRenderCountTable renderCounts={renderCounts} />);
+
+    const initialCounts = {...renderCounts};
+    expect(Object.keys(initialCounts)).toHaveLength(5);
+
+    await act(async () => {
+      await user.click(screen.getByRole('button', {name: 'Expand row'}));
+    });
+
+    for (let i = 0; i < 4; i++) {
+      expect(renderCounts[`root-${i}`]).toBe(initialCounts[`root-${i}`]);
+    }
+    // The children mounted exactly once.
+    expect(renderCounts['child-0']).toBe(1);
+    expect(renderCounts['child-1']).toBe(1);
+  });
+
+  it('collapsing unmounts the subtree rows entirely', async () => {
+    const user = userEvent.setup();
+    const renderCounts: Record<string, number> = {};
+
+    render(<TreeRenderCountTable renderCounts={renderCounts} />);
+
+    await act(async () => {
+      await user.click(screen.getByRole('button', {name: 'Expand row'}));
+    });
+    expect(screen.getAllByRole('row')).toHaveLength(8); // header + 5 roots + 2 children
+
+    await act(async () => {
+      await user.click(screen.getByRole('button', {name: 'Collapse row'}));
+    });
+    expect(screen.getAllByRole('row')).toHaveLength(6); // header + 5 roots
+  });
+
+  it('adds at most one wrapper, one expander/spacer to the tree column and zero DOM to other columns', () => {
+    const {container} = render(
+      <Table
+        data={
+          [{id: 'a', name: 'a', children: [{id: 'b', name: 'b'}]}] as TreeRow[]
+        }
+        columns={[
+          {key: 'name', header: 'Name'},
+          {key: 'id', header: 'Id'},
+        ]}
+        idKey="id"
+        plugins={{}}
+      />,
+    );
+    const plainSecondCellHTML =
+      container.querySelectorAll('tbody td')[1].innerHTML;
+
+    function DomBudgetTable() {
+      const {visibleData, treeConfig} = useTableTreeState<TreeRow>({
+        data: [{id: 'a', name: 'a', children: [{id: 'b', name: 'b'}]}],
+        idKey: 'id',
+      });
+      const tree = useTableTreeData(treeConfig);
+      return (
+        <Table
+          data={visibleData}
+          columns={[
+            {key: 'name', header: 'Name'},
+            {key: 'id', header: 'Id'},
+          ]}
+          idKey="id"
+          plugins={{tree}}
+        />
+      );
+    }
+    const {container: treeContainer} = render(<DomBudgetTable />);
+    const cells = treeContainer.querySelectorAll('tbody td');
+
+    // Tree column: one flex wrapper containing one expander button + text.
+    const wrapper = cells[0].firstElementChild as HTMLElement;
+    expect(wrapper.tagName).toBe('DIV');
+    expect(wrapper.children).toHaveLength(1);
+    expect(wrapper.querySelector('button')).not.toBeNull();
+
+    // Other columns: byte-identical to the plugin-free render.
+    expect(cells[1].innerHTML).toBe(plainSecondCellHTML);
+  });
+});