@astryxdesign/core 0.7.1 → 0.7.2-canary.01eab6a

package/src/Slider/Slider.spec.md

@@ -34,13 +34,20 @@ an additive target for the interactive control surface.
 
 ## Compatibility and migration
 
-- Released default preserved: `yes`
+- Released default preserved: `no` — FR5 changes the released `onChangeEnd`
+  payload; every other released default is unchanged
 - Compatibility class: additive target and state reflection; default styling,
   DOM semantics, and public props remain unchanged, and the one keyboard change
   AR1 names — the horizontal arrows follow the track's direction under RTL —
   ships as a behavior fix
+- `onChangeEnd` payload (FR5): a new contract decision (`spec:AST-017/FR33`),
+  not a correction. Released victim: an owner that moves `value` only from
+  `onChangeEnd`, with no `onChange`, moves by keyboard today and does not under
+  FR5, so the change is breaking (`spec:AST-017/FR1`) and ships as
+  `[breaking]` in a declared minor (`spec:AST-017/FR31`).
 - Controlled/uncontrolled behavior: unchanged; Slider remains controlled
-- Migration decision: none
+- Migration decision: an owner that moves `value` only from `onChangeEnd`
+  moves it from `onChange` instead (FR5)
 
 Consumer migration instructions belong in consumer docs and release notes.
 
@@ -64,18 +71,20 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Public concepts
 
-The record adds one public theming target and names the keyboard model (AR1)
-without adding or changing a component prop or value domain. Consumer props,
+The record adds one public theming target, names the keyboard model (AR1), and
+states which value `onChangeEnd` carries (FR5) without adding or changing a
+component prop or value domain. Consumer props,
 modes, states, and usage remain documented in `Slider.doc.mjs`.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                  | Basis                                   | Review state                                       |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |
-| FR1 | The current render places a filled range, one or two thumbs, and optional tick marks over the background track.                                      | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |
-| FR2 | `Slider`, `Interactive control`, `Track`, and `Thumb` carry the `slider`, `slider-control`, `slider-track`, and `slider-thumb` targets respectively. | Current source, public docs, and #6224  | Approved additive target contract                  |
-| FR3 | Filled range, tick marks, mark labels, and adjacent text value display are stable rendered parts without their own current Slider target.            | Current source and public docs          | Verified current asymmetry; not ratified as policy |
-| FR4 | Label and status presentation continue to use Field and FieldStatus; value tooltips continue to use Tooltip.                                         | Current source and focused tests        | Verified composition boundary                      |
+| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                                                                                                                                          | Basis                                   | Review state                                       |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |
+| FR1 | The current render places a filled range, one or two thumbs, and optional tick marks over the background track.                                                                                                                                                                                                                                                                                                                              | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |
+| FR2 | `Slider`, `Interactive control`, `Track`, and `Thumb` carry the `slider`, `slider-control`, `slider-track`, and `slider-thumb` targets respectively.                                                                                                                                                                                                                                                                                         | Current source, public docs, and DEC-1  | Approved additive target contract                  |
+| FR3 | Filled range, tick marks, mark labels, and adjacent text value display are stable rendered parts without their own current Slider target.                                                                                                                                                                                                                                                                                                    | Current source and public docs          | Verified current asymmetry; not ratified as policy |
+| FR4 | Label and status presentation continue to use Field and FieldStatus; value tooltips continue to use Tooltip.                                                                                                                                                                                                                                                                                                                                 | Current source and focused tests        | Verified composition boundary                      |
+| FR5 | `onChangeEnd` fires once when an interaction ends — a pointer drag or track press is released or cancelled, or a keyboard step (arrow, Page, Home, End) completes — and carries the value the owner renders after its synchronous response to that interaction's `onChange` calls, including any clamp, snap, or rejection; it never carries a value Slider emitted that the owner did not render. A range reports both values the same way. | Maintainer decision (DEC-3)             | Approved                                           |
 
 ### Observed current target asymmetry
 
@@ -106,6 +115,8 @@ either component's remaining target shape.
 
 - ORD1: an arrow or Page key result snaps to the nearest step, then clamps to
   the bounds; Home and End go to `min` and `max` (AR1).
+- ORD2: within one interaction, Slider calls `onChange`, the owner responds and
+  renders, then `onChangeEnd` reports the rendered value (FR5).
 - The anatomy decision (DEC-1) introduces no value, snapping, geometry,
   interaction, or styling precedence rule of its own.
 
