@astryxdesign/core 0.1.3 → 0.1.4-canary.01e5b29

package/src/Table/BaseTable.tsx

@@ -225,7 +225,7 @@ function TableRowInner<T extends Record<string, unknown>>({
     rowIndex,
   );
 
-  return (
+  const row = (
     <RowComponent
       key={rowKey}
       ref={rowRenderProps.ref}
@@ -234,6 +234,8 @@ function TableRowInner<T extends Record<string, unknown>>({
       {rowRenderProps.children}
     </RowComponent>
   );
+
+  return row;
 }
 
 /**
@@ -277,11 +279,18 @@ function areRowPropsEqual<T extends Record<string, unknown>>(
     return true;
   }
 
-  // Different object reference - compare values
+  // Different object reference - compare values. This is intentionally a
+  // one-level shallow compare: nested fields rely on reference identity.
   const prevItem = prevProps.item;
   const nextItem = nextProps.item;
   const keys = Object.keys(nextItem);
 
+  // A key deleted from nextItem would never be visited by the loop below,
+  // and the row would keep rendering the removed field's stale value.
+  if (Object.keys(prevItem).length !== keys.length) {
+    return false;
+  }
+
   for (const key of keys) {
     if (prevItem[key] !== nextItem[key]) {
       return false;
@@ -363,9 +372,13 @@ function BaseTableInner<T extends Record<string, unknown>>({
   const headerCells = resolvedColumns.map((col, columnIndex) => {
     const headerContent = col.header ?? col.key;
 
-    // Build initial htmlProps with column alignment if specified
+    // Build initial htmlProps with column alignment if specified.
+    // `scope: 'col'` is the default so every column header associates its
+    // data cells with the correct column for screen readers; a plugin's
+    // transformHeaderCell can override it via htmlProps.scope.
     const initialHeaderHtmlProps: Record<string, unknown> = {
       'data-column-key': col.key,
+      scope: 'col',
     };
     if (col.align) {
       initialHeaderHtmlProps.style = {textAlign: col.align};

package/src/Table/Table.test.tsx

@@ -15,6 +15,9 @@ import {BaseTable} from './BaseTable';
 import {Table} from './Table';
 import {TableRow} from './TableRow';
 import {TableCell} from './TableCell';
+import {TableHeader} from './TableHeader';
+import {TableBody} from './TableBody';
+import {TableFooter} from './TableFooter';
 import {
   proportional,
   pixel,
@@ -229,6 +232,34 @@ describe('BaseTable', () => {
     expect(headers[2]).toHaveTextContent('Email');
   });
 
+  it('renders every column header with scope="col"', () => {
+    render(<BaseTable data={users} columns={columns} />);
+    const headers = screen.getAllByRole('columnheader');
+    expect(headers).toHaveLength(3);
+    for (const header of headers) {
+      expect(header).toHaveAttribute('scope', 'col');
+    }
+  });
+
+  it('lets a consumer override scope via header html props', () => {
+    // A `<th scope="row">` maps to the `rowheader` role, so query the DOM
+    // directly to assert the attribute regardless of the resolved ARIA role.
+    const plugin: TablePlugin<User> = {
+      transformHeaderCell: (props, column) =>
+        column.key === 'name'
+          ? {...props, htmlProps: {...props.htmlProps, scope: 'row'}}
+          : props,
+    };
+    const {container} = render(
+      <BaseTable data={users} columns={columns} plugins={[plugin]} />,
+    );
+    const headerCells = container.querySelectorAll('thead th');
+    // columns fixture order: name, age, email — plugin overrides name → 'row'
+    expect(headerCells[0]).toHaveAttribute('scope', 'row');
+    expect(headerCells[1]).toHaveAttribute('scope', 'col');
+    expect(headerCells[2]).toHaveAttribute('scope', 'col');
+  });
+
   it('renders data cells', () => {
     render(<BaseTable data={users} columns={columns} />);
     const cells = screen.getAllByRole('cell');
@@ -617,6 +648,29 @@ describe('BaseTable', () => {
 // =============================================================================
 
 describe('Table', () => {
+  it('clears a cell when the field is removed from the row object (#3595)', () => {
+    const cols: TableColumn<Record<string, unknown>>[] = [
+      {key: 'name', header: 'Name'},
+      {key: 'status', header: 'Status'},
+    ];
+    const {rerender} = render(
+      <Table
+        data={[{id: '1', name: 'Alice', status: 'active'}]}
+        columns={cols}
+        idKey="id"
+      />,
+    );
+    expect(screen.getByText('active')).toBeInTheDocument();
+
+    // Clearing a field by omitting it (optimistic update / server response)
+    // must re-render the row — the memo previously only compared the keys of
+    // the NEW item, so the deleted field's stale value kept rendering.
+    rerender(
+      <Table data={[{id: '1', name: 'Alice'}]} columns={cols} idKey="id" />,
+    );
+    expect(screen.queryByText('active')).not.toBeInTheDocument();
+  });
+
   it('renders a table with correct structure', () => {
     render(<Table data={users} columns={columns} />);
     expect(screen.getByRole('table')).toBeInTheDocument();
@@ -1232,4 +1286,37 @@ describe('emptyState', () => {
     expect(screen.getByText('Name')).toBeInTheDocument();
     expect(screen.getByText('Age')).toBeInTheDocument();
   });
+
+  describe('table section rest forwarding', () => {
+    it('forwards data-testid and id to the tbody, thead, and tfoot', () => {
+      const {container} = render(
+        <table>
+          <TableHeader data-testid="thead" id="head-1">
+            <tr>
+              <th>H</th>
+            </tr>
+          </TableHeader>
+          <TableBody data-testid="tbody" id="body-1">
+            <tr>
+              <td>B</td>
+            </tr>
+          </TableBody>
+          <TableFooter data-testid="tfoot" id="foot-1">
+            <tr>
+              <td>F</td>
+            </tr>
+          </TableFooter>
+        </table>,
+      );
+      const thead = container.querySelector('thead')!;
+      const tbody = container.querySelector('tbody')!;
+      const tfoot = container.querySelector('tfoot')!;
+      expect(thead).toHaveAttribute('data-testid', 'thead');
+      expect(thead).toHaveAttribute('id', 'head-1');
+      expect(tbody).toHaveAttribute('data-testid', 'tbody');
+      expect(tbody).toHaveAttribute('id', 'body-1');
+      expect(tfoot).toHaveAttribute('data-testid', 'tfoot');
+      expect(tfoot).toHaveAttribute('id', 'foot-1');
+    });
+  });
 });

package/src/Table/TableBody.tsx

@@ -13,11 +13,24 @@ export interface TableBodyProps extends BaseProps<HTMLTableSectionElement> {
   children: ReactNode;
 }
 
-export function TableBody({ref, children, xstyle}: TableBodyProps) {
+export function TableBody({
+  ref,
+  children,
+  xstyle,
+  className,
+  style,
+  ...rest
+}: TableBodyProps) {
   return (
     <tbody
       ref={ref}
-      {...mergeProps(themeProps('table-body'), stylex.props(xstyle))}>
+      {...mergeProps(
+        themeProps('table-body'),
+        stylex.props(xstyle),
+        className,
+        style,
+      )}
+      {...rest}>
       {children}
     </tbody>
   );

package/src/Table/TableCell.tsx

@@ -87,6 +87,62 @@ const densityStyles = stylex.create({
   },
 });
 
+// When a cell owns a context menu, its padding moves from the `<td>` onto the
+// right-click trigger wrapper so the *entire* cell (padding included) opens the
+// menu. Without this, right-clicking the padding ring near a cell edge falls
+// through to the browser's native menu. Paired with `contextMenuCellStyles` on
+// the `<td>` (font/box-sizing only — no padding).
+const densityTextStyles = stylex.create({
+  compact: {
+    fontSize: typeScaleVars['--text-body-size'],
+    boxSizing: 'border-box',
+  },
+  balanced: {
+    fontSize: typeScaleVars['--text-body-size'],
+    boxSizing: 'border-box',
+  },
+  spacious: {
+    fontSize: typeScaleVars['--text-body-size'],
+    boxSizing: 'border-box',
+  },
+});
+
+const densityPaddingStyles = stylex.create({
+  compact: {
+    paddingBlock: spacingVars['--spacing-1'],
+    paddingInline: spacingVars['--spacing-2'],
+  },
+  balanced: {
+    paddingBlock: spacingVars['--spacing-2'],
+    paddingInline: spacingVars['--spacing-3'],
+  },
+  spacious: {
+    paddingBlock: spacingVars['--spacing-3'],
+    paddingInline: spacingVars['--spacing-4'],
+  },
+});
+
+// The trigger wrapper fills the whole cell (a `<td>` child with height:100%
+// stretches to the row height) so a right-click anywhere in the cell opens the
+// menu. It carries the density padding relocated off the `<td>`.
+const triggerFillStyles = stylex.create({
+  fill: {
+    display: 'block',
+    boxSizing: 'border-box',
+    blockSize: '100%',
+    inlineSize: '100%',
+  },
+});
+
+// `height:100%` on the `<td>` is the CSS trick that lets a block child resolve
+// its own `height:100%` against the row height — so the trigger fills the cell
+// vertically (top/bottom padding included) and is fully right-clickable.
+const contextMenuCellStyles = stylex.create({
+  cell: {
+    blockSize: '100%',
+  },
+});
+
 const dividerRowStyles = stylex.create({
   cell: {
     borderBottomWidth: {
@@ -151,22 +207,45 @@ export function TableCell({
 }: TableCellProps) {
   const ctx = useTableContext();
 
-  // Standalone (no table context) renders plain, with no density/divider styles.
+  const hasContextMenu =
+    typeof contextMenuActions === 'function' ||
+    (Array.isArray(contextMenuActions) && contextMenuActions.length > 0);
+
+  // When the cell owns a context menu, its density padding is relocated onto
+  // the right-click trigger wrapper (see `content` below) so the entire cell —
+  // padding included — opens the menu. Otherwise padding lives on the `<td>`.
   const cellStyles: StyleXStyles[] = ctx
     ? [
-        densityStyles[ctx.density],
-        ctx.textOverflow === 'truncate'
-          ? overflowStyles.cell
-          : wrapStyles.cell,
+        hasContextMenu
+          ? densityTextStyles[ctx.density]
+          : densityStyles[ctx.density],
+        ctx.textOverflow === 'truncate' ? overflowStyles.cell : wrapStyles.cell,
         containerEdgeStyles[ctx.density],
         verticalAlignStyles[ctx.verticalAlign],
-        ...buildDividerStyles(ctx, dividerRowStyles.cell, dividerColumnStyles.cell),
+        ...buildDividerStyles(
+          ctx,
+          dividerRowStyles.cell,
+          dividerColumnStyles.cell,
+        ),
+        ...(hasContextMenu ? [contextMenuCellStyles.cell] : []),
       ]
     : [];
 
   // The cell owns the context-menu wrapper so it controls how the menu
-  // interacts with its padding / content. No-op when no actions.
-  const content = wrapInTableContextMenu(children, contextMenuActions);
+  // interacts with its padding / content. No-op when no actions. When actions
+  // exist we make the trigger fill the cell and carry the density padding so a
+  // right-click anywhere in the cell (including the padding ring) opens it.
+  const triggerXstyle =
+    hasContextMenu && ctx
+      ? [triggerFillStyles.fill, densityPaddingStyles[ctx.density]]
+      : hasContextMenu
+        ? triggerFillStyles.fill
+        : undefined;
+  const content = wrapInTableContextMenu(
+    children,
+    contextMenuActions,
+    triggerXstyle,
+  );
 
   return (
     <td

package/src/Table/TableFooter.tsx

@@ -13,11 +13,24 @@ export interface TableFooterProps extends BaseProps<HTMLTableSectionElement> {
   children: ReactNode;
 }
 
-export function TableFooter({ref, children, xstyle}: TableFooterProps) {
+export function TableFooter({
+  ref,
+  children,
+  xstyle,
+  className,
+  style,
+  ...rest
+}: TableFooterProps) {
   return (
     <tfoot
       ref={ref}
-      {...mergeProps(themeProps('table-footer'), stylex.props(xstyle))}>
+      {...mergeProps(
+        themeProps('table-footer'),
+        stylex.props(xstyle),
+        className,
+        style,
+      )}
+      {...rest}>
       {children}
     </tfoot>
   );

package/src/Table/TableHeader.tsx

@@ -13,11 +13,24 @@ export interface TableHeaderProps extends BaseProps<HTMLTableSectionElement> {
   children: ReactNode;
 }
 
-export function TableHeader({ref, children, xstyle}: TableHeaderProps) {
+export function TableHeader({
+  ref,
+  children,
+  xstyle,
+  className,
+  style,
+  ...rest
+}: TableHeaderProps) {
   return (
     <thead
       ref={ref}
-      {...mergeProps(themeProps('table-header'), stylex.props(xstyle))}>
+      {...mergeProps(
+        themeProps('table-header'),
+        stylex.props(xstyle),
+        className,
+        style,
+      )}
+      {...rest}>
       {children}
     </thead>
   );

package/src/Table/index.ts

@@ -26,6 +26,10 @@ export {useTableColumnSettings} from './plugins/columnSettings';
 export {useTableColumnSettingsState} from './plugins/columnSettings';
 export {useTableColumnResize} from './plugins/columnResize';
 export {useTableStickyColumns} from './plugins/stickyColumns';
+export {
+  useTableRowExpansion,
+  useTableRowExpansionState,
+} from './plugins/rowExpansion';
 export {resolveContextActions} from './tableContextMenu';
 export {
   useTableFiltering,
@@ -97,6 +101,7 @@ export type {
 } from './plugins/columnSettings';
 export type {UseTableColumnResizeConfig} from './plugins/columnResize';
 export type {UseTableStickyColumnsConfig} from './plugins/stickyColumns';
+export type {UseTableRowExpansionConfig} from './plugins/rowExpansion';
 export type {
   UseTableFilteringConfig,
   TableFilterState,

package/src/Table/plugins/columnResize/useTableColumnResize.test.tsx

@@ -551,6 +551,19 @@ describe('useTableColumnResize', () => {
       expect(handle).toHaveAttribute('aria-valuenow', '200');
     });
 
+    it('handle has a numeric aria-valuenow on initial render (before any width is measured)', () => {
+      // A focusable role="separator" requires aria-valuenow per the ARIA spec.
+      // Before the column width has been measured there is no override width, so
+      // the handle must fall back to a defined numeric value (the column
+      // minWidth) rather than omitting the attribute.
+      render(<ResizeTable minWidth={80} />);
+      const handle = getResizeHandles()[0];
+      const valueNow = handle.getAttribute('aria-valuenow');
+      expect(valueNow).not.toBeNull();
+      expect(Number.isNaN(Number(valueNow))).toBe(false);
+      expect(valueNow).toBe('80');
+    });
+
     it('handle has aria-label with column header text', () => {
       render(<ResizeTable />);
       const handle = getResizeHandles()[0];

package/src/Table/plugins/columnResize/useTableColumnResize.tsx

@@ -676,7 +676,9 @@ function ResizeHandle({
     <div
       role="separator"
       aria-orientation="vertical"
-      aria-valuenow={currentWidth ?? undefined}
+      // A focusable role="separator" requires a numeric aria-valuenow, so fall
+      // back to the column's minWidth before the width has been measured.
+      aria-valuenow={currentWidth ?? minWidth}
       aria-valuemin={minWidth}
       aria-valuemax={maxWidth === Infinity ? undefined : maxWidth}
       aria-label={ariaLabel}

package/src/Table/plugins/pagination/paginateData.ts

@@ -38,6 +38,10 @@ export function paginateData<T>(
   const size = Number.isFinite(pageSize)
     ? Math.max(1, Math.floor(pageSize))
     : 10;
-  const start = (page - 1) * size;
+  // page needs the same coercion: a negative start index makes Array.slice
+  // count from the END of the data (page -1 returns the tail dressed up as a
+  // page), and a fractional page returns a slice straddling two pages.
+  const p = Number.isFinite(page) ? Math.max(1, Math.floor(page)) : 1;
+  const start = (p - 1) * size;
   return data.slice(start, start + size);
 }

package/src/Table/plugins/pagination/useTablePagination.test.tsx

@@ -132,6 +132,19 @@ describe('paginateData', () => {
     expect(paginateData([], 1, 10)).toEqual([]);
   });
 
+  it('clamps invalid page numbers to the first page (#3593)', () => {
+    const data = generateItems(30);
+    // Negative pages previously fed a negative index to Array.slice, which
+    // counts from the END of the data — the tail dressed up as a page.
+    expect(paginateData(data, -1, 10)[0].id).toBe('1');
+    expect(paginateData(data, 0, 10)[0].id).toBe('1');
+    expect(paginateData(data, NaN, 10)[0].id).toBe('1');
+    // Fractional pages floor to the containing page instead of straddling two.
+    expect(paginateData(data, 1.5, 10).map(i => i.id)).toEqual(
+      paginateData(data, 1, 10).map(i => i.id),
+    );
+  });
+
   it('returns empty array when page exceeds data', () => {
     const data = generateItems(10);
     expect(paginateData(data, 5, 10)).toEqual([]);

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

@@ -0,0 +1,7 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+export {
+  useTableRowExpansion,
+  useTableRowExpansionState,
+} from './useTableRowExpansion';
+export type {UseTableRowExpansionConfig} from './useTableRowExpansion';

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

@@ -0,0 +1,155 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {useState} from 'react';
+import {Table} from '../../Table';
+import type {TableColumn} from '../../types';
+import {
+  useTableRowExpansion,
+  useTableRowExpansionState,
+} from './useTableRowExpansion';
+
+// popover mock for context-menu tests
+beforeEach(() => {
+  HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+    this.setAttribute('popover-open', '');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'open'});
+    this.dispatchEvent(event);
+  });
+  HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+    this.removeAttribute('popover-open');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'closed'});
+    this.dispatchEvent(event);
+  });
+  const originalMatches = HTMLElement.prototype.matches;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (HTMLElement.prototype as any).matches = function (
+    selector: string,
+  ): boolean {
+    if (selector === ':popover-open') {
+      return this.hasAttribute('popover-open');
+    }
+    return originalMatches.call(this, selector);
+  };
+});
+
+interface TreeItem extends Record<string, unknown> {
+  id: string;
+  name: string;
+  children: TreeItem[];
+}
+
+const treeData: TreeItem[] = [
+  {
+    id: 'a',
+    name: 'Folder A',
+    children: [
+      {id: 'a1', name: 'File A1', children: []},
+      {id: 'a2', name: 'File A2', children: []},
+    ],
+  },
+  {
+    id: 'b',
+    name: 'Folder B',
+    children: [{id: 'b1', name: 'File B1', children: []}],
+  },
+  {id: 'c', name: 'Leaf C', children: []},
+];
+
+const columns: TableColumn<TreeItem>[] = [{key: 'name', header: 'Name'}];
+
+const EMPTY_KEYS = new Set<string>();
+
+function Harness({
+  initialExpanded = EMPTY_KEYS,
+}: {
+  initialExpanded?: Set<string>;
+}) {
+  const [expandedKeys, setExpandedKeys] = useState(initialExpanded);
+  const {data, expansionConfig} = useTableRowExpansionState<TreeItem>({
+    baseData: treeData,
+    getChildren: item => item.children,
+    getRowKey: item => item.id,
+    expandedKeys,
+    setExpandedKeys,
+  });
+  const expansion = useTableRowExpansion(expansionConfig);
+  return (
+    <Table data={data} columns={columns} idKey="id" plugins={{expansion}} />
+  );
+}
+
+describe('useTableRowExpansion', () => {
+  it('renders a chevron button for expandable rows', () => {
+    render(<Harness />);
+    const buttons = screen.getAllByRole('button', {name: /expand row/i});
+    // Folder A and Folder B are expandable (top-level with children)
+    expect(buttons.length).toBe(2);
+  });
+
+  it('shows child rows when expanded', () => {
+    render(<Harness initialExpanded={new Set(['a'])} />);
+    expect(screen.getByText('File A1')).toBeInTheDocument();
+    expect(screen.getByText('File A2')).toBeInTheDocument();
+  });
+
+  it('hides child rows when collapsed', () => {
+    render(<Harness />);
+    expect(screen.queryByText('File A1')).not.toBeInTheDocument();
+  });
+
+  it('toggles expansion on chevron click', () => {
+    render(<Harness />);
+    expect(screen.queryByText('File A1')).not.toBeInTheDocument();
+    fireEvent.click(screen.getAllByRole('button', {name: /expand row/i})[0]);
+    expect(screen.getByText('File A1')).toBeInTheDocument();
+  });
+
+  it('contributes a context-menu action on expandable rows', () => {
+    render(<Harness />);
+    fireEvent.contextMenu(screen.getByText('Folder A'));
+    const items = screen.getAllByRole('menuitem', {
+      name: /expand row/i,
+      hidden: true,
+    });
+    expect(items.length).toBeGreaterThan(0);
+  });
+
+  it('does not show chevron for leaf nodes', () => {
+    render(<Harness />);
+    // Leaf C has no children
+    expect(screen.getByText('Leaf C')).toBeInTheDocument();
+    // only 2 expand buttons (Folder A, Folder B), not 3
+    expect(
+      screen.getAllByRole('button', {name: /expand row|collapse row/i}).length,
+    ).toBe(2);
+  });
+
+  it('renders an expand-all toggle in the header', () => {
+    render(<Harness />);
+    expect(
+      screen.getByRole('button', {name: /expand all rows/i}),
+    ).toBeInTheDocument();
+  });
+
+  it('expand-all toggle expands every expandable row', () => {
+    render(<Harness />);
+    expect(screen.queryByText('File A1')).not.toBeInTheDocument();
+    fireEvent.click(screen.getByRole('button', {name: /expand all rows/i}));
+    // Both folders' children become visible.
+    expect(screen.getByText('File A1')).toBeInTheDocument();
+    expect(screen.getByText('File A2')).toBeInTheDocument();
+    expect(screen.getByText('File B1')).toBeInTheDocument();
+  });
+
+  it('collapse-all toggle collapses every row', () => {
+    render(<Harness initialExpanded={new Set(['a', 'b'])} />);
+    expect(screen.getByText('File A1')).toBeInTheDocument();
+    fireEvent.click(screen.getByRole('button', {name: /collapse all rows/i}));
+    expect(screen.queryByText('File A1')).not.toBeInTheDocument();
+    expect(screen.queryByText('File B1')).not.toBeInTheDocument();
+  });
+});