@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

package/src/TabList/TabList.tsx

@@ -515,6 +515,10 @@ export function TabList({
     revealSelectedTabRef.current = revealSelectedTab;
   }, [revealSelectedTab]);
 
+  // The tab whose focus revealed it (see `handleRootFocus`), while it keeps
+  // focus.
+  const focusRevealedValueRef = useRef<string | null>(null);
+
   // The tab you are on has to be visible. Selection can move without focus —
   // on mount, or when the host sets `value` itself — and neither scrolls the
   // strip the way clicking or arrowing to a tab does. The check is what makes
@@ -525,6 +529,14 @@ export function TabList({
       return;
     }
     revealedValueRef.current = value;
+    if (value != null && focusRevealedValueRef.current === value) {
+      // A press or an arrow focused this tab first, and focusing it revealed
+      // it. Measuring now would force the new selection's style and layout
+      // inside the press, before it can paint. The next frame lays them out
+      // anyway, so finish there: the selected weight can still widen the tab.
+      const frame = requestAnimationFrame(() => revealSelectedTabRef.current());
+      return () => cancelAnimationFrame(frame);
+    }
     revealSelectedTabRef.current();
   }, [value]);
 
@@ -595,7 +607,9 @@ export function TabList({
       // The browser scrolls a focused element into view only when it is
       // entirely outside the scrollport, so arrowing onto a half-visible stop
       // leaves it cut off under the fade. Finish the job it started.
-      revealStop(e.target.closest(TAB_STOP_SELECTOR));
+      const stop = e.target.closest<HTMLElement>(TAB_STOP_SELECTOR);
+      revealStop(stop);
+      focusRevealedValueRef.current = stop?.dataset.tabValue ?? null;
     },
     [onFocusProp, onHintFocus, handleFocus, revealStop],
   );