@@ -214,14 +225,15 @@ separately listed value tooltip retains Tooltip's target.
 
 ## Verification map
 
-| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                                    | Representative states                                                         | Mutation or failure expectation                                                                                                                                       | Audit section                |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
-| FR1                 | `Slider.test.tsx` structure, range, and marks suites                                                                                                                                                                                                                                                                                                                            | Single, range, horizontal, vertical, marks                                    | Removing or misaligning stable parts breaks existing role, position, or mark assertions.                                                                              | `audit:Slider/anatomy`       |
-| AR1                 | Slider accessibility contract (`internal/a11y-spec`, pending) bound to Slider, in jsdom and Chromium; `Slider.test.tsx` keyboard suites, including "follows the mirrored track under RTL: ArrowLeft increases, ArrowRight decreases, Up/Down unchanged" and "keeps ArrowLeft decreasing on a vertical track under RTL"; the Page, Home/End and Up/Down cases under the contract | Single and range; horizontal LTR and RTL; vertical; disabled; formatted value | A thumb loses its role, name or value properties; an arrow, Page, Home or End key stops stepping or steps against the mirrored track; a range thumb crosses the other | `audit:Slider/accessibility` |
-| FR2                 | `Slider.test.tsx`, `themingTargets.test.ts`, generated probe theme, and Chromium                                                                                                                                                                                                                                                                                                | Root, horizontal/vertical control, disabled control, track, and thumb         | A target class/state is missing, undocumented, or placed outside its owning anatomy.                                                                                  | `audit:Slider/theming`       |
-| FR3                 | Source and consumer-doc review                                                                                                                                                                                                                                                                                                                                                  | Filled range, marks, labels, adjacent text value                              | A missing target is inaccurately documented as present or intentionally permanent.                                                                                    | `audit:Slider/theming`       |
-| FR4                 | Source inspection; focused tests cover label, status, and disabled-reason Tooltip only                                                                                                                                                                                                                                                                                          | Label, status, value tooltip, disabled reason                                 | Shared composition or its accessible association disappears; value-tooltip composition still lacks focused coverage.                                                  | `audit:Slider/anatomy`       |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                   | Canonical anatomy and four current local targets                              | Missing, extra, prefixed, stale, or unclaimed mappings fail repository validation.                                                                                    | `audit:Slider/theming`       |
+| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                                    | Representative states                                                                       | Mutation or failure expectation                                                                                                                                       | Audit section                |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| FR1                 | `Slider.test.tsx` structure, range, and marks suites                                                                                                                                                                                                                                                                                                                            | Single, range, horizontal, vertical, marks                                                  | Removing or misaligning stable parts breaks existing role, position, or mark assertions.                                                                              | `audit:Slider/anatomy`       |
+| AR1                 | Slider accessibility contract (`internal/a11y-spec`, pending) bound to Slider, in jsdom and Chromium; `Slider.test.tsx` keyboard suites, including "follows the mirrored track under RTL: ArrowLeft increases, ArrowRight decreases, Up/Down unchanged" and "keeps ArrowLeft decreasing on a vertical track under RTL"; the Page, Home/End and Up/Down cases under the contract | Single and range; horizontal LTR and RTL; vertical; disabled; formatted value               | A thumb loses its role, name or value properties; an arrow, Page, Home or End key stops stepping or steps against the mirrored track; a range thumb crosses the other | `audit:Slider/accessibility` |
+| FR2                 | `Slider.test.tsx`, `themingTargets.test.ts`, generated probe theme, and Chromium                                                                                                                                                                                                                                                                                                | Root, horizontal/vertical control, disabled control, track, and thumb                       | A target class/state is missing, undocumented, or placed outside its owning anatomy.                                                                                  | `audit:Slider/theming`       |
+| FR3                 | Source and consumer-doc review                                                                                                                                                                                                                                                                                                                                                  | Filled range, marks, labels, adjacent text value                                            | A missing target is inaccurately documented as present or intentionally permanent.                                                                                    | `audit:Slider/theming`       |
+| FR4                 | Source inspection; focused tests cover label, status, and disabled-reason Tooltip only                                                                                                                                                                                                                                                                                          | Label, status, value tooltip, disabled reason                                               | Shared composition or its accessible association disappears; value-tooltip composition still lacks focused coverage.                                                  | `audit:Slider/anatomy`       |
+| FR5                 | Pending: `Slider.test.tsx` change-end cases driven by an owner that renders, clamps, or rejects the emitted value (not yet in the suite)                                                                                                                                                                                                                                        | Single and range; pointer release before and after the owner re-renders; each keyboard step | `onChangeEnd` reports a value the owner did not render, fires more than once per interaction, or skips a completed keyboard step                                      | `audit:Slider/accessibility` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                   | Canonical anatomy and four current local targets                                            | Missing, extra, prefixed, stale, or unclaimed mappings fail repository validation.                                                                                    | `audit:Slider/theming`       |
 
 The focused Slider suite asserts the `slider-control` target's orientation and
 disabled state. Source/metadata guards cover all four target declarations. The
