@astryxdesign/core 0.6.2 → 0.6.3-canary.0788c49

package/src/TabList/TabList.spec.md

@@ -0,0 +1,204 @@
+---
+schema_version: 3
+template_version: 5
+kind: component
+id: component:TabList
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-21
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, accessibility]
+verified_by:
+  [
+    packages/core/src/TabList/TabList.test.tsx,
+    apps/storybook/stories/TabList.stories.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [architecture:container-padding, architecture:public-component-api]
+contributing: [contributing:api-conventions]
+system_specs: [spec:AST-002/DEC-1, spec:AST-002/DEC-2, spec:AST-017/DEC-1]
+---
+
+# TabList component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                           |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | Canonicalize the existing alignment mode as `edgeCompensation?: 'inline'`; deprecate `isFullBleed` and remove it in the next minor release.                                                                                                                                        |
+| Behavior                | Move first and last visible tab content toward the host content line, reaching it when the host inset is at least the edge-tab padding, while preserving tab interaction padding, focus-ring room, overflow controls, selection-indicator geometry, and the optional divider rail. |
+| End-user impact         | Edge tabs lose unnecessary extra inset where host geometry permits and remain fully interactive without clipped focus, selection, overflow, or divider treatment.                                                                                                                  |
+| Builder impact          | Existing `isFullBleed` callsites keep working during the deprecation window and migrate mechanically to `edgeCompensation="inline"`.                                                                                                                                               |
+| Compatibility/readiness | Current behavior is shipped; the canonical alias is additive, while removing the released legacy prop is a separately implemented breaking change in the next minor release.                                                                                                       |
+| Review checks           | Reject a behavior change disguised as a rename, directional values without overflow/indicator proof, or early removal of the legacy prop.                                                                                                                                          |
+| Governing rules         | `architecture:container-padding/INV9–INV11`; `spec:AST-002/DEC-1–DEC-2`; `spec:AST-017/DEC-1`.                                                                                                                                                                                     |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+TabList's current opt-in is edge compensation: it consumes the full inherited
+host inset, moves visible edge-tab content toward the surrounding content line,
+and retains Tab-owned interaction padding plus TabList-owned divider, overflow,
+and indicator geometry. Content reaches the host line only when that inset is at
+least the edge tab's own padding. The public `isFullBleed` name is misleading
+because the strip restores uncovered content inset after the outer box expands.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; omission keeps current TabList geometry.
+- Compatibility class: the canonical alias is additive while the released
+  `isFullBleed` prop remains; removing that prop is a breaking change in the next
+  minor release under `spec:AST-017/DEC-1`.
+- Controlled/uncontrolled behavior: active-value control is unchanged.
+- Migration decision: `component:TabList/DEC-1`.
+
+During the compatibility window:
+
+- `edgeCompensation="inline"` is the canonical spelling;
+- omitted `edgeCompensation` plus `isFullBleed={true}` selects the same mode;
+- `isFullBleed` is deprecated and maintained examples use the canonical prop;
+- if both props are supplied, explicit `edgeCompensation` is canonical and the
+  legacy boolean cannot disable it.
+
+The removal release MUST include a `[breaking]` Changeset for
+`@astryxdesign/core`, consumer release notes, and an `astryx upgrade` codemod that rewrites
+`isFullBleed` to `edgeCompensation="inline"`.
+
+## Ownership boundary
+
+**Owns**
+
+- The TabList-wide edge-compensation mode and its compatibility alias.
+- The relationship between the outer TabList box, inner strip padding, edge tabs,
+  focus-ring room, overflow controls, and selection indicator.
+- Which logical edges are supported by the public mode.
+
+**Does not own / non-goals**
+
+- Host padding publication, nesting, or overlay resets — owned by
+  `architecture:container-padding`.
+- Button or List edge-compensation projections.
+- New `start` or `end` values without separate proof and owner approval.
+- A change to navigation/tab semantics, selection state, keyboard behavior, or
+  overflow ownership.
+
+## Public concepts
+
+| Concept           | Closed values or states  | Meaning                                                                                                                                              | Availability by variant/orientation/state                          | Default         | Owner               | Stability                       | Invalid-value behavior                                 |
+| ----------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | --------------- | ------------------- | ------------------------------- | ------------------------------------------------------ |
+| Edge compensation | omitted, `inline`        | Consume both inherited inline host insets and move edge-tab content toward the host lines while retaining local interaction and strip-owned geometry | Navigation and tabs patterns across current layout/overflow states | omitted         | `component:TabList` | accepted; canonical API pending | Other values are rejected by the public type           |
+| Legacy alias      | omitted, `false`, `true` | Compatibility spelling for omitted or inline edge compensation                                                                                       | Until the next minor release                                       | omitted/`false` | `component:TabList` | deprecated                      | `true` maps to `inline`; explicit canonical input wins |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                      | Basis                                                             | Status                                                   |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------- |
+| FR1 | The current opt-in MUST remain edge compensation: the outer TabList box consumes the full inherited inline host inset and any `hasDivider` rail spans that expanded width; the inner strip restores `max(host inset - edge-tab padding, 0)` at each logical edge. Visible edge-tab content reaches the host line only when the host inset is at least the tab padding; otherwise it moves toward that line without crossing the host boundary. | Current source and `component:TabList/DEC-1`                      | Shipped behavior                                         |
+| FR2 | Compensation MUST preserve Tab interaction padding, focus-ring room, overflow detection and controls, scroll access, selection-indicator geometry, and the optional divider rail's expanded inline span.                                                                                                                                                                                                                                       | Current source plus owner direction                               | Shipped behavior; expanded evidence required with rename |
+| FR3 | `edgeCompensation?: 'inline'` MUST become the canonical API without changing FR1–FR2 geometry or the omitted default.                                                                                                                                                                                                                                                                                                                          | `architecture:container-padding/INV10`; `component:TabList/DEC-1` | Accepted contract; implementation pending                |
+| FR4 | During the deprecation window, omitted `edgeCompensation` plus `isFullBleed={true}` MUST produce the canonical `inline` behavior. Explicit `edgeCompensation` MUST remain authoritative when both props are supplied.                                                                                                                                                                                                                          | Compatibility decision                                            | Accepted contract; implementation pending                |
+| FR5 | `isFullBleed` MUST be removed in the next minor release only after maintained docs/examples use `edgeCompensation`, both paths have compatibility evidence, and the removal includes a `[breaking]` Changeset plus an `astryx upgrade` codemod for mechanical consumer migration.                                                                                                                                                              | `component:TabList/DEC-1`; `spec:AST-017/DEC-1`                   | Accepted contract; implementation pending                |
+| FR6 | `start` and `end` MUST remain rejected until per-edge overflow, clipping, scroll-control, focus-ring, indicator, direction, and theme-padding evidence receives owner approval.                                                                                                                                                                                                                                                                | Shared logical vocabulary and TabList boundary                    | Accepted boundary                                        |
+
+### Allowed variation
+
+- Layout, size, role, selected value, labels, tab content, and overflow mode may
+  vary while the same edge-compensation meaning is preserved.
+- The implementation may retain the current outer-box/inner-strip technique or
+  replace it with equivalent geometry that satisfies FR1–FR2.
+- A host may be painted or bounded only where TabList's component-specific
+  evidence proves the outer box, clipping, focus, and indicator behavior safe.
+
+### Representative states
+
+| State                 | Required invariant                                                                                                       | Allowed variation                                                                               |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| Default/omitted       | Current TabList box, strip, and tab geometry are unchanged.                                                              | Any current layout, role, or overflow mode.                                                     |
+| Canonical inline mode | Outer box consumes each host inset; edge content reaches the host line only when that inset is at least the tab padding. | Host inset smaller than, equal to, or larger than edge-tab padding; asymmetric insets; LTR/RTL. |
+| Divider               | `hasDivider` rail spans the expanded outer inline width.                                                                 | Fitting or overflowing strips.                                                                  |
+| Legacy alias          | `isFullBleed={true}` matches canonical inline geometry during the compatibility window.                                  | The canonical prop may also be present.                                                         |
+| Overflowing strip     | Scroll access, edge fades, controls, and selected-tab reveal remain correct.                                             | Start/end overflow independently.                                                               |
+| Focused edge tab      | The focus ring remains visible and local to the tab.                                                                     | Keyboard or pointer focus.                                                                      |
+
+### Transformation and precedence order
+
+- **ORD1 — Public input.** Resolve explicit `edgeCompensation`; otherwise map
+  `isFullBleed={true}` to `inline` during the compatibility window; otherwise use
+  no compensation.
+- **ORD2 — Host geometry.** Read the matching inherited logical host insets, with
+  missing values falling back to zero.
+- **ORD3 — Component geometry.** Resolve edge-tab padding and focus/indicator
+  allowances from TabList-owned sources, restore the non-overlapping portion of
+  each content inset, and preserve interaction padding and owned affordances.
+
+### Performance and resources
+
+- **PR1 — CSS-first geometry.** The rename MUST add no observer, listener,
+  state, Effect, or render pass. Existing overflow measurement remains unchanged.
+
+## Accessibility contract
+
+- **AR1 — Interaction remains stable.** Edge compensation MUST NOT change the
+  tab/nav pattern, accessible names, selected state, keyboard movement, tab stop,
+  focus target, or controlled value behavior.
+- **AR2 — Overflow remains reachable.** Compensated edge geometry MUST NOT clip or
+  hide a focus ring, selected indicator, visible tab content, or an overflow
+  control required to reach offscreen tabs.
+
+## Design relationships
+
+| Anatomy or state  | Design requirement                                                                                    | Representation authority  | Hierarchy role | Component contract |
+| ----------------- | ----------------------------------------------------------------------------------------------------- | ------------------------- | -------------- | ------------------ |
+| Outer TabList box | Consumes the full inherited inline host inset; with `hasDivider`, its rail spans that expanded width. | `component:TabList/DEC-1` | Supporting     | FR1–FR3            |
+| Inner strip       | Restores `max(host inset - edge-tab padding, 0)` and owns scrolling/fades.                            | Current TabList behavior  | Structural     | FR1–FR2            |
+| Edge Tab          | Retains interaction padding and visible focus/selection treatment.                                    | Tab composition           | Prominent      | FR1–FR2, AR1–AR2   |
+
+## Family and system relationships
+
+- `architecture:container-padding` owns host publication, the shared
+  `edgeCompensation` vocabulary, logical-edge semantics, and overlay reset.
+- `architecture:public-component-api` and `spec:AST-002` own public API
+  admission; `spec:AST-017/DEC-1` owns the breaking classification and migration
+  evidence required when the released alias is removed.
+- TabList owns its specialized host, overflow, focus, and indicator projection.
+
+## Verification map
+
+| Contract         | Verification                                                                                                            | Representative states                                                                                                                           | Mutation or failure expectation                                                                            | Audit section          |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------- |
+| FR1–FR4          | `TabList.test.tsx` and type/docs tests                                                                                  | omitted, canonical, legacy, both props, and `hasDivider`                                                                                        | Alias drift, changed defaults, wrong precedence, or lost divider span fails                                | `audit:TabList/api`    |
+| FR1–FR6, AR1–AR2 | Real-browser TabList geometry and interaction evidence                                                                  | LTR/RTL; host inset smaller/equal/larger than edge-tab padding; asymmetric/zero inset; divider; fitting/overflowing; selected/focused edge tabs | Wrong bounded movement, clipped focus/indicator/divider, inaccessible overflow, or scroll regression fails | `audit:TabList/visual` |
+| FR5 and docs     | `TabList.doc.mjs`, Storybook, `[breaking]` Changeset, `astryx upgrade` codemod tests, and `scripts/check-knowledge.mjs` | canonical examples, deprecated alias, and removal migration                                                                                     | Missing migration guidance, wrong Changeset class, missing codemod rewrite, or stale canonical usage fails | `audit:TabList/docs`   |
+
+## Decision log
+
+### DEC-1 — TabList migrates from full-bleed wording to edge compensation
+
+**Reference:** `component:TabList/DEC-1`
+
+**Decider:** cixzhang, 2026-09-21
+
+TabList's current mode consumes the full inherited inline host inset, keeps an
+optional divider across that expanded width, and restores only the portion of
+content inset not already supplied by edge-tab padding. The user-facing intent is
+therefore edge compensation, not a promise that tab content itself reaches an
+outer edge. `edgeCompensation="inline"` becomes the canonical spelling;
+`isFullBleed` remains a compatibility alias until its `[breaking]` next-minor
+removal, with the required codemod and release evidence.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This claim-scoped contract does not duplicate TabList's complete navigation,
+selection, overflow, or theming contract, consumer examples, implementation
+steps, or List/Button projections. Those remain with their named owners.

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