@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

package/src/TabList/TabList.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TabList} from './TabList';
 import {Tab} from './Tab';
@@ -702,3 +702,187 @@ describe('TabMenu', () => {
     expect(reportsItem).not.toHaveAttribute('aria-current');
   });
 });
+
+describe('TabMenu keyboard navigation (roving tabindex)', () => {
+  const menuOptions = [
+    {value: 'analytics', label: 'Analytics'},
+    {value: 'reports', label: 'Reports'},
+  ];
+
+  it('exposes the overflow menu as a single Tab stop (one item tabbable, rest -1)', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+
+    const analytics = screen.getByRole('menuitem', {
+      name: 'Analytics',
+      hidden: true,
+    });
+    const reports = screen.getByRole('menuitem', {
+      name: 'Reports',
+      hidden: true,
+    });
+
+    // Exactly one menu item is in the Tab sequence; arrow keys reach the rest.
+    expect(analytics).toHaveAttribute('tabindex', '0');
+    expect(reports).toHaveAttribute('tabindex', '-1');
+
+    const tabbable = [analytics, reports].filter(
+      el => el.getAttribute('tabindex') === '0',
+    );
+    expect(tabbable).toHaveLength(1);
+  });
+
+  it('moves focus between items with ArrowDown and ArrowUp', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+    const analytics = screen.getByRole('menuitem', {
+      name: 'Analytics',
+      hidden: true,
+    });
+    const reports = screen.getByRole('menuitem', {
+      name: 'Reports',
+      hidden: true,
+    });
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(analytics).toHaveFocus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(reports).toHaveFocus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowUp'});
+    expect(analytics).toHaveFocus();
+  });
+
+  it('moves the roving tab stop with arrow navigation', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+    const analytics = screen.getByRole('menuitem', {
+      name: 'Analytics',
+      hidden: true,
+    });
+    const reports = screen.getByRole('menuitem', {
+      name: 'Reports',
+      hidden: true,
+    });
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'}); // focus analytics
+    fireEvent.keyDown(menu, {key: 'ArrowDown'}); // focus reports
+
+    // The tab stop follows focus, so it is still a single stop after moving.
+    expect(reports).toHaveAttribute('tabindex', '0');
+    expect(analytics).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('jumps to first and last item with Home and End', async () => {
+    const user = userEvent.setup();
+    const options = [
+      {value: 'analytics', label: 'Analytics'},
+      {value: 'reports', label: 'Reports'},
+      {value: 'exports', label: 'Exports'},
+    ];
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={options} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+    const analytics = screen.getByRole('menuitem', {
+      name: 'Analytics',
+      hidden: true,
+    });
+    const exports = screen.getByRole('menuitem', {
+      name: 'Exports',
+      hidden: true,
+    });
+
+    fireEvent.keyDown(menu, {key: 'End'});
+    expect(exports).toHaveFocus();
+
+    fireEvent.keyDown(menu, {key: 'Home'});
+    expect(analytics).toHaveFocus();
+  });
+
+  it('selects an item with Enter and calls onChange', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <TabList value="home" onChange={handleChange}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const analytics = screen.getByRole('menuitem', {
+      name: 'Analytics',
+      hidden: true,
+    });
+    analytics.focus();
+    fireEvent.keyDown(analytics, {key: 'Enter'});
+
+    expect(handleChange).toHaveBeenCalledWith('analytics');
+  });
+
+  it('closes the menu when Tab is pressed inside it (APG menu-button)', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+
+    const hidePopover = vi.mocked(HTMLElement.prototype.hidePopover);
+    hidePopover.mockClear();
+    fireEvent.keyDown(menu, {key: 'Tab'});
+    expect(hidePopover).toHaveBeenCalled();
+  });
+
+  it('closes the menu when Escape is pressed', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+
+    const hidePopover = vi.mocked(HTMLElement.prototype.hidePopover);
+    hidePopover.mockClear();
+    fireEvent.keyDown(menu, {key: 'Escape'});
+    expect(hidePopover).toHaveBeenCalled();
+  });
+});

package/src/TabList/TabMenu.tsx

@@ -16,7 +16,7 @@
  * - /packages/cli/templates/blocks/components/TabList/ (showcase blocks)
  */
 
-import React, {useCallback, useId, type ReactNode} from 'react';
+import React, {useCallback, useId, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Icon} from '../Icon';
 import {renderIconSlot, type IconType} from '../Icon';
