@astryxdesign/core 0.7.1 → 0.7.2-canary.151434a

package/src/Selector/useCombobox.doc.mjs

@@ -0,0 +1,237 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useCombobox',
+  displayName: 'useCombobox',
+  group: 'Selector',
+  keywords: [
+    'combobox',
+    'listbox',
+    'select',
+    'dropdown',
+    'highlight',
+    'active option',
+    'aria-activedescendant',
+    'keyboard',
+    'arrow keys',
+    'headless',
+    'apg',
+    'accessibility',
+    'a11y',
+  ],
+  params: [
+    {
+      name: 'options',
+      type: 'UseComboboxOptions',
+      description: 'Configuration object.',
+      required: true,
+    },
+    {
+      name: 'options.selectableItems',
+      type: 'SelectorOptionData[]',
+      description:
+        'The options in the same order as they render. Options with `disabled` cannot be picked and are skipped while moving through the open list; ArrowDown or ArrowUp that opens the list still lands on the first or last option.',
+      required: true,
+    },
+    {
+      name: 'options.isOpen',
+      type: 'boolean',
+      description: 'Whether the list is shown. The caller owns this state.',
+      required: true,
+    },
+    {
+      name: 'options.onOpen',
+      type: '() => unknown',
+      description:
+        'Called to show the list. Return `false` to refuse; the hook then leaves the highlight alone.',
+      required: true,
+    },
+    {
+      name: 'options.onClose',
+      type: '() => void',
+      description:
+        'Called when the hook hides the list; the hook resets the highlight first. When the caller closes the list itself (an outside press, say), it should also call `setHighlightedIndex(-1)`.',
+      required: true,
+    },
+    {
+      name: 'options.listboxId',
+      type: 'string',
+      description:
+        "The listbox element's id. Option ids are derived from it through `getItemId`.",
+      required: true,
+    },
+    {
+      name: 'options.value',
+      type: 'string',
+      description:
+        'The selected value. Without search, opening by a press, Enter or Space highlights it, or the first option when nothing is selected; ArrowDown and ArrowUp open on the first and last option.',
+    },
+    {
+      name: 'options.onSelect',
+      type: '(value: string) => void',
+      description:
+        'Called with the picked value. Picking also closes the list.',
+    },
+    {
+      name: 'options.onClear',
+      type: '() => void',
+      description:
+        'Clears the value. When provided, Delete or Backspace on the closed control clears it, so clearing is not pointer-only. Ignored while the list is open or with `hasSearch`.',
+    },
+    {
+      name: 'options.hasSearch',
+      type: 'boolean',
+      description:
+        'Whether the list has its own search field. Space then types instead of picking, opening by a press or Enter does not pre-highlight (ArrowDown and ArrowUp still open on the first and last option), and printable keys on the closed control go to `onSearchSeed`.',
+      default: 'false',
+    },
+    {
+      name: 'options.onSearchSeed',
+      type: '(char: string) => void',
+      description:
+        'With `hasSearch`, receives each printable character except Space typed while the control has focus, opening the list first when it is closed, so type-to-find needs no separate open step.',
+    },
+    {
+      name: 'options.isDisabled',
+      type: 'boolean',
+      description: 'Whether the control ignores clicks and keys.',
+      default: 'false',
+    },
+  ],
+  returns: [
+    {
+      name: 'highlightedIndex',
+      type: 'number',
+      description:
+        'Index of the active option, or -1 when none is active. With `hasSearch`, opening by a press or Enter does not set one, so it stays -1 after the hook itself closes the list; ArrowDown and ArrowUp still open on the first or last option. Render it as the active option and name it in `aria-activedescendant` only while it points at a rendered option.',
+    },
+    {
+      name: 'setHighlightedIndex',
+      type: '(index: number) => void',
+      description:
+        'Sets the active option, for example from a filter that changes the options.',
+    },
+    {
+      name: 'getItemId',
+      type: '(index: number) => string',
+      description:
+        "The id to render on the option at `index`. Set the control's `aria-activedescendant` to `isOpen && highlightedIndex >= 0 && highlightedIndex < selectableItems.length ? getItemId(highlightedIndex) : undefined`, so it never names an option that does not exist, including in an empty list.",
+    },
+    {
+      name: 'onTriggerClick',
+      type: '() => void',
+      description: 'Toggles the list from a press on the control.',
+    },
+    {
+      name: 'onKeyDown',
+      type: '(e: React.KeyboardEvent) => void',
+      description:
+        'Key handler for the control that keeps focus. ArrowDown and ArrowUp open the list or move the active option; Enter (and Space without search) picks it or opens the list; Escape and Tab close it; Home, End, PageUp and PageDown jump to the first or last option. An editable control that keeps Home and End for the caret does not pass them to this handler, as CommandPalette does.',
+    },
+    {
+      name: 'onItemSelect',
+      type: '(item: SelectorOptionData) => void',
+      description: 'Picks an option from a press on it, then closes the list.',
+    },
+    {
+      name: 'onItemMouseEnter',
+      type: '(item: SelectorOptionData, index: number) => void',
+      description:
+        'Makes the hovered option active without scrolling the list or moving focus.',
+    },
+  ],
+  usage: {
+    description:
+      'Tracks the active option of a single-select combobox and handles its keys, while DOM focus stays on the control. It powers Selector and CommandPalette; use it to build a combobox those components do not cover. It renders nothing and sets no attributes: the caller renders the control, the listbox and the options, and wires `role`, `aria-expanded`, `aria-controls` and `aria-activedescendant` from what it returns.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Render each option with `id={getItemId(index)}` and set the control's `aria-activedescendant` only while `isOpen` and `highlightedIndex` points at a rendered option, as CommandPalette does.",
+      },
+      {
+        guidance: true,
+        description:
+          "For type-to-select without a search field, run useTypeahead's handler first and fall through to this `onKeyDown` when it returns false, as Selector does.",
+      },
+      {
+        guidance: true,
+        description:
+          'Announce the number of results through useAnnounce when the options change for a new query.',
+      },
+      {
+        guidance: false,
+        description:
+          'Move DOM focus onto the options; the active option is announced through `aria-activedescendant` while focus stays on the control.',
+      },
+    ],
+  },
+  relatedComponents: ['Selector', 'CommandPalette'],
+  relatedHooks: ['useMultiCombobox', 'useTypeahead', 'useAnnounce'],
+  importPath: '@astryxdesign/core/Selector',
+  category: 'focus',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Single-select combobox state + keys; focus stays on control. Powers Selector / CommandPalette. Renders nothing, sets no attrs: caller renders control / listbox / options and wires role, aria-expanded, aria-controls, aria-activedescendant.',
+  paramDescriptions: {
+    options: 'config.',
+    'options.selectableItems':
+      'options in render order; disabled ones not pickable, skipped while moving in open list (ArrowDown/Up opening still lands first / last).',
+    'options.isOpen': 'list shown; caller owns state.',
+    'options.onOpen':
+      'show list; return false to refuse (highlight untouched).',
+    'options.onClose':
+      'hook hides list; resets highlight first. caller closing itself (outside press): also setHighlightedIndex(-1).',
+    'options.listboxId': 'listbox id; option ids derive from it (getItemId).',
+    'options.value':
+      'selected value; w/o search, press / Enter / Space opening highlights it (else first); ArrowDown/Up open on first / last.',
+    'options.onSelect': 'called w/ picked value; picking closes.',
+    'options.onClear':
+      'clears value; Delete / Backspace on closed control. ignored when open or hasSearch.',
+    'options.hasSearch':
+      'list has own search field: Space types, press / Enter opening does not pre-highlight (ArrowDown/Up still first / last), printable keys on closed control -> onSearchSeed.',
+    'options.onSearchSeed':
+      'w/ hasSearch, each printable char except Space typed while control focused (opens first if closed).',
+    'options.isDisabled': 'ignore clicks + keys.',
+  },
+  returnDescriptions: {
+    highlightedIndex:
+      'active option index, -1 = none. hasSearch: press / Enter opening sets none (stays -1 after hook closes); ArrowDown/Up still first / last. name in aria-activedescendant only when it points at a rendered option.',
+    setHighlightedIndex: 'set active option (e.g. after filtering).',
+    getItemId:
+      'id for option at index; aria-activedescendant = isOpen && highlightedIndex >= 0 && highlightedIndex < selectableItems.length ? getItemId(highlightedIndex) : undefined (empty list safe).',
+    onTriggerClick: 'toggle list from a press on control.',
+    onKeyDown:
+      'control keydown: ArrowDown/Up open or move; Enter (Space w/o search) picks or opens; Escape / Tab close; Home / End / PageUp / PageDown jump. editable control keeping Home / End for caret: do not pass them.',
+    onItemSelect: 'pick from a press, then close.',
+    onItemMouseEnter: 'hover makes option active; no scroll, no focus move.',
+  },
+  usage: {
+    description:
+      'Headless single-select combobox: active option + keys, focus stays on control. Caller renders + wires ARIA.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Option id = getItemId(index); aria-activedescendant only while open and highlightedIndex points at a rendered option.',
+      },
+      {
+        guidance: true,
+        description:
+          'Type-to-select w/o search: run useTypeahead first, fall through when it returns false.',
+      },
+      {
+        guidance: true,
+        description: 'Announce result count via useAnnounce on new query.',
+      },
+      {
+        guidance: false,
+        description: 'Move DOM focus onto options; use aria-activedescendant.',
+      },
+    ],
+  },
+};

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.',