@astryxdesign/core 0.6.2-canary.bfee8a4 → 0.6.2-canary.c8d5849

package/src/TabList/Tab.tsx

@@ -137,6 +137,15 @@ const styles = stylex.create({
       [stylex.when.ancestor(':hover', tabScope)]: {
         '@media (hover: hover)': colorVars['--color-overlay-hover'],
       },
+      // Pressed: the same layer steps up to the pressed overlay, read off the
+      // tab the way the hover is, so a press paints on a finger too. Repeated
+      // inside the hover-capable branch so it outranks the hover rule there
+      // (a media-nested rule carries extra generated priority; see
+      // interactionOverlay.stylex.ts).
+      [stylex.when.ancestor(':active', tabScope)]: {
+        default: colorVars['--color-overlay-pressed'],
+        '@media (hover: hover)': colorVars['--color-overlay-pressed'],
+      },
     },
     transitionProperty: 'background-color',
     transitionDuration: durationVars['--duration-fast'],
@@ -249,6 +258,7 @@ export function Tab({
   xstyle,
   className,
   style,
+  onClick,
   ...restProps
 }: TabProps) {
   const tabListCtx = useTabListContext();
@@ -263,9 +273,23 @@ export function Tab({
   const displayIcon = isSelected && selectedIcon ? selectedIcon : icon;
   const hasVisibleLabel = !isLabelHidden && label !== '';
 
-  const handleSelect = useCallback(() => {
-    tabListCtx.onChange(value);
-  }, [tabListCtx, value]);
+  const isDisabled =
+    restProps['aria-disabled'] === true ||
+    restProps['aria-disabled'] === 'true';
+
+  const handleSelect = useCallback(
+    (event: React.MouseEvent<HTMLButtonElement | HTMLAnchorElement>) => {
+      if (isDisabled) {
+        event.preventDefault();
+        return;
+      }
+      onClick?.(event as React.MouseEvent<HTMLButtonElement>);
+      if (!event.defaultPrevented) {
+        tabListCtx.onChange(value);
+      }
+    },
+    [isDisabled, onClick, tabListCtx, value],
+  );
 
   useDevWarning(
     'Tab',
@@ -339,7 +363,7 @@ export function Tab({
         sizeStyles[size],
         isSelected && styles.selected,
         isFill && layoutStyles.fill,
-        tabScope,
+        !isDisabled && tabScope,
         xstyle,
       ),
       className,
@@ -382,10 +406,14 @@ export function Tab({
   ) : null;
 
   if (isLink) {
+    // A disabled link tab must not reach a router component: some routers reject
+    // a missing destination, while others treat it as the current route. A
+    // plain anchor without href preserves the element shape but cannot navigate.
+    const LinkRoot = isDisabled ? 'a' : LinkComponent;
     return (
-      <LinkComponent
+      <LinkRoot
         ref={ref}
-        href={href}
+        href={isDisabled ? undefined : href}
         onClick={handleSelect}
         {...sharedProps}>
         {hoverBgElement}
@@ -393,7 +421,7 @@ export function Tab({
         {labelElement}
         {endContentElement}
         {indicatorElement}
-      </LinkComponent>
+      </LinkRoot>
     );
   }
 

package/src/TabList/TabList.doc.mjs

@@ -103,6 +103,17 @@ export const docs = {
     {name: 'TabMenu'},
   ],
   usage: {
+    accessibility: [
+      {
+        name: 'Tab label',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Hover', 'Pointer down', 'Selected'],
+        description:
+          'Each label must have at least 4.5:1 contrast with the tab surface behind it. For Hover and Pointer down, measure the final background after the overlay layer is applied.',
+      },
+    ],
     description:
       'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page, with overflow items handled by a built-in "more" menu.',
     bestPractices: [

package/src/TabList/TabList.test.tsx

@@ -12,6 +12,7 @@
 import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {hasPressedArm} from '../__tests__/pressState';
 import {TabList} from './TabList';
 import type {TabListProps} from './TabList';
 import {Tab} from './Tab';
@@ -1515,3 +1516,68 @@ describe('TabList ARIA pattern — any other role', () => {
     );
   });
 });
+
+describe('pressed state', () => {
+  it('paints the pressed overlay on the tab surface while the tab is pressed', () => {
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <Tab value="settings" label="Settings" />
+      </TabList>,
+    );
+    const tab = screen.getByRole('button', {name: 'Settings'});
+    // The hover surface is a child layer read off the tab; the press paints
+    // the same layer, so the assertion is on that layer.
+    const surface = tab.querySelector('span[aria-hidden="true"]');
+    if (surface == null) {
+      throw new Error('the tab has no hover surface to press');
+    }
+    expect(hasPressedArm(surface)).toBe(true);
+  });
+
+  it('does not activate a disabled button tab or call its handler', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    const onClick = vi.fn();
+    render(
+      <TabList value="home" onChange={onChange}>
+        <Tab value="home" label="Home" />
+        <Tab
+          value="settings"
+          label="Settings"
+          aria-disabled="true"
+          onClick={onClick}
+        />
+      </TabList>,
+    );
+    const tab = screen.getByRole('button', {name: 'Settings'});
+    await user.click(tab);
+    expect(onClick).not.toHaveBeenCalled();
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('removes navigation from a disabled link tab', () => {
+    const onChange = vi.fn();
+    const {container} = render(
+      <LinkProvider component={CustomLink}>
+        <TabList value="home" onChange={onChange}>
+          <Tab value="home" label="Home" />
+          <Tab
+            value="settings"
+            label="Settings"
+            href="/settings"
+            aria-disabled="true"
+          />
+        </TabList>
+      </LinkProvider>,
+    );
+    const tab = container.querySelector('a');
+    if (tab == null) {
+      throw new Error('the disabled link tab did not render an anchor');
+    }
+    expect(tab).not.toHaveAttribute('data-custom-link');
+    expect(tab).not.toHaveAttribute('href');
+    fireEvent.click(tab);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});

package/src/TabList/__tests__/Tabs.a11y.known-failures.ts

@@ -9,37 +9,4 @@
 
 import type {KnownFailure} from '@astryxdesign/a11y-spec';
 
-const COMMON = {
-  binding: 'Tab',
-  state: 'tab-disabled-unselected',
-  evidenceLayer: 'real-browser',
-  standardsReference:
-    'WCAG 2.2 4.1.2 Name, Role, Value; WAI-ARIA 1.2 aria-disabled',
-  reason:
-    'This migration records the existing behavior without changing the component interaction contract.',
-} as const;
-
-export const TABS_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
-  {
-    ...COMMON,
-    expectation: 'tabs.tab.unavailable-pointer-inert',
-    failureEquals:
-      'the tab is reported unavailable, but clicking it selected it',
-    userImpact:
-      'A pointer user can activate a tab that assistive technology reports as unavailable.',
-  },
-  {
-    ...COMMON,
-    expectation: 'tabs.tab.unavailable-enter-inert',
-    failureEquals: 'the tab is reported unavailable, but Enter selected it',
-    userImpact:
-      'A keyboard user can activate a focusable tab with Enter after assistive technology reports it unavailable.',
-  },
-  {
-    ...COMMON,
-    expectation: 'tabs.tab.unavailable-space-inert',
-    failureEquals: 'the tab is reported unavailable, but Space selected it',
-    userImpact:
-      'A keyboard user can activate a focusable tab with Space after assistive technology reports it unavailable.',
-  },
-];
+export const TABS_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [];

package/src/Table/Table.doc.mjs

@@ -12,7 +12,7 @@ const anatomy = [
     name: 'Scroll region',
     required: true,
     description:
-      'Keyboard-focusable outer region that scrolls horizontally when the columns overflow.',
+      'Outer region that scrolls horizontally, enters the keyboard order, and contains overscroll only while the columns overflow.',
   },
   {
     name: 'Header section',

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>
   );
 }