@@ -250,6 +262,15 @@ A thumb already plays the slider role as one composite control, so it carries th
 
 Rejected: keeping ArrowRight as "increase" under RTL; a Tab stop or arrow model per range thumb that differs from the single thumb.
 
+### DEC-3 — `onChangeEnd` reports the value the owner renders
+
+**Reference:** `component:Slider/DEC-3`
+**Decider:** `cixzhang`, `2026-10-16`
+
+`onChangeEnd` marks the end of an interaction, so it reports what the slider shows when the interaction ends: the controlled value after the owner has answered `onChange`. An owner that clamps, snaps, or rejects a value therefore receives the value it kept, and the commit agrees with the thumb (FR5).
+
+Rejected: reporting the last value Slider emitted through `onChange`.
+
 ## Open questions
 
 - **OQ1 — After a joint ProgressBar and Slider family audit, should any shared

package/src/Switch/Switch.test.tsx

@@ -834,6 +834,55 @@ describe('Switch', () => {
       expect(root).toHaveAttribute('id', 'switch-1');
       expect(root).toHaveAttribute('aria-label', 'Toggle notifications');
     });
+
+    it('composes a caller aria-describedby onto the switch control', () => {
+      const {container} = render(
+        <>
+          <p id="external-hint">Applies to every repository</p>
+          <Switch
+            label="Notifications"
+            description="Sends a daily digest"
+            value={false}
+            onChange={() => {}}
+            data-testid="my-switch"
+            aria-describedby="external-hint"
+          />
+        </>,
+      );
+      const control = screen.getByRole('switch');
+      const description = screen.getByText('Sends a daily digest');
+      expect(control.getAttribute('aria-describedby')?.split(' ')).toEqual([
+        'external-hint',
+        description.id,
+      ]);
+      expect(control).toHaveAccessibleDescription(
+        'Applies to every repository Sends a daily digest',
+      );
+      // The id reference lives on the control only, not on the field wrapper.
+      const root = container.querySelector('[data-testid="my-switch"]');
+      expect(root).not.toHaveAttribute('aria-describedby');
+    });
+
+    it('names the switch control from a caller aria-labelledby', () => {
+      const {container} = render(
+        <>
+          <span id="row-title">Release notes</span>
+          <Switch
+            label="Pin Release notes"
+            isLabelHidden
+            value={false}
+            onChange={() => {}}
+            data-testid="my-switch"
+            aria-labelledby="row-title"
+          />
+        </>,
+      );
+      const control = screen.getByRole('switch', {name: 'Release notes'});
+      expect(control).toHaveAttribute('aria-labelledby', 'row-title');
+      // The id reference lives on the control only, not on the field wrapper.
+      const root = container.querySelector('[data-testid="my-switch"]');
+      expect(root).not.toHaveAttribute('aria-labelledby');
+    });
   });
 
   describe('pressed state', () => {

package/src/Switch/Switch.tsx

@@ -566,6 +566,8 @@ export function Switch({
   className,
   style,
   ref,
+  'aria-describedby': ariaDescribedByProp,
+  'aria-labelledby': ariaLabelledByProp,
   ...rest
 }: SwitchProps) {
   const t = useTranslator();
@@ -610,7 +612,12 @@ export function Switch({
   // Only include descriptionID when the element actually renders.
   // FieldLabel renders the description (with descriptionID) even when the
   // label is visually hidden — it's sr-only, so keep it linked.
+  // A consumer's own `aria-describedby` describes the control, so it comes
+  // first here rather than landing on the field wrapper via `...rest`.
   const describedByParts: string[] = [];
+  if (ariaDescribedByProp) {
+    describedByParts.push(ariaDescribedByProp);
+  }
   if (description) {
     describedByParts.push(descriptionID);
   }
@@ -658,6 +665,10 @@ export function Switch({
         }}
         onFocus={onFocus}
         onBlur={onBlur}
+        // A caller's `aria-labelledby` names the control (a visible title
+        // elsewhere in the row, for example), so it reaches the input rather
+        // than the field wrapper via `...rest`.
+        aria-labelledby={ariaLabelledByProp}
         aria-describedby={ariaDescribedBy}
         aria-invalid={status?.type === 'error' ? true : undefined}
         aria-busy={isBusy || undefined}

package/src/TabList/TabList.spec.md

@@ -31,10 +31,10 @@ system_specs: [spec:AST-002/DEC-1, spec:AST-002/DEC-2, spec:AST-017/DEC-1]
 
 | Area                    | Contract                                                                                                                                                                                                                                                                           |
 | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | Canonicalize the existing alignment mode as `edgeCompensation?: 'inline'`; deprecate `isFullBleed` and remove it in the next minor release.                                                                                                                                        |
+| Public contract         | Canonicalize the existing mode as `edge?: 'padded' \| 'bleed'` (default `'padded'`) from the shared `edge` vocabulary; deprecate `isFullBleed` as an alias of `edge="bleed"` 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"`.                                                                                                                                               |
+| Builder impact          | Existing `isFullBleed` callsites keep working during the deprecation window and migrate mechanically to `edge="bleed"`.                                                                                                                                                            |
 | 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`.                                                                                                                                                                                     |
@@ -43,12 +43,13 @@ 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,
+TabList's current opt-in is the shared `bleed` edge treatment: 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.
+because the strip keeps a content line: it restores uncovered content inset
+after the outer box expands, which `architecture:container-padding` names `bleed`.
 
 ## Compatibility and migration
 
@@ -61,21 +62,21 @@ because the strip restores uncovered content inset after the outer box expands.
 
 During the compatibility window:
 
-- `edgeCompensation="inline"` is the canonical spelling;
-- omitted `edgeCompensation` plus `isFullBleed={true}` selects the same mode;
+- `edge="bleed"` is the canonical spelling, and omitted `edge` means `padded`;
+- omitted `edge` plus `isFullBleed={true}` selects `bleed`;
 - `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.
+- if both props are supplied, explicit `edge` is canonical and the legacy
+  boolean cannot override 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"`.
+`isFullBleed` to `edge="bleed"`.
 
 ## Ownership boundary
 
 **Owns**
 
-- The TabList-wide edge-compensation mode and its compatibility alias.
+- The TabList-wide `bleed` edge treatment 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.
@@ -84,33 +85,34 @@ The removal release MUST include a `[breaking]` Changeset for
 
 - 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.
+- Button or List edge projections.
+- The `flush` or `outset` values, or per-edge application, 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 |
+| Concept        | Closed values or states    | Meaning                                                                                                                                                                                           | Availability by variant/orientation/state                          | Default            | Owner               | Stability                       | Invalid-value behavior                       |
+| -------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------ | ------------------- | ------------------------------- | -------------------------------------------- |
+| Edge treatment | omitted, `padded`, `bleed` | `bleed`: consume both inherited inline host insets and move edge-tab content toward the host lines while retaining local interaction and strip-owned geometry; `padded`: current default geometry | Navigation and tabs patterns across current layout/overflow states | omitted (`padded`) | `component:TabList` | accepted; canonical API pending | Other values are rejected by the public type |
+| Legacy alias   | omitted, `false`, `true`   | Compatibility spelling for `padded` or `bleed`                                                                                                                                                    | Until the next minor release                                       | omitted/`false`    | `component:TabList` | deprecated                      | `true` maps to `bleed`; explicit `edge` 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                                        |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                          | Basis                                                             | Status                                                   |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------- |
+| FR1 | The current opt-in MUST remain the `bleed` treatment: 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 | `edge?: 'padded' \| 'bleed'` MUST become the canonical API, with `bleed` selecting FR1–FR2 geometry and `padded` the omitted default, without changing either.                                                                                                                                                                                                                                                                                     | `architecture:container-padding/INV10`; `component:TabList/DEC-1` | Accepted contract; implementation pending                |
+| FR4 | During the deprecation window, omitted `edge` plus `isFullBleed={true}` MUST produce the canonical `bleed` behavior. Explicit `edge` 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 `edge`, 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 | `flush`, `outset`, and per-edge application MUST remain rejected until overflow, clipping, scroll-control, focus-ring, indicator, direction, and theme-padding evidence receives owner approval.                                                                                                                                                                                                                                                   | Shared edge 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.
+  vary while the same `bleed` 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
@@ -118,20 +120,20 @@ The removal release MUST include a `[breaking]` Changeset for
 
 ### 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.                                                                      |
+| State             | Required invariant                                                                                                       | Allowed variation                                                                               |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| Default/omitted   | Current TabList box, strip, and tab geometry are unchanged.                                                              | Any current layout, role, or overflow mode.                                                     |
+| Canonical `bleed` | 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 `bleed` 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.
+- **ORD1 — Public input.** Resolve explicit `edge`; otherwise map
+  `isFullBleed={true}` to `bleed` during the compatibility window; otherwise use
+  `padded`.
 - **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
@@ -145,10 +147,10 @@ The removal release MUST include a `[breaking]` Changeset for
 
 ## Accessibility contract
 
-- **AR1 — Interaction remains stable.** Edge compensation MUST NOT change the
+- **AR1 — Interaction remains stable.** The `bleed` treatment 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
+- **AR2 — Overflow remains reachable.** `bleed` geometry MUST NOT clip or
   hide a focus ring, selected indicator, visible tab content, or an overflow
   control required to reach offscreen tabs.
 
@@ -162,8 +164,8 @@ The removal release MUST include a `[breaking]` Changeset for
 
 ## Family and system relationships
 
-- `architecture:container-padding` owns host publication, the shared
-  `edgeCompensation` vocabulary, logical-edge semantics, and overlay reset.
+- `architecture:container-padding` owns host publication, the shared `edge`
+  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.
@@ -189,9 +191,20 @@ 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.
+outer edge. DEC-2 sets the canonical spelling; `isFullBleed` remains a
+compatibility alias until its `[breaking]` next-minor removal, with the required
+codemod and release evidence.
+
+### DEC-2 — TabList spells its mode with the shared edge vocabulary
+
+**Reference:** `component:TabList/DEC-2`
+
+**Decider:** cixzhang, 2026-10-16
+
+`architecture:container-padding` names TabList's geometry `bleed`: paint reaches
+the host's padding edge and content stays on the host content line, or at the
+edge tab's own padding when the host inset is smaller. `edge="bleed"` is the
+canonical spelling, so TabList and List share one prop name and one value set.
 
 ## Open questions
 

package/src/TabList/TabList.test.tsx

@@ -783,6 +783,73 @@ describe('TabMenu', () => {
   });
 });
 
+describe('TabMenu host attributes', () => {
+  const menuOptions = [
+    {value: 'analytics', label: 'Analytics'},
+    {value: 'reports', label: 'Reports'},
+  ];
+
+  it('forwards host attributes to the trigger, not the popup', () => {
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu
+          label="More"
+          options={menuOptions}
+          id="more-tabs"
+          aria-label="More views"
+          data-view="overflow"
+        />
+      </TabList>,
+    );
+
+    const trigger = screen.getByRole('button', {name: 'More views'});
+    expect(trigger).toHaveAttribute('id', 'more-tabs');
+    expect(trigger).toHaveAttribute('data-view', 'overflow');
+    const menu = screen.getByRole('menu', {name: 'More', hidden: true});
+    expect(trigger).toHaveAttribute('aria-controls', menu.id);
+  });
+
+  it('runs drag-and-drop handlers on the trigger', () => {
+    const onDragOver = vi.fn();
+    const onDrop = vi.fn();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu
+          label="More"
+          options={menuOptions}
+          onDragOver={onDragOver}
+          onDrop={onDrop}
+        />
+      </TabList>,
+    );
+    const trigger = screen.getByRole('button', {name: 'More'});
+    fireEvent.dragOver(trigger);
+    fireEvent.drop(trigger);
+    expect(onDragOver).toHaveBeenCalledTimes(1);
+    expect(onDrop).toHaveBeenCalledTimes(1);
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('onClick preserves the toggle', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn((event: React.MouseEvent<HTMLButtonElement>) => {
+      event.preventDefault();
+    });
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} onClick={onClick} />
+      </TabList>,
+    );
+    const trigger = screen.getByRole('button', {name: 'More'});
+    await user.click(trigger);
+    expect(onClick).toHaveBeenCalledTimes(1);
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+  });
+});
+
 describe('TabMenu keyboard navigation (roving tabindex)', () => {
   const menuOptions = [
     {value: 'analytics', label: 'Analytics'},

package/src/TabList/TabMenu.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   subComponentOf: 'TabList',
   displayName: 'Tab Menu',
   isHiddenFromOverview: true,
-  description: "Overflow menu trigger that opens a dropdown of additional tab options, showing the selected option's label as the trigger text.",
+  description: "Overflow menu trigger that opens a dropdown of additional tab options, showing the selected option's label as the trigger text. Host attributes and DOM event handlers (id, aria-*, data-*, drag and drop) reach the trigger button, not the popup or its options. The button keeps its role, tab stop, and menu disclosure attributes.",
   // TabMenu requires TabList context; wrap it so the preview doesn't throw.
   // The wrapper value matches none of the options, so the trigger shows its
   // own label (the idle overflow state).
@@ -42,7 +42,7 @@ export const docsZh = {
   name: 'TabMenu',
   isHiddenFromOverview: true,
   displayName: 'Tab Menu',
-  description: '溢出菜单触发器，打开包含额外标签选项的下拉菜单，将选中选项的标签显示为触发器文本。',
+  description: '溢出菜单触发器，打开包含额外标签选项的下拉菜单，将选中选项的标签显示为触发器文本。宿主属性和 DOM 事件处理器（id、aria-*、data-*、拖放）传递给触发按钮，而不是弹出菜单或选项。按钮保留自己的角色、Tab 停靠点及菜单展开属性。',
   props: [
     {
       name: 'label',
@@ -63,7 +63,8 @@ export const docsDense = {
   name: 'TabMenu',
   isHiddenFromOverview: true,
   displayName: 'Tab Menu',
-  description: "Overflow menu trigger; dropdown of extra tab options, shows selected option's label as trigger text.",
+  description:
+    "Overflow menu trigger; shows selected option's label. Host attributes/DOM handlers reach the trigger button, not the popup/options; role, tab stop and disclosure attributes stay owned.",
   propDescriptions: {
     label: 'Trigger text (when no option selected) + dropdown heading.',
     options: 'Menu options array rendered in dropdown.',

package/src/TabList/TabMenu.tsx

@@ -37,7 +37,7 @@ import {useListFocus} from '../hooks/useListFocus';
 import {useTabListContext} from './TabListContext';
 import type {TabListSize} from './TabListContext';
 import {tabScope} from './tab.markers.stylex';
-import {mergeProps} from '../utils';
+import {composeEventHandlers, mergeProps} from '../utils';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
@@ -51,9 +51,9 @@ export interface TabMenuOption {
   icon?: ReactNode | IconType;
 }
 
-export interface TabMenuProps extends Pick<
+export interface TabMenuProps extends Omit<
   BaseProps<HTMLButtonElement>,
-  'xstyle' | 'className' | 'style'
+  'role' | 'tabIndex' | 'aria-haspopup' | 'aria-expanded' | 'aria-controls'
 > {
   ref?: React.Ref<HTMLButtonElement>;
   /**
@@ -263,6 +263,8 @@ export function TabMenu({
   xstyle,
   className,
   style,
+  onClick,
+  ...rest
 }: TabMenuProps) {
   const tabListCtx = useTabListContext();
   const menuId = useId();
@@ -346,6 +348,7 @@ export function TabMenu({
   return (
     <>
       <button
+        {...rest}
         ref={setButtonRef}
         type="button"
         aria-haspopup="menu"
@@ -353,7 +356,7 @@ export function TabMenu({
         aria-controls={menuId}
         data-tab-menu=""
         tabIndex={hasSelectedOption ? 0 : -1}
-        onClick={handleToggle}
+        onClick={composeEventHandlers(handleToggle, onClick)}
         {...mergeProps(
           themeProps('tab-menu'),
           focusOutlineProps.focusVisible(