@astryxdesign/core 0.6.2 → 0.6.3-canary.01fa439

package/src/Table/Table.spec.md

@@ -13,6 +13,7 @@ review_triggers: [public-api, behavior, layout, theming, accessibility]
 verified_by:
   [
     packages/core/src/Table/Table.test.tsx,
+    packages/core/src/Table/__tests__/TableScroll.a11y.chromium.spec.ts,
     packages/core/src/Table/Table.perf.test.tsx,
     packages/core/src/Table/plugins/selection/useTableSelection.test.tsx,
     packages/core/src/Table/plugins/sortable/useTableSortable.test.tsx,
@@ -33,7 +34,7 @@ architecture:
     architecture:public-component-api,
   ]
 contributing: []
-system_specs: []
+system_specs: [spec:AST-025]
 ---
 
 # Table component contract
@@ -49,11 +50,13 @@ generated anatomy, accessibility, migration, and evidence belong to each listed
 
 ## Compatibility and migration
 
-- Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
-  targets, aliases, and public API remain unchanged
+- Released default preserved: `no`; a fitting Table scroll region now passes
+  scrolling to its ancestor and stays out of the keyboard order, while an
+  overflowing region keeps its existing native scrolling path.
+- Compatibility class: standards-conformance bug fix; no public prop, target,
+  alias, or semantic Table element changes.
 - Controlled/uncontrolled behavior: unchanged
-- Migration decision: none
+- Migration decision: `spec:AST-025` FR12, FR14, FR19, FR21, and DEC-1
 
 Consumer migration instructions belong in consumer docs and release notes.
 
@@ -87,7 +90,7 @@ Consumer migration instructions belong in consumer docs and release notes.
   concerns for `useTableRowStatus`.
 - New targets for current untargeted plugin parts, or correction of current
   target-reachability gaps.
-- New runtime behavior, DOM, API, target, or alias.
+- New public API, theme target, or alias.
 
 ## Public concepts
 
@@ -103,20 +106,20 @@ documented in `Table.doc.mjs` and the member and module docs.
 
 ## Behavioral and layout contract
 
-| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                | Basis                                | Evidence state                                                                  |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------- |
-| FR1  | Styled Table renders one keyboard-focusable Scroll region around one semantic Table.                                                                                                                                                                                                                                                                                     | Current source, docs, and tests      | Verified current behavior; no new behavior decided                              |
-| 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                |
-| FR5  | For a sortable column, useTableSortable renders a Sort control around the column label, an Icon-owned Sort indicator glyph, and a numeric Sort priority only while multi-sort has more than one active entry.                                                                                                                                                            | Current source, docs, and tests      | Control and priority are tested; glyph presence is source-inspected only        |
-| FR6  | useTableSelection renders CheckboxInput-owned Selection controls in the generated selection Column header cell and each selectable body Cell; selection remains row state rather than separate anatomy.                                                                                                                                                                  | Current source, docs, and tests      | Verified stable delegated controls; no target or state change                   |
-| FR7  | For an expandable row, useTableRowExpansion renders an Expansion control with an Icon-owned Expansion glyph and conditionally appends an Expanded detail panel whose cell spans the column count captured by that plugin's `transformColumns` step.                                                                                                                      | Current source, docs, and tests      | Verified stable plugin parts; current target gaps remain                        |
-| FR8  | Empty data renders the default compact EmptyState unless the caller supplies replacement content or disables it.                                                                                                                                                                                                                                                         | Current source, docs, and tests      | Verified conditional delegation; caller content remains outside ownership       |
-| FR9  | Table converts the caller's named plugin record into one ordered array after its built-in styling plugin. Known names use the current canonical sequence `columnSettings → sort → tree → selection → pagination`; every other name follows that known set while preserving its record insertion order.                                                                   | Current source and docs              | Current shared ordering; canonical-name coverage is source-inspected            |
-| FR10 | Every applicable non-context transform runs sequentially in the resolved plugin-array order, so a later plugin receives the value returned by every earlier successful plugin. A throwing transform reports a development error and leaves the prior accumulated value in the pipeline.                                                                                  | Current source and tests             | Sequential composition is tested; failure isolation is source-inspected         |
-| FR11 | `transformColumns` completes before element transforms. Table then applies table, header-cell/header-row, body-cell/body-row, scroll-wrapper, and context phases at their render points. Header-cell contributions use `before`, `content`, `after`, `overlay`, and `below` slots. Context transforms run in reverse so the first plugin becomes the outermost provider. | Current source, types, and tests     | Transform application is tested; complete cross-phase order is source-inspected |
-| FR12 | When built-in and named plugin references are unchanged, Table reuses the resolved plugin array; unknown/custom plugin value identity and insertion order remain stable inputs to memoization.                                                                                                                                                                           | Current source and performance tests | Current performance contract; focused named-order coverage is partial           |
+| 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 |
+| 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                                      |
+| FR5  | For a sortable column, useTableSortable renders a Sort control around the column label, an Icon-owned Sort indicator glyph, and a numeric Sort priority only while multi-sort has more than one active entry.                                                                                                                                                             | Current source, docs, and tests                                        | Control and priority are tested; glyph presence is source-inspected only                              |
+| FR6  | useTableSelection renders CheckboxInput-owned Selection controls in the generated selection Column header cell and each selectable body Cell; selection remains row state rather than separate anatomy.                                                                                                                                                                   | Current source, docs, and tests                                        | Verified stable delegated controls; no target or state change                                         |
+| FR7  | For an expandable row, useTableRowExpansion renders an Expansion control with an Icon-owned Expansion glyph and conditionally appends an Expanded detail panel whose cell spans the column count captured by that plugin's `transformColumns` step.                                                                                                                       | Current source, docs, and tests                                        | Verified stable plugin parts; current target gaps remain                                              |
+| FR8  | Empty data renders the default compact EmptyState unless the caller supplies replacement content or disables it.                                                                                                                                                                                                                                                          | Current source, docs, and tests                                        | Verified conditional delegation; caller content remains outside ownership                             |
+| FR9  | Table converts the caller's named plugin record into one ordered array after its built-in styling plugin. Known names use the current canonical sequence `columnSettings → sort → tree → selection → pagination`; every other name follows that known set while preserving its record insertion order.                                                                    | Current source and docs                                                | Current shared ordering; canonical-name coverage is source-inspected                                  |
+| FR10 | Every applicable non-context transform runs sequentially in the resolved plugin-array order, so a later plugin receives the value returned by every earlier successful plugin. A throwing transform reports a development error and leaves the prior accumulated value in the pipeline.                                                                                   | Current source and tests                                               | Sequential composition is tested; failure isolation is source-inspected                               |
+| FR11 | `transformColumns` completes before element transforms. Table then applies table, header-cell/header-row, body-cell/body-row, scroll-wrapper, and context phases at their render points. Header-cell contributions use `before`, `content`, `after`, `overlay`, and `below` slots. Context transforms run in reverse so the first plugin becomes the outermost provider.  | Current source, types, and tests                                       | Transform application is tested; complete cross-phase order is source-inspected                       |
+| FR12 | When built-in and named plugin references are unchanged, Table reuses the resolved plugin array; unknown/custom plugin value identity and insertion order remain stable inputs to memoization.                                                                                                                                                                            | Current source and performance tests                                   | Current performance contract; focused named-order coverage is partial                                 |
 
 ### Current evidence and gaps
 
@@ -193,11 +196,15 @@ documented in `Table.doc.mjs` and the member and module docs.
 
 ## Accessibility contract
 