@@ -262,6 +262,7 @@ export function TabMenu({
 }: TabMenuProps) {
   const tabListCtx = useTabListContext();
   const menuId = useId();
+  const buttonRef = useRef<HTMLButtonElement>(null);
 
   const popover = usePopover({
     hasLightDismiss: true,
@@ -270,20 +271,50 @@ export function TabMenu({
     // The popup's own role="menu" is the exposed semantics; a modal dialog
     // wrapper would announce an unnamed dialog around the menu.
     role: 'none',
+    // Return focus to the trigger when the menu closes (Escape, Tab, select,
+    // or light dismiss) so keyboard focus is never dropped to <body>.
+    onHide: useCallback(() => {
+      buttonRef.current?.focus();
+    }, []),
   });
 
-  const {listRef, handleKeyDown: handleListKeyDown} =
-    useListFocus<HTMLDivElement>({
-      onEscape: () => popover.hide(),
-    });
+  // The overflow menu is a composite widget: a single roving tab stop with
+  // arrow-key navigation between items, per the APG menu pattern. The hook owns
+  // item tabindex — items render tabIndex={-1} and exactly one is promoted to 0.
+  const {
+    listRef,
+    handleKeyDown: handleListKeyDown,
+    handleFocus,
+    focusFirst,
+  } = useListFocus<HTMLDivElement>({
+    hasRovingTabIndex: true,
+    onEscape: () => popover.hide(),
+  });
 
   const handleToggle = useCallback(() => {
     if (popover.isOpen) {
       popover.hide();
     } else {
       popover.show();
+      // Move focus into the menu on open so arrow navigation works and the
+      // roving tab stop lands on a real item (APG menu-button focus-on-open).
+      requestAnimationFrame(() => focusFirst());
     }
-  }, [popover]);
+  }, [popover, focusFirst]);
+
+  const handleMenuKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      // APG menu-button: Tab leaves the menu rather than walking its items.
+      // Close and let onHide return focus to the trigger, from which the
+      // browser's default Tab continues to the next element.
+      if (e.key === 'Tab') {
+        popover.hide();
+        return;
+      }
+      handleListKeyDown(e);
+    },
+    [handleListKeyDown, popover],
+  );
 
   const selectedOption = options.find(o => o.value === tabListCtx.value);
   const triggerLabel = selectedOption?.label ?? label;
@@ -299,7 +330,11 @@ export function TabMenu({
     [tabListCtx, popover],
   );
 
-  const setButtonRef = mergeRefs<HTMLButtonElement>(popover.triggerRef, ref);
+  const setButtonRef = mergeRefs<HTMLButtonElement>(
+    popover.triggerRef,
+    buttonRef,
+    ref,
+  );
 
   return (
     <>
@@ -357,7 +392,8 @@ export function TabMenu({
           id={menuId}
           role="menu"
           aria-label={label}
-          onKeyDown={handleListKeyDown}
+          onKeyDown={handleMenuKeyDown}
+          onFocus={handleFocus}
           {...mergeProps(
             themeProps('tab-menu-dropdown'),
             stylex.props(styles.dropdown),
@@ -371,7 +407,7 @@ export function TabMenu({
               <div
                 key={option.value}
                 role="menuitem"
-                tabIndex={0}
+                tabIndex={-1}
                 aria-current={isSelected ? 'true' : undefined}
                 onClick={() => handleSelect(option.value)}
                 onKeyDown={e => {

package/src/Table/BaseTable.tsx

@@ -279,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;
@@ -365,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.doc.mjs

@@ -25,6 +25,11 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-base-table'},
+      {className: 'astryx-table'},
+      {className: 'astryx-table-scroll-wrapper'},
+      {className: 'astryx-table-header'},
+      {className: 'astryx-table-body'},
+      {className: 'astryx-table-footer'},
       {className: 'astryx-table-row'},
       {className: 'astryx-table-cell'},
       {className: 'astryx-table-header-cell'},
@@ -40,7 +45,7 @@ export const docs = {
     {
       name: 'columns',
       type: 'TableColumn<T>[]',
-      description: 'Column definitions: each column has {key, header, width?, align?, renderCell?}. The `header` field sets the column heading text. If omitted, columns are auto-generated from data object keys.',
+      description: 'Column definitions: each column has {key, header, width?, align?, renderCell?}. The `header` field sets the column heading text. If omitted, columns are auto-generated from data object keys. The `width` field is typed as `ColumnWidth` (not a number) — use `proportional(n)` or `pixel(n)` helpers imported from `@astryxdesign/core/Table`. Example: `width: pixel(120)` for 120px fixed, `width: proportional(1)` for flex distribution.',
     },
     {
       name: 'idKey',

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/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,7 @@ export {useTableColumnSettings} from './plugins/columnSettings';
 export {useTableColumnSettingsState} from './plugins/columnSettings';
 export {useTableColumnResize} from './plugins/columnResize';
 export {useTableStickyColumns} from './plugins/stickyColumns';
+export {useTableGroupedRows} from './plugins/groupedRows';
 export {
   useTableRowExpansion,
   useTableRowExpansionState,
@@ -102,6 +103,10 @@ export type {
 export type {UseTableColumnResizeConfig} from './plugins/columnResize';
 export type {UseTableStickyColumnsConfig} from './plugins/stickyColumns';
 export type {UseTableRowExpansionConfig} from './plugins/rowExpansion';
+export type {
+  UseTableGroupedRowsConfig,
+  UseTableGroupedRowsResult,
+} from './plugins/groupedRows';
 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/groupedRows/index.ts

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