@@ -603,6 +617,7 @@ export function TabList({
   const handleRootBlur = useCallback(
     (e: React.FocusEvent<HTMLElement>) => {
       onBlurProp?.(e);
+      focusRevealedValueRef.current = null;
       if (e.defaultPrevented) {
         return;
       }

package/src/TabList/__tests__/TabPressPointer.interaction.browser.spec.ts

@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TabPressPointer.interaction.browser.spec.ts
+ * @input Uses @playwright/test and the interaction harness (a built
+ *   Storybook)
+ * @output Proves a Tab's hover and press layer under a fine and a coarse
+ *   primary pointer
+ * @position Interaction proof for packages/core/src/TabList/Tab.tsx
+ *
+ * Tab's press layer has a hover branch and a coarse-pointer rule, which
+ * StyleX makes exclusive. The outcome on every pointer: a fine pointer
+ * paints the hover, then a pressed overlay that differs from it; under a
+ * coarse pointer a finger's press paints as an image (`data-astryx-press`),
+ * and the colour layer stays transparent while the tab is `:active`.
+ * Chromium only: it holds a finger, and forces `:active`, through the
+ * DevTools protocol.
+ */
+
+import {expect, test, type CDPSession, type Page} from '@playwright/test';
+import {openStory, withStorybook} from '@astryxdesign/interaction-harness';
+
+const storybook = withStorybook(test);
+
+const TRANSPARENT = 'rgba(0, 0, 0, 0)';
+
+/** The "Projects" tab: not the story's current one. */
+function projectsTab(page: Page) {
+  return page.locator('button', {hasText: 'Projects'}).first();
+}
+
+/** The tab's colour layer (its first aria-hidden span) and the pointer. */
+async function tabState(page: Page): Promise<{
+  colour: string;
+  image: string;
+  press: string | null;
+  coarse: boolean;
+  hover: boolean;
+}> {
+  return projectsTab(page).evaluate(element => {
+    const layer = element.querySelector('span[aria-hidden="true"]');
+    const style = layer == null ? null : getComputedStyle(layer);
+    return {
+      colour: style?.backgroundColor ?? '',
+      image: style?.backgroundImage ?? '',
+      press: element.getAttribute('data-astryx-press'),
+      coarse: matchMedia('(pointer: coarse)').matches,
+      hover: matchMedia('(hover: hover)').matches,
+    };
+  });
+}
+
+/** The layer's colour once its transition has landed (three equal reads). */
+async function settledColour(page: Page): Promise<string> {
+  let last = '';
+  let same = 0;
+  for (let read = 0; read < 60 && same < 3; read++) {
+    const colour = (await tabState(page)).colour;
+    same = colour === last ? same + 1 : 1;
+    last = colour;
+    await page.waitForTimeout(50);
+  }
+  return last;
+}
+
+/** The tab's centre, in page coordinates. */
+async function tabCentre(page: Page): Promise<{x: number; y: number}> {
+  const box = await projectsTab(page).boundingBox();
+  if (box == null) {
+    throw new Error('the Projects tab has no box');
+  }
+  return {x: box.x + box.width / 2, y: box.y + box.height / 2};
+}
+
+/** A finger held on the tab's centre; returns the lift. */
+async function holdFinger(
+  page: Page,
+  cdp: CDPSession,
+): Promise<() => Promise<void>> {
+  await cdp.send('Input.dispatchTouchEvent', {
+    type: 'touchStart',
+    touchPoints: [await tabCentre(page)],
+  });
+  return async () => {
+    await cdp.send('Input.dispatchTouchEvent', {
+      type: 'touchEnd',
+      touchPoints: [],
+    });
+  };
+}
+
+/** Puts the tab in `:active` (or out of it) through the DevTools protocol. */
+async function forceActive(cdp: CDPSession, isActive: boolean): Promise<void> {
+  await cdp.send('DOM.enable');
+  await cdp.send('CSS.enable');
+  const {root} = await cdp.send('DOM.getDocument', {depth: -1});
+  const {nodeIds} = await cdp.send('DOM.querySelectorAll', {
+    nodeId: root.nodeId,
+    selector: 'button',
+  });
+  for (const nodeId of nodeIds) {
+    const {outerHTML} = await cdp.send('DOM.getOuterHTML', {nodeId});
+    if (outerHTML.includes('Projects')) {
+      await cdp.send('CSS.forcePseudoState', {
+        nodeId,
+        forcedPseudoClasses: isActive ? ['active'] : [],
+      });
+      return;
+    }
+  }
+  throw new Error('the Projects tab has no node');
+}
+
+test.describe('Tab press layer by pointer', () => {
+  test.skip(
+    ({browserName}) => browserName !== 'chromium',
+    'Chromium holds a finger and forces :active through the DevTools protocol',
+  );
+
+  test.describe('fine pointer with hover', () => {
+    test.use({isMobile: false, hasTouch: false});
+    test('paints the hover, then a pressed overlay that differs from it', async ({
+      page,
+    }) => {
+      await openStory(page, storybook(), 'core-tablist--default');
+      await projectsTab(page).hover();
+      const state = await tabState(page);
+      expect(state.coarse).toBe(false);
+      expect(state.hover).toBe(true);
+      await expect
+        .poll(async () => (await tabState(page)).colour)
+        .not.toBe(TRANSPARENT);
+      const hovered = await settledColour(page);
+      await page.mouse.down();
+      // The pressed overlay is its own colour, not the hover paint held on.
+      await expect
+        .poll(async () => (await tabState(page)).colour)
+        .not.toBe(hovered);
+      expect(await settledColour(page)).not.toBe(hovered);
+      await page.mouse.up();
+    });
+  });
+
+  test("coarse pointer: a finger's press paints as an image, and the colour layer stays transparent while the tab is :active", async ({
+    page,
+  }) => {
+    await openStory(page, storybook(), 'core-tablist--default');
+    const cdp = await page.context().newCDPSession(page);
+    expect((await tabState(page)).coarse).toBe(true);
+    // The finger's press: the press model marks the tab, and the layer
+    // paints the pressed overlay as an image.
+    const lift = await holdFinger(page, cdp);
+    await expect.poll(async () => (await tabState(page)).press).toBe('on');
+    expect((await tabState(page)).image).not.toBe('none');
+    await lift();
+    await expect.poll(async () => (await tabState(page)).press).not.toBe('on');
+    // The tab in :active under the coarse pointer: the reset keeps the
+    // colour layer transparent, past any transition.
+    await forceActive(cdp, true);
+    expect(await settledColour(page)).toBe(TRANSPARENT);
+    await forceActive(cdp, false);
+  });
+});

package/src/Table/Table.spec.md

@@ -127,7 +127,7 @@ documented in `Table.doc.mjs` and the member and module docs.
 
 | ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Basis                                                                  | Evidence state                                                                                                                                                                       |
 | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| FR1  | By default, Styled Table renders one named Scroll region around one observed content box and one semantic Table. The Scroll region enters the keyboard order and contains inline overscroll only while inline content effectively overflows; fitting content passes scroll gestures to its ancestor. Explicit scroll-wrapper plugin HTML attributes remain authoritative.                                                                                                                                                                                                                                                                                                           | `spec:AST-025` FR12, FR14, FR19, FR21; current source, docs, and tests | Verified fitting and inline-overflow transitions through the shared `useScrollableArea` behavior core                                                                                |
+| FR1  | By default, Styled Table renders one named Scroll region around one observed content box and one semantic Table. The Scroll region takes the Table's own name (its `aria-labelledby`, else its `aria-label`), and a generic table name only when the Table has none. The Scroll region enters the keyboard order and contains inline overscroll only while inline content effectively overflows; fitting content passes scroll gestures to its ancestor. Explicit scroll-wrapper plugin HTML attributes remain authoritative.                                                                                                                                                       | `spec:AST-025` FR12, FR14, FR19, FR21; current source, docs, and tests | Verified fitting and inline-overflow transitions through the shared `useScrollableArea` behavior core                                                                                |
 | FR2  | Data-driven mode renders a Body section and a Header section with Column header cells when columns are present. Each data item renders a standard Row and Cells; an empty data array instead renders the configured empty-state row when enabled. It never creates a Footer section.                                                                                                                                                                                                                                                                                                                                                                                                | Current source, docs, and tests                                        | Verified current behavior; no new behavior decided                                                                                                                                   |
 | FR3  | Children mode passes caller composition through to the Table. TableHeader, TableBody, and TableFooter provide the respective sections, and TableRow, TableHeaderCell, and TableCell provide standard rows and cells.                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Current source, docs, and tests                                        | Verified current composition; no new API or DOM rule                                                                                                                                 |
 | FR4  | `Table.doc.mjs` is the canonical aggregate consumer owner for the eight current targets: `table`, `table-scroll-wrapper`, `table-header`, `table-body`, `table-footer`, `table-row`, `table-cell`, and `table-header-cell`. Member docs retain direct lookup metadata through `subComponentOf: 'Table'`.                                                                                                                                                                                                                                                                                                                                                                            | Current docs and CLI target tests                                      | Verified parent ownership; focused placement coverage is partial                                                                                                                     |

package/src/Table/Table.test.tsx

@@ -961,6 +961,38 @@ describe('Table', () => {
     expect(wrapper.style.overscrollBehaviorX).toBe('auto');
   });
 
+  it('names the scroll region after its table, not a generic "Table" (AST-025)', () => {
+    render(
+      <>
+        <Table aria-label="Orders" data={users} columns={columns} />
+        <h2 id="refunds-title">Refunds</h2>
+        <Table aria-labelledby="refunds-title" data={users} columns={columns} />
+        <h2 id="returns-title">Returns</h2>
+        <Table
+          aria-label="Ignored label"
+          aria-labelledby="returns-title"
+          data={users}
+          columns={columns}
+        />
+        <Table data={users} columns={columns} />
+      </>,
+    );
+    expect(screen.getByRole('group', {name: 'Orders'})).toBeInTheDocument();
+    expect(screen.getByRole('group', {name: 'Refunds'})).toHaveAttribute(
+      'aria-labelledby',
+      'refunds-title',
+    );
+    // With both, the region is named as the table is: by aria-labelledby.
+    expect(screen.getByRole('table', {name: 'Returns'})).toBeInTheDocument();
+    const returns = screen.getByRole('group', {name: 'Returns'});
+    expect(returns).not.toHaveAttribute('aria-label');
+    expect(
+      screen.queryByRole('group', {name: 'Ignored label'}),
+    ).not.toBeInTheDocument();
+    // An unnamed table keeps the generic fallback.
+    expect(screen.getAllByRole('group', {name: 'Table'})).toHaveLength(1);
+  });
+
   it('preserves scroll-wrapper HTML attributes from plugins', () => {
     const plugin: TablePlugin<User> = {
       transformScrollWrapper: props => ({

package/src/Table/Table.tsx

@@ -17,7 +17,7 @@
  * - /packages/cli/assets/templates/blocks/components/Table/ (showcase blocks)
  */
 
-import {useMemo, type ReactElement, type Ref} from 'react';
+import {createContext, use, useMemo, type ReactElement, type Ref} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
 import {BaseTable} from './BaseTable';
@@ -135,6 +135,17 @@ const scrollWrapperStyles = stylex.create({
   },
 });
 
+/**
+ * The Table's own name, for the scroll region that names itself after it.
+ * Internal to Table: the scroll wrapper is not given it as a prop, so it adds
+ * nothing to the public table types.
+ */
+const TableNameContext = createContext<{
+  label?: string;
+  labelledBy?: string;
+} | null>(null);
+TableNameContext.displayName = 'TableNameContext';
+
 function TableScrollWrapper({
   children,
   htmlProps,
@@ -151,7 +162,17 @@ function TableScrollWrapper({
   afterTable?: React.ReactNode;
 }) {
   const t = useTranslator();
-  const label = t('@astryx.table.label');
+  const tableName = use(TableNameContext);
+  // The focusable scroll region takes the table's own name (spec:AST-025
+  // FR12), so two tables are not two groups both named "Table". It is named
+  // the way the table is: `aria-labelledby` wins over `aria-label`, as it does
+  // in accessible-name computation; the generic name is the fallback for an
+  // unnamed table.
+  const labelledBy = tableName?.labelledBy;
+  const label =
+    labelledBy != null
+      ? undefined
+      : (tableName?.label ?? t('@astryx.table.label'));
   const {getViewportProps, getContentProps, state} = useScrollableArea({
     axis: 'inline',
     keyboardAccess: {owner: 'content'},
@@ -161,6 +182,9 @@ function TableScrollWrapper({
   const viewportProps = getViewportProps<HTMLDivElement>({
     role: 'group',
     'aria-label': label,
+    // A plugin's explicit name stays authoritative (Table FR1).
+    'aria-labelledby':
+      restHtmlProps['aria-label'] == null ? labelledBy : undefined,
     ...(state.inline.isScrollable ? {tabIndex: 0} : {}),
     ...restHtmlProps,
     ref,
@@ -240,18 +264,26 @@ function TableInner<T extends Record<string, unknown>>({
     }),
     [density, dividers, isStriped, hasHover, verticalAlign, textOverflow],
   );
+  const tableLabel = rest['aria-label'];
+  const tableLabelledBy = rest['aria-labelledby'];
+  const tableName = useMemo(
+    () => ({label: tableLabel, labelledBy: tableLabelledBy}),
+    [tableLabel, tableLabelledBy],
+  );
 
   return (
     <TableContext value={contextValue}>
-      <BaseTable<T>
-        ref={ref}
-        data={data}
-        columns={columns}
-        plugins={mergedPlugins}
-        textOverflow={textOverflow}
-        scrollWrapper={TableScrollWrapper}
-        {...rest}
-      />
+      <TableNameContext value={tableName}>
+        <BaseTable<T>
+          ref={ref}
+          data={data}
+          columns={columns}
+          plugins={mergedPlugins}
+          textOverflow={textOverflow}
+          scrollWrapper={TableScrollWrapper}
+          {...rest}
+        />
+      </TableNameContext>
     </TableContext>
   );
 }

package/src/Table/__tests__/Table.a11y.chromium.spec.ts

@@ -100,15 +100,27 @@ async function runState(
   });
 }
 
-test('every Table expectation is exercised by at least one Table state', async ({
-  page,
-}) => {
-  const cdp = await page.context().newCDPSession(page);
+// Checking coverage runs every state again, which on a loaded runner nears
+// the per-test timeout as one test. It runs as one serial part per state,
+// sharing their results, then one check over all of them.
+test.describe('every Table expectation is exercised by at least one Table state', () => {
+  test.describe.configure({mode: 'serial'});
   const results: BindingResult[] = [];
+
   for (const state of TABLE_A11Y_STATES) {
-    results.push(await runState(page, cdp, state));
+    test(`runs ${state.id}`, async ({page}) => {
+      const cdp = await page.context().newCDPSession(page);
+      results.push(await runState(page, cdp, state));
+    });
   }
-  expect(neverExercised(results)).toEqual([]);
+
+  test('no expectation is left unexercised', () => {
+    // Every part ran in this worker; this test alone proves nothing.
+    expect(results.map(result => result.state).sort()).toEqual(
+      TABLE_A11Y_STATES.map(state => state.id).sort(),
+    );
+    expect(neverExercised(results)).toEqual([]);
+  });
 });
 
 for (const state of TABLE_A11Y_STATES) {

package/src/Table/__tests__/Table.a11y.states.ts

@@ -51,11 +51,7 @@ export const TABLE_A11Y_STATES = [
     modules: ['sort'],
     facts: {
       label: 'Team members',
-      columnHeaders: [
-        'Sort by Name, sorted descending',
-        'Sort by Role',
-        'Sort by Location',
-      ],
+      columnHeaders: ['Name', 'Role', 'Location'],
       rows: 3,
       rowHeaders: [],
       cells: 3,

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

@@ -574,6 +574,28 @@ describe('useTableColumnResize', () => {
       expect(handle).toHaveAttribute('aria-label', 'Resize column Name');
     });
 
+    it("names a node header's handle by the header's visible text (AR1)", () => {
+      function Glyph() {
+        return <svg aria-hidden />;
+      }
+      render(
+        <ResizeTable
+          columns={[
+            {key: 'name', header: <span>Amount (EUR)</span>},
+            {key: 'role', header: <Glyph />},
+            {key: 'id', header: 'ID'},
+          ]}
+        />,
+      );
+      const [amount, role] = getResizeHandles();
+      expect(amount).toHaveAttribute(
+        'aria-label',
+        'Resize column Amount (EUR)',
+      );
+      // A header with no text it renders through children falls back to the key.
+      expect(role).toHaveAttribute('aria-label', 'Resize column role');
+    });
+
     it('handle has aria-valuemin', () => {
       render(<ResizeTable minWidth={80} />);
       const handle = getResizeHandles()[0];

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

@@ -29,6 +29,8 @@ import {
   DEFAULT_MIN_COLUMN_WIDTH,
 } from '../../columnUtils';
 import {observeResize} from '../../../utils/sharedResizeObserver';
+import {getNodeText} from '../../../utils/getNodeText';
+import {useTranslator} from '../../../i18n';
 
 // =============================================================================
 // Config Type
@@ -384,6 +386,7 @@ function ResizeHandle({
   isDraggingRef,
   tableRef,
 }: ResizeHandleProps) {
+  const t = useTranslator();
   const setTableDragging = useCallback(
     (dragging: boolean) => {
       const table = tableRef.current;
@@ -743,10 +746,11 @@ function ResizeHandle({
     ],
   );
 
-  const ariaLabel =
-    typeof columnHeader === 'string'
-      ? `Resize column ${columnHeader}`
-      : `Resize column ${columnKey}`;
+  // Named by the column's visible text, also when its header is a node; the
+  // key is the fallback only for a header with no reachable text (AR1).
+  const ariaLabel = t('@astryx.table.columnResize.resizeColumn', {
+    label: getNodeText(columnHeader) || columnKey,
+  });
 
   return (
     <div