-This contract does not change or extend the current native table semantics,
-focusable Scroll region, column-header scope, sort `aria-sort`, selection
-`aria-selected`, CheckboxInput labels, or expansion `aria-expanded` behavior.
-Each public module owns accessibility introduced by its transforms; the shared
-pipeline does not confer correctness on module output.
+By default, the Scroll region is named as a `group`, enters sequential keyboard
+navigation only while inline overflow is effective, and keeps native Arrow/Page
+scrolling. A scroll-wrapper plugin may explicitly override its HTML accessibility
+attributes. Losing overflow removes future default tab stops without moving current
+focus. Effective inline scrolling contains overscroll at its edge; fitting content
+leaves page scrolling available. Native table semantics, column-header scope, sort
+`aria-sort`, selection `aria-selected`, CheckboxInput labels, and expansion
+`aria-expanded` remain unchanged. Each public module owns accessibility introduced
+by its transforms; the shared pipeline does not confer correctness on module output.
 
 ## Design relationships
 
@@ -294,24 +301,31 @@ aggregate ownership.
 
 ## Verification map
 
-| Contract            | Verification                                                                                         | Representative states                                               | Mutation or failure expectation                                                                                                                                                                                                                                           | Audit section             |
-| ------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
-| FR1-FR3             | `Table.test.tsx` render, structure, children-mode, section, and target assertions                    | Data-driven rows, empty data, and children composition              | Removing Table, Scroll region, or configured structure fails existing role, structure, class, or prop-forwarding assertions; Row and Cell are conditional on rendered data or caller composition.                                                                         | `audit:Table/anatomy`     |
-| FR4                 | CLI discovery and API target tests plus source inspection                                            | Direct member docs and unfiltered/scoped target output              | Duplicating a parent/member target or changing the canonical owner fails parent-aware discovery assertions; section target placement remains source-inspected.                                                                                                            | `audit:Table/theming`     |
-| FR5                 | `plugins/sortable/useTableSortable.test.tsx` plus source inspection                                  | Unsorted, ascending, descending, and multi-sort                     | Removing the Sort control, conditional priority, or ARIA state fails existing assertions. Removing the Sort indicator glyph does not currently fail a focused test; glyph presence and delegated Icon target placement remain source-inspected.                           | `audit:Table/anatomy`     |
-| FR6                 | `plugins/selection/useTableSelection.test.tsx`                                                       | Select all, individual, disabled, and non-selectable                | Removing header/body Selection controls or row selection state fails existing structure, label, interaction, and ARIA assertions; delegated CheckboxInput target placement remains source-inspected.                                                                      | `audit:Table/anatomy`     |
-| FR7                 | `plugins/rowExpansion/useTableRowExpansion.test.tsx` plus source inspection                          | Collapsed, expanded, and non-expandable rows                        | Removing the Expansion control, conditional detail panel, captured-count `colSpan`, or ARIA state fails existing assertions in the covered plugin order; later column transforms, delegated Icon target placement, and untargeted panel wrappers remain source-inspected. | `audit:Table/anatomy`     |
-| FR8                 | `Table.test.tsx` empty-state suite plus EmptyState public target metadata                            | Default, custom, disabled, and non-empty                            | Removing conditional empty behavior fails existing assertions; default EmptyState delegation remains source-inspected.                                                                                                                                                    | `audit:Table/anatomy`     |
-| FR9-FR11            | `Table.test.tsx`, `types.ts`, `BaseTable.tsx`, and `useBaseTablePlugins.ts`                          | Built-in plus known and custom named plugins; every transform phase | Sequential composition, base-before-user behavior, transform application, and slot output have focused coverage; complete known-name sorting, phase order, exception continuation, and context nesting remain source-inspected.                                           | `audit:Table/plugins`     |
-| FR12, PR1           | `Table.perf.test.tsx` plus `useBaseTablePlugins.ts` source inspection                                | Same plugin references, recreated record, and changed plugin value  | Unchanged plugin values must preserve the resolved array and representative no-op row-update budgets; focused named-record identity coverage remains partial.                                                                                                             | `audit:Table/performance` |
-| Module backlink     | `scripts/check-knowledge.mjs`                                                                        | Active parent and colocated module record                           | A missing, duplicate, mis-parented, wrong-kind, misnamed, or undiscovered module record fails knowledge validation.                                                                                                                                                       | `audit:Table/modules`     |
-| Theming anatomy map | `scripts/check-knowledge.mjs`, `themingTargets.test.ts`, and CLI parent-aware target discovery tests | Canonical anatomy, eight current targets, legacy alias              | Missing, extra, duplicated, prefixed, stale, alias-backed, or independently owned member mappings fail repository validation or discovery coverage.                                                                                                                       | `audit:Table/theming`     |
+| Contract            | Verification                                                                                                | Representative states                                                                   | Mutation or failure expectation                                                                                                                                                                                                                                           | Audit section             |
+| ------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| FR1-FR3             | `Table.test.tsx` render, structure, fit/overflow transitions, children-mode, section, and target assertions | Fitting and inline-overflowing data-driven tables, empty data, and children composition | Removing Table, Scroll region, observed content box, conditional keyboard access, or effective-axis containment fails existing role, structure, state, class, style, or prop-forwarding assertions; Row and Cell are conditional on rendered data or caller composition.  | `audit:Table/anatomy`     |
+| FR4                 | CLI discovery and API target tests plus source inspection                                                   | Direct member docs and unfiltered/scoped target output                                  | Duplicating a parent/member target or changing the canonical owner fails parent-aware discovery assertions; section target placement remains source-inspected.                                                                                                            | `audit:Table/theming`     |
+| FR5                 | `plugins/sortable/useTableSortable.test.tsx` plus source inspection                                         | Unsorted, ascending, descending, and multi-sort                                         | Removing the Sort control, conditional priority, or ARIA state fails existing assertions. Removing the Sort indicator glyph does not currently fail a focused test; glyph presence and delegated Icon target placement remain source-inspected.                           | `audit:Table/anatomy`     |
+| FR6                 | `plugins/selection/useTableSelection.test.tsx`                                                              | Select all, individual, disabled, and non-selectable                                    | Removing header/body Selection controls or row selection state fails existing structure, label, interaction, and ARIA assertions; delegated CheckboxInput target placement remains source-inspected.                                                                      | `audit:Table/anatomy`     |
+| FR7                 | `plugins/rowExpansion/useTableRowExpansion.test.tsx` plus source inspection                                 | Collapsed, expanded, and non-expandable rows                                            | Removing the Expansion control, conditional detail panel, captured-count `colSpan`, or ARIA state fails existing assertions in the covered plugin order; later column transforms, delegated Icon target placement, and untargeted panel wrappers remain source-inspected. | `audit:Table/anatomy`     |
+| FR8                 | `Table.test.tsx` empty-state suite plus EmptyState public target metadata                                   | Default, custom, disabled, and non-empty                                                | Removing conditional empty behavior fails existing assertions; default EmptyState delegation remains source-inspected.                                                                                                                                                    | `audit:Table/anatomy`     |
+| FR9-FR11            | `Table.test.tsx`, `types.ts`, `BaseTable.tsx`, and `useBaseTablePlugins.ts`                                 | Built-in plus known and custom named plugins; every transform phase                     | Sequential composition, base-before-user behavior, transform application, and slot output have focused coverage; complete known-name sorting, phase order, exception continuation, and context nesting remain source-inspected.                                           | `audit:Table/plugins`     |
+| FR12, PR1           | `Table.perf.test.tsx` plus `useBaseTablePlugins.ts` source inspection                                       | Same plugin references, recreated record, and changed plugin value                      | Unchanged plugin values must preserve the resolved array and representative no-op row-update budgets; focused named-record identity coverage remains partial.                                                                                                             | `audit:Table/performance` |
+| Module backlink     | `scripts/check-knowledge.mjs`                                                                               | Active parent and colocated module record                                               | A missing, duplicate, mis-parented, wrong-kind, misnamed, or undiscovered module record fails knowledge validation.                                                                                                                                                       | `audit:Table/modules`     |
+| Theming anatomy map | `scripts/check-knowledge.mjs`, `themingTargets.test.ts`, and CLI parent-aware target discovery tests        | Canonical anatomy, eight current targets, legacy alias                                  | Missing, extra, duplicated, prefixed, stale, alias-backed, or independently owned member mappings fail repository validation or discovery coverage.                                                                                                                       | `audit:Table/theming`     |
 
 ## Decision log
 
-None. This current contract records existing Table facts, approved canonical parent
-ownership, and the shared plugin protocol without introducing a component-local
-visual or runtime change.
+### DEC-1 — Table adopts the shared scroll behavior on its owned viewport
+
+**Reference:** `component:Table/DEC-1`
+**Decider:** `cixzhang`, 2026-09-20
+
+Table uses `useScrollableArea` on its existing Scroll region with a private observed
+content box. Inline overflow remains native and keyboard reachable. Containment is
+active only while that axis can scroll, so a fitting Table does not create a dead
+scroll zone for an ancestor. This keeps one Table-owned viewport and adds no public
+prop or parallel overflow detector.
 
 ## Open questions
 

package/src/Table/Table.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {act, render, screen} from '@testing-library/react';
 import * as stylex from '@stylexjs/stylex';
 import {BaseTable} from './BaseTable';
 import {Table} from './Table';
@@ -837,22 +837,95 @@ describe('Table', () => {
     expect(screen.getAllByRole('row')).toHaveLength(4);
   });
 
-  it('wraps table in a scroll container', () => {
+  it('wraps the table in an observed scroll content box', () => {
     render(<Table data={users} columns={columns} />);
     const table = screen.getByRole('table');
-    const wrapper = table.parentElement;
+    const content = table.parentElement;
+    const wrapper = content?.parentElement;
+    expect(content).toHaveAttribute('data-scroll-content');
     expect(wrapper).toBeTruthy();
     expect(wrapper!.className).toContain('astryx-table-scroll-wrapper');
   });
 
-  it('makes the scroll container keyboard-focusable', () => {
+  it('keeps a fitting scroll container out of the keyboard order', () => {
     render(<Table data={users} columns={columns} />);
-    const table = screen.getByRole('table');
-    const wrapper = table.parentElement;
-    expect(wrapper).toBeTruthy();
-    expect(wrapper!).toHaveAttribute('tabindex', '0');
-    expect(wrapper!).toHaveAttribute('role', 'group');
-    expect(wrapper!).toHaveAttribute('aria-label', 'Table');
+    const wrapper = screen.getByRole('group', {name: 'Table'});
+    expect(wrapper).not.toHaveAttribute('tabindex');
+    expect(wrapper.style.overscrollBehaviorX).toBe('auto');
+  });
+
+  it('preserves scroll-wrapper HTML attributes from plugins', () => {
+    const plugin: TablePlugin<User> = {
+      transformScrollWrapper: props => ({
+        ...props,
+        htmlProps: {
+          ...props.htmlProps,
+          role: 'region',
+          'aria-label': 'Orders',
+          tabIndex: 2,
+        },
+      }),
+    };
+    render(<Table data={users} columns={columns} plugins={{custom: plugin}} />);
+    const wrapper = screen.getByRole('region', {name: 'Orders'});
+    expect(wrapper).toHaveAttribute('tabindex', '2');
+  });
+
+  it('contains overscroll only while the table scrolls', () => {
+    const frames: FrameRequestCallback[] = [];
+    vi.stubGlobal(
+      'requestAnimationFrame',
+      vi.fn((callback: FrameRequestCallback) => {
+        frames.push(callback);
+        return frames.length;
+      }),
+    );
+    vi.stubGlobal('cancelAnimationFrame', vi.fn());
+
+    try {
+      render(<Table data={users} columns={columns} />);
+      const wrapper = screen.getByRole('group', {name: 'Table'});
+      Object.assign(wrapper.style, {overflowX: 'auto'});
+      for (const [key, value] of Object.entries({
+        clientWidth: 100,
+        clientHeight: 100,
+        scrollWidth: 180,
+        scrollHeight: 100,
+        scrollLeft: 0,
+        scrollTop: 0,
+      })) {
+        Object.defineProperty(wrapper, key, {
+          configurable: true,
+          value,
+          writable: true,
+        });
+      }
+
+      act(() => {
+        wrapper.dispatchEvent(new Event('scroll'));
+        frames.splice(0).forEach(callback => callback(performance.now()));
+      });
+
+      expect(wrapper).toHaveAttribute('tabindex', '0');
+      expect(wrapper).toHaveAttribute('data-scrollable-inline', 'true');
+      expect(wrapper.style.overscrollBehaviorX).toBe('contain');
+
+      Object.defineProperty(wrapper, 'scrollWidth', {
+        configurable: true,
+        value: 100,
+        writable: true,
+      });
+      act(() => {
+        wrapper.dispatchEvent(new Event('scroll'));
+        frames.splice(0).forEach(callback => callback(performance.now()));
+      });
+
+      expect(wrapper).not.toHaveAttribute('tabindex');
+      expect(wrapper).not.toHaveAttribute('data-scrollable-inline');
+      expect(wrapper.style.overscrollBehaviorX).toBe('auto');
+    } finally {
+      vi.unstubAllGlobals();
+    }
   });
 
   it('uses table-layout: auto in children mode', () => {

package/src/Table/Table.tsx

@@ -11,6 +11,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Table/Table.doc.mjs (props table, features, usage examples)
  * - /packages/core/src/Table/Table.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/Table/__tests__/TableScroll.a11y.chromium.spec.ts (browser scroll behavior)
  * - /packages/core/src/Table/index.ts (exports if types change)
  * - /apps/storybook/stories/Table.stories.tsx (storybook stories)
  * - /packages/cli/assets/templates/blocks/components/Table/ (showcase blocks)
@@ -22,6 +23,7 @@ import {colorVars} from '../theme/tokens.stylex';
 import {BaseTable} from './BaseTable';
 import {TableContext} from './TableContext';
 import {useBaseTablePlugins} from './useBaseTablePlugins';
+import {useScrollableArea} from '../hooks/useScrollableArea';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 import type {
@@ -149,30 +151,36 @@ function TableScrollWrapper({
   afterTable?: React.ReactNode;
 }) {
   const t = useTranslator();
+  const label = t('@astryx.table.label');
+  const {getViewportProps, getContentProps, state} = useScrollableArea({
+    axis: 'inline',
+    keyboardAccess: {owner: 'content'},
+    overscroll: 'contain',
+  });
   const {ref, ...restHtmlProps} = htmlProps ?? {};
+  const viewportProps = getViewportProps<HTMLDivElement>({
+    role: 'group',
+    'aria-label': label,
+    ...(state.inline.isScrollable ? {tabIndex: 0} : {}),
+    ...restHtmlProps,
+    ref,
+    ...mergeProps(
+      themeProps('table-scroll-wrapper'),
+      stylex.props(
+        scrollWrapperStyles.base,
+        scrollWrapperStyles.containerBleed,
+        ...(pluginStyles ?? []),
+      ),
+    ),
+  });
+
   return (
-    <div
-      ref={ref}
-      // Keyboard-focusable so keyboard users can scroll a horizontally
-      // overflowing table. Uses role="group" (not "region") so multiple
-      // tables on a page don't create duplicate same-named landmarks
-      // (axe: landmark-unique). Callers may override role/aria-label via
-      // htmlProps.
-      tabIndex={0}
-      role="group"
-      aria-label={t('@astryx.table.label')}
-      {...restHtmlProps}
-      {...mergeProps(
-        themeProps('table-scroll-wrapper'),
-        stylex.props(
-          scrollWrapperStyles.base,
-          scrollWrapperStyles.containerBleed,
-          ...(pluginStyles ?? []),
-        ),
-      )}>
-      {beforeTable}
-      {children}
-      {afterTable}
+    <div {...viewportProps}>
+      <div {...getContentProps<HTMLDivElement>()}>
+        {beforeTable}
+        {children}
+        {afterTable}
+      </div>
     </div>
   );
 }

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

@@ -0,0 +1,137 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TableScroll.a11y.chromium.spec.ts
+ * @input Built responsive Table story and real Chromium wheel input
+ * @output Browser evidence for conditional inline containment and scroll chaining
+ * @position Table integration proof for the shared useScrollableArea behavior
+ */
+
+import {expect, test, type Locator, type Page} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+async function mount(page: Page) {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=core-table--responsive-scroll&viewMode=story`,
+  );
+  const wrappers = page.locator('.astryx-table-scroll-wrapper');
+  await expect(wrappers).toHaveCount(3);
+  return wrappers;
+}
+
+async function putInsideOuterScroller(
+  page: Page,
+  viewport: Locator,
+  viewportWidth: number,
+  contentWidth: number,
+  tableWidth: number,
+) {
+  await viewport.evaluate(
+    (node, sizes) => {
+      const outer = document.createElement('div');
+      outer.dataset.tableScrollOuter = '';
+      outer.style.inlineSize = `${sizes.viewportWidth}px`;
+      outer.style.overflowX = 'auto';
+      const content = document.createElement('div');
+      content.style.inlineSize = `${sizes.contentWidth}px`;
+      node.parentElement?.insertBefore(outer, node);
+      outer.append(content);
+      content.append(node);
+      (node as HTMLElement).style.inlineSize = `${sizes.tableWidth}px`;
+    },
+    {viewportWidth, contentWidth, tableWidth},
+  );
+  return page.locator('[data-table-scroll-outer]');
+}
+
+async function wheelInline(page: Page, target: Locator) {
+  const box = await target.boundingBox();
+  if (box == null) {
+    throw new Error('Table scroll viewport has no rendered bounds');
+  }
+  await page.mouse.move(box.x + Math.min(box.width / 2, 100), box.y + 20);
+  await page.mouse.wheel(200, 0);
+}
+
+test('an overflowing table contains horizontal wheel input at its edge', async ({
+  page,
+}) => {
+  const wrappers = await mount(page);
+  const tableViewport = wrappers.nth(0);
+  await tableViewport.locator('table').evaluate(table => {
+    const viewport = table.closest<HTMLElement>('.astryx-table-scroll-wrapper');
+    if (viewport != null) {
+      table.style.minWidth = `${viewport.clientWidth + 400}px`;
+    }
+  });
+  await expect(tableViewport).toHaveAttribute('data-scrollable-inline', 'true');
+  await expect(tableViewport).toHaveAttribute('tabindex', '0');
+  await expect
+    .poll(async () =>
+      tableViewport.evaluate(
+        element => getComputedStyle(element).overscrollBehaviorX,
+      ),
+    )
+    .toBe('contain');
+
+  const outer = await putInsideOuterScroller(
+    page,
+    tableViewport,
+    320,
+    800,
+    320,
+  );
+  await tableViewport.evaluate(element => {
+    element.scrollLeft = element.scrollWidth - element.clientWidth;
+  });
+  await wheelInline(page, tableViewport);
+  await expect
+    .poll(async () => outer.evaluate(element => element.scrollLeft))
+    .toBe(0);
+});
+
+test('a fitting table passes horizontal wheel input to its outer scroller', async ({
+  page,
+}) => {
+  const wrappers = await mount(page);
+  const tableViewport = wrappers.nth(2);
+  const outer = await putInsideOuterScroller(
+    page,
+    tableViewport,
+    320,
+    800,
+    800,
+  );
+
+  await expect(tableViewport).not.toHaveAttribute(
+    'data-scrollable-inline',
+    'true',
+  );
+  await expect(tableViewport).not.toHaveAttribute('tabindex');
+  await expect
+    .poll(async () =>
+      tableViewport.evaluate(
+        element => getComputedStyle(element).overscrollBehaviorX,
+      ),
+    )
+    .toBe('auto');
+
+  await wheelInline(page, tableViewport);
+  await expect
+    .poll(async () => outer.evaluate(element => element.scrollLeft))
+    .toBeGreaterThan(0);
+});

package/src/TextArea/TextArea.tsx

@@ -95,9 +95,14 @@ const styles = stylex.create({
     paddingBlock: spacingVars['--spacing-1'],
     paddingInline: 'var(--_textarea-inline-padding)',
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/src/TextInput/TextInput.test.tsx

@@ -2,7 +2,8 @@
 
 /**
  * @file TextInput.test.tsx
- * @input Uses vitest, @testing-library/react, TextInput component
+ * @input Uses vitest, @testing-library/react, TextInput component, and the
+ *   shared declaredValue StyleX read-back helper
  * @output Unit tests for TextInput component behavior
  * @position Testing; validates TextInput.tsx implementation
  *
@@ -13,6 +14,7 @@ import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TestIcon} from '../__tests__/TestIcon';
+import {declaredValue} from '../__tests__/stylexDeclarations';
 import {InputGroup} from '../InputGroup';
 import {TextInput} from './TextInput';
 
@@ -1113,3 +1115,20 @@ describe('TextInput clear button focus behavior', () => {
     rafSpy.mockRestore();
   });
 });
+
+describe('TextInput text size', () => {
+  it('renders the theme body size outside the iOS zoom gate', () => {
+    // The 16px floor rides `@supports (-webkit-touch-callout: none)` inside
+    // `@media (pointer: coarse)` — iOS Safari is the browser that zooms on
+    // focus under 16px, so the floor targets it alone instead of every
+    // coarse pointer. jsdom's CSSOM drops at-rule-wrapped declarations it
+    // cannot parse, so the gate itself is pinned against the sources in
+    // inputFontFloor.test.ts; what this asserts is the visible result off
+    // the gate: the plain token size, not a floor.
+    render(<TextInput label="Name" value="" onChange={() => {}} />);
+    expect(declaredValue(screen.getByLabelText('Name'), 'font-size')).toBe(
+      'var(--text-body-size)',
+    );
+  });
+});
+

package/src/TextInput/TextInput.tsx

@@ -58,9 +58,14 @@ const styles = stylex.create({
     borderStyle: 'none',
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/src/TimeInput/TimeInput.tsx

@@ -95,9 +95,14 @@ const styles = stylex.create({
     borderStyle: 'none',
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/src/ToggleButton/ToggleButton.doc.mjs

@@ -31,17 +31,17 @@ export const docs = {
     {
       name: 'isPressed',
       type: 'boolean',
-      description: 'Whether the button is currently pressed. Ignored when inside a group.',
+      description: 'Whether the button is currently pressed. Ignored for a ToggleButtonGroup member with a value.',
     },
     {
       name: 'onPressedChange',
       type: '(isPressed: boolean, event: MouseEvent) => void',
-      description: 'Called when pressed state should change. Receives the next state and the click event; call event.preventDefault() to skip pressedChangeAction. Ignored when inside a group.',
+      description: 'Called synchronously when pressed state should change. Receives the next state and the click event; call event.preventDefault() to skip pressedChangeAction. Without an Action, the callback produces no Action-pending feedback. Ignored for a ToggleButtonGroup member with a value.',
     },
     {
       name: 'pressedChangeAction',
       type: '(isPressed: boolean) => void | Promise<void>',
-      description: 'Action handler for API- or navigation-backed toggles, run in a transition. Shows an optimistic pressed state immediately and a spinner while pending; the button stays interruptible by re-clicks.',
+      description: 'Action handler for API- or navigation-backed toggles, run in a transition after the synchronous onPressedChange callback unless that callback calls event.preventDefault(). Works without onPressedChange. Shows an optimistic pressed state and a spinner while pending, and remains interruptible by re-clicks. Omit it for callback-only toggles with no Action-pending feedback. Ignored for a ToggleButtonGroup member with a value.',
     },
     {
       name: 'size',