@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Switch/Switch.tsx

@@ -44,7 +44,7 @@ import type {InputStatus} from '../Field/types';
 import {Spinner} from '../Spinner';
 import {useTooltip} from '../Tooltip';
 import {mergeProps, mergeRefs, rtlStyles} from '../utils';
-import {switchFocusScope, switchScope} from './switch.markers.stylex';
+import {switchFocusInput, switchScope} from './switch.markers.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
@@ -258,20 +258,22 @@ const styles = stylex.create({
     },
   },
   // The one ring in the system not drawn by focusOutlineStyles. The focusable
-  // input is a sibling of the track, so the condition has to reach the shared
-  // scope marker — and a marker cannot be shared across components without
-  // leaking focus state from an outer one, so it cannot live in the utility.
-  // StyleX also cannot inline a constant imported from another module, so the
-  // values are read from the tokens the utility reads.
+  // input is the track's preceding sibling, so the condition reads that input
+  // through its own marker: a sibling relation, never a `:has()` scan of the
+  // row, which would restyle everything under it on any change. A marker
+  // cannot be shared across components without leaking focus state from an
+  // outer one, so it cannot live in the utility. StyleX also cannot inline a
+  // constant imported from another module, so the values are read from the
+  // tokens the utility reads.
   trackFocus: {
     outline: {
       default: 'none',
-      [stylex.when.ancestor(':has(:focus-visible)', switchFocusScope)]:
+      [stylex.when.siblingBefore(':focus-visible', switchFocusInput)]:
         `${focusVars['--focus-outline-width']} ${focusVars['--focus-outline-style']} ${focusVars['--focus-outline-color']}`,
     },
     outlineOffset: {
       default: null,
-      [stylex.when.ancestor(':has(:focus-visible)', switchFocusScope)]:
+      [stylex.when.siblingBefore(':focus-visible', switchFocusInput)]:
         focusVars['--focus-outline-offset'],
     },
   },
@@ -686,6 +688,7 @@ export function Switch({
           inputSizeStyles[size],
           isDisabled && styles.inputDisabled,
           isBusy && styles.inputBusy,
+          switchFocusInput,
         )}
       />
       <div
@@ -773,7 +776,6 @@ export function Switch({
           isLabelHidden && styles.containerLabelHidden,
           labelSpacing === 'spread' && styles.containerSpread,
           !isDisabled && switchScope,
-          switchFocusScope,
           // The touch press's strength and release live on the row the
           // controller writes to; the track and thumb inherit and paint it.
           !isDisabled && interactionOverlayStyles.pressedAlpha,

package/src/Switch/__tests__/Switch.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y release-only
 
 /**
  * @file Switch.a11y.chromium.spec.ts

package/src/Switch/switch.markers.stylex.ts

@@ -9,6 +9,11 @@ import * as stylex from '@stylexjs/stylex';
 export const switchScope: ReturnType<typeof stylex.defineMarker> =
   stylex.defineMarker();
 
-/** Focus-ring marker; unlike `switchScope`, it stays on while disabled. */
-export const switchFocusScope: ReturnType<typeof stylex.defineMarker> =
+/**
+ * Marks the switch's own focusable input, the track's preceding sibling, so
+ * the track's focus ring follows that input's `:focus-visible` alone. Unlike
+ * `switchScope`, it stays on while disabled (a focusable-disabled switch
+ * still shows the ring).
+ */
+export const switchFocusInput: ReturnType<typeof stylex.defineMarker> =
   stylex.defineMarker();

package/src/TabList/Tab.spec.md

@@ -0,0 +1,201 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Tab
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-27
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility]
+verified_by:
+  [
+    packages/core/src/TabList/TabList.test.tsx,
+    packages/core/src/TabList/__tests__/Tabs.a11y.test.tsx,
+    packages/core/src/TabList/__tests__/Tabs.a11y.chromium.spec.ts,
+    apps/storybook/stories/TabList.stories.tsx,
+  ]
+modules: []
+families: [family:navigation-destinations]
+design_specs: [design:reduced-motion]
+architecture:
+  [
+    architecture:component-style-authoring,
+    architecture:interaction-modality,
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+  ]
+contributing: []
+system_specs: []
+---
+
+# Tab component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                             |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | `Tab` with `value`, `label`, `isLabelHidden`, `href`, `as`, `panelId`, `icon`, `selectedIcon`, and `endContent`; targets `tab` and `tab-indicator` with a `selected` state.                                                                                                          |
+| Behavior                | One TabList entry. In the navigation pattern it is a button or, with `href`, a link marked `aria-current` when selected; in the tabs pattern (`role="tablist"`) it is a `role="tab"` button that controls its panel. The strip has one tab stop, which starts on the selected entry. |
+| End-user impact         | Users select a view or destination; keyboard users meet one tab stop for the whole strip; screen-reader users hear the selected entry and, in the tabs pattern, the panel it controls.                                                                                               |
+| Builder impact          | None.                                                                                                                                                                                                                                                                                |
+| Compatibility/readiness | Records shipped behavior; no public change. Four implementation gaps (see Current-state impact).                                                                                                                                                                                     |
+| Review checks           | Reject more than one tab stop per strip, `aria-current="page"` on a navigation tab, a disabled tab that fires its handler or navigates, or a tabs-pattern tab that renders a link.                                                                                                   |
+| Governing rules         | `component:TabList` (strip edge geometry); `family:navigation-destinations`; `architecture:interaction-modality`.                                                                                                                                                                    |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Tab is one entry in a TabList. It owns its element and role in each TabList
+pattern, its selected and disabled behavior, its icon swap, label sizing, and
+its selection indicator. Consumer usage lives in `Tab.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: selection is the TabList's `value`
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **A hidden label twin reserves the selected width.** Each visible label
+  renders a second, `aria-hidden` copy that reserves the label's selected
+  weight so the tab does not shift. `architecture:component-style-authoring`
+  INV7 has content render once and has CSS size or reserve it on the element
+  that shows it.
+- **Hover decoration is an element.** The hover fill is an `aria-hidden` span
+  rather than a pseudo-element; `architecture:component-style-authoring` INV7
+  has decoration without a semantic role carried by a pseudo-element.
+- **Color transitions under reduced motion.** The label color, hover fill,
+  pressed fill, and indicator fade still animate when reduced motion is
+  requested;
+  `design:reduced-motion` DR3 allows no animated property for a fine pointer.
+- **The `tab` target does not reflect disabled.** A disabled Tab drops its
+  hover and pressed treatment, but the `tab` target reflects only `selected`.
+  `architecture:component-theming-surface` INV6 has a state that changes paint
+  reflected on the owning target.
+
+## Ownership boundary
+
+**Owns**
+
+- The entry element and role per pattern, selection on activation, disabled
+  handling, the tab stop, icon swap, label, end content, and indicator
+  (FR1–FR8).
+
+**Does not own / non-goals**
+
+- Which value is selected, the pattern (`role`), size, layout, arrow-key
+  movement, and overflow scrolling — owned by TabList and uncontracted here;
+  strip edge geometry — owned by `component:TabList`.
+- Destination acceptance and blocking — owned by
+  `family:navigation-destinations`.
+- The panel a tab controls — owned by the caller.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning                                                   | Availability by variant/orientation/state | Default    | Owner   | Stability | Invalid-value behavior |
+| ------- | ----------------------- | --------------------------------------------------------- | ----------------------------------------- | ---------- | ------- | --------- | ---------------------- |
+| Pattern | navigation, tabs        | Set by the TabList `role`; decides element and semantics. | Every tab.                                | navigation | TabList | Stable    | Not settable on Tab.   |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                  | Basis                    |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | In the navigation pattern a Tab is a `<button type="button">`, or with `href` the `as` component, else the `LinkProvider` link, else `<a>`. The selected Tab carries `aria-current="true"`, never `"page"`.                                                                                                                                                | Current source and tests |
+| FR2 | In the tabs pattern a Tab is a `<button>` with `role="tab"`, `aria-selected`, and `aria-controls` from `panelId` (else a caller `aria-controls`). `href` is ignored, and development warnings name an ignored `href`, a missing panel, or a `panelId` outside the tabs pattern.                                                                            | Current source and tests |
+| FR3 | The strip has one tab stop. It starts on the selected Tab (`tabIndex=0`, every other entry `-1`), and moves to whichever entry the arrow keys, Home, or End focus, without selecting it. Where the stop starts when no entry is selected, or the selected one is disabled, is uncontracted here; the Tabs accessibility inventory leaves that policy open. | Current source and tests |
+| FR4 | Activation runs the caller `onClick`, then selects the Tab's `value` through the TabList unless the caller cancelled the event.                                                                                                                                                                                                                            | Current source and tests |
+| FR5 | A Tab with `aria-disabled="true"` does not run `onClick`, does not select, and, as a link, renders a plain `<a>` without `href`; it gets no hover or pressed treatment.                                                                                                                                                                                    | Current source and tests |
+| FR6 | `isLabelHidden` names the Tab by `label` through `aria-label` and hides the text; the visible label reserves its selected (semibold) width so selection does not shift layout. `selectedIcon` replaces `icon` while selected.                                                                                                                              | Current source and tests |
+| FR7 | Every Tab renders an indicator carrying `tab-indicator`, visible only when selected; the root carries `tab` with `selected`. The pressed overlay paints on the tab surface.                                                                                                                                                                                | Current source and tests |
+| FR8 | The root forwards the `ref` and other DOM props, merges `className`, `style`, and `xstyle` after component styles, and paints the shared focus outline.                                                                                                                                                                                                    | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Size and layout.** Height follows the TabList size; `fill` layout
+  stretches Tabs.
+- **AV2 — Theme styling.** Themes restyle `tab` and `tab-indicator` per selected
+  state.
+
+### Representative states
+
+| State             | Required invariant                              | Allowed variation  |
+| ----------------- | ----------------------------------------------- | ------------------ |
+| Navigation button | `aria-current="true"` when selected.            | Icon, end content. |
+| Navigation link   | Link; `aria-current="true"` when selected.      | Router renderer.   |
+| Tabs pattern      | `role="tab"`, `aria-selected`, `aria-controls`. | —                  |
+| Icon only         | Named by `label`.                               | Icon.              |
+| Disabled          | No selection, handler, or navigation.           | Muted styling.     |
+
+### Transformation and precedence order
+
+- **ORD1 — Element.** Tabs pattern → button; else `href` → link (disabled →
+  plain `<a>`); else button.
+- **ORD2 — Controls.** `panelId`, then caller `aria-controls`.
+
+### Performance and resources
+
+- No resource rule.
+
+## Accessibility contract
+
+- **AR1 — Pattern semantics.** FR1 and FR2.
+- **AR2 — One tab stop.** FR3.
+- **AR3 — Names.** Visible label or, when hidden, `aria-label` from `label`.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                   | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Tab              | Icon, label, end content; stable width on selection. | Current source and public docs | Prominent      | FR6                |
+| Indicator        | Selected-only underline.                             | Current source                 | Supporting     | FR7                |
+
+`Tab.doc.mjs` declares no anatomy of its own, so no anatomy-theming map is
+recorded. Edge and indicator geometry across the strip is `component:TabList`
+FR1–FR2.
+
+## Family and system relationships
+
+- TabList supplies pattern, value, size, layout, and keyboard movement;
+  `component:TabList` contracts its edge geometry.
+- `family:navigation-destinations` owns the accept/block decision for `href`.
+
+## Verification map
+
+| Contract | Verification                                                                                                                                      | Representative states             | Mutation or failure expectation                  | Audit section             |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------ | ------------------------- |
+| FR1, FR2 | `TabList.test.tsx` aria-current, polymorphic link, and tabs-pattern tests; `Tabs.a11y.test.tsx`; `Tabs.a11y.chromium.spec.ts` for `aria-selected` | Navigation, link, tabs            | Wrong role or state fails.                       | `audit:Tab/accessibility` |
+| FR3      | `TabList.test.tsx` single tab stop and roving tabindex tests                                                                                      | Selected                          | Extra tab stops, or a wrong starting stop, fail. | `audit:Tab/accessibility` |
+| FR4, FR5 | `TabList.test.tsx` onChange and disabled tests                                                                                                    | Click, disabled button            | Selection when disabled fails.                   | `audit:Tab/behavior`      |
+| FR6, FR7 | `TabList.test.tsx` icon, icon-only, and pressed-overlay tests                                                                                     | Icon, selected icon, hidden label | Wrong icon, name, or overlay fails.              | `audit:Tab/behavior`      |
+
+Read from source, with no focused test yet:
+
+- FR3: the stop moving with arrow, Home, and End focus.
+- FR1: the button's `type="button"`.
+- FR4: the caller `onClick` running first, and its `preventDefault()`
+  cancelling selection.
+- FR5: the absent hover and pressed treatment on a disabled Tab.
+- FR6: the reserved selected-width label.
+- FR7: the `tab` and `tab-indicator` targets and their `selected` state.
+- FR8.
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, or TabList strip
+behavior. It links to their owners.

package/src/TabList/Tab.tsx

@@ -247,6 +247,12 @@ const hoverSizeStyles = stylex.create({
 });
 
 const layoutStyles = stylex.create({
+  // A hugging tab keeps its label's width. Without this the strip's flex
+  // shrinks every tab below its text before overflow can scroll, and on a
+  // narrow screen the labels draw over one another.
+  hug: {
+    flexShrink: 0,
+  },
   fill: {
     flex: 1,
     justifyContent: 'center',
@@ -391,7 +397,7 @@ export function Tab({
         styles.base,
         sizeStyles[size],
         isSelected && styles.selected,
-        isFill && layoutStyles.fill,
+        isFill ? layoutStyles.fill : layoutStyles.hug,
         !isDisabled && tabScope,
         // The touch press's strength and release live on the tab the
         // controller writes to; the hover layer inherits and paints it.

package/src/TabList/TabList.doc.mjs

@@ -115,7 +115,7 @@ export const docs = {
       },
     ],
     description:
-      'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page, with overflow items handled by a built-in "more" menu.',
+      'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page. A strip narrower than its tabs scrolls horizontally and keeps the selected tab in view.',
     bestPractices: [
       { guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
       { guidance: true, description: 'Leave overflow handling on: a strip narrower than its tabs scrolls, and the selected tab is kept in view. Use TabMenu when you want a curated group of extra options rather than a scrolling strip.' },
@@ -138,7 +138,7 @@ export const docs = {
 export const docsZh = {
   usage: {
     description:
-      'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page, with overflow items handled by a built-in "more" menu.',
+      'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page. A strip narrower than its tabs scrolls horizontally and keeps the selected tab in view.',
     bestPractices: [
       { guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
       { guidance: true, description: 'Leave overflow handling on: a strip narrower than its tabs scrolls, and the selected tab is kept in view. Use TabMenu when you want a curated group of extra options rather than a scrolling strip.' },
@@ -162,7 +162,7 @@ export const docsDense = {
   description: 'Tab strip w/ overflow scrolling; nav landmark by default, WAI-ARIA tabs pattern under role="tablist".',
   usage: {
     description:
-      'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page, with overflow items handled by a built-in "more" menu.',
+      'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page. A strip narrower than its tabs scrolls horizontally and keeps the selected tab in view.',
     bestPractices: [
       { guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
       { guidance: true, description: 'Leave overflow handling on: a strip narrower than its tabs scrolls, and the selected tab is kept in view. Use TabMenu when you want a curated group of extra options rather than a scrolling strip.' },

package/src/TabList/TabList.test.tsx

@@ -11,6 +11,7 @@
 
 import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
+import {__resetMenuPressForTest} from '../hooks/useMenuPress';
 import userEvent from '@testing-library/user-event';
 import {
   hasPressedArm,
@@ -734,6 +735,32 @@ describe('TabMenu', () => {
     expect(heading).toHaveTextContent('More');
   });
 
+  it('picks the option a press slid across the menu lifts on, once (family:action-groups FR1, FR2, FR5)', async () => {
+    __resetMenuPressForTest();
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <TabList value="home" onChange={handleChange}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const option = (name: string) =>
+      screen.getByRole('menuitemradio', {name, hidden: true});
+    for (const pointer of [
+      {pointerType: 'touch', pointerId: 1},
+      {pointerType: 'mouse', pointerId: 2, button: 0},
+    ]) {
+      handleChange.mockClear();
+      fireEvent.pointerDown(option('Analytics'), pointer);
+      fireEvent.pointerMove(option('Reports'), pointer);
+      fireEvent.pointerUp(option('Reports'), pointer);
+      expect(handleChange).toHaveBeenCalledTimes(1);
+      expect(handleChange).toHaveBeenCalledWith('reports');
+    }
+  });
+
   it('selects a menu item and calls onChange', async () => {
     const user = userEvent.setup();
     const handleChange = vi.fn();

package/src/TabList/TabMenu.spec.md

@@ -0,0 +1,198 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:TabMenu
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-27
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility]
+verified_by:
+  [
+    packages/core/src/TabList/TabList.test.tsx,
+    apps/storybook/stories/TabList.stories.tsx,
+  ]
+modules: []
+families: [family:overlay-dismissal, family:action-groups]
+design_specs: [design:reduced-motion]
+architecture:
+  [
+    architecture:component-style-authoring,
+    architecture:interaction-modality,
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+  ]
+contributing: []
+system_specs: []
+---
+
+# TabMenu component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                           |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `TabMenu` with `label` and `options` (`{value, label, icon?}`); targets `tab-menu`, `tab-menu-dropdown`, and `tab-menu-item`, plus `tab-indicator` when an option is selected.     |
+| Behavior                | A TabList entry that groups several tab values behind a menu button. Its label shows the selected option, else `label`; choosing an option selects that value and closes the menu. |
+| End-user impact         | Users reach overflow tab values from one entry and see which one is selected; keyboard users get APG menu-button behavior with a single tab stop inside the menu.                  |
+| Builder impact          | None.                                                                                                                                                                              |
+| Compatibility/readiness | Records shipped behavior; no public change. Six implementation gaps (see Current-state impact).                                                                                    |
+| Review checks           | Reject options without `menuitemradio` and `aria-checked`, more than one tab stop in the open menu, or a closed menu that leaves focus stranded.                                   |
+| Governing rules         | `component:TabList` (strip edge geometry); `family:overlay-dismissal`; `architecture:interaction-modality`.                                                                        |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+TabMenu is a TabList entry that holds several tab values in a menu. It owns its
+trigger, the option menu, and how choosing an option selects a value. Consumer
+usage lives in `TabMenu.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: selection is the TabList's `value`; the
+  menu's open state is internal
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **A hidden label twin reserves the selected width.** The trigger's visible
+  label renders a second, `aria-hidden` copy that reserves the label's selected
+  weight. `architecture:component-style-authoring` INV7 has content render once
+  and has CSS size or reserve it on the element that shows it.
+- **Hover decoration is an element.** The trigger's hover fill is an
+  `aria-hidden` span rather than a pseudo-element;
+  `architecture:component-style-authoring` INV7 has decoration without a
+  semantic role carried by a pseudo-element.
+- **The open menu repeats the label.** The menu's heading repeats `label`,
+  which the trigger also shows while no option is selected, so that text
+  renders twice while the menu is open. `architecture:component-style-authoring`
+  INV7 has content render once.
+- **Motion under reduced motion.** The chevron's turn and the trigger and item
+  color and fill transitions still animate when reduced motion is requested;
+  `design:reduced-motion` DR1–DR3 allow no travel and, for a fine pointer, no
+  animated property.
+- **The `tab-menu` and `tab-menu-item` targets reflect no state.** The trigger
+  takes selected styling and a checked option takes medium weight, but neither
+  target reflects a state. `architecture:component-theming-surface` INV6 has a
+  state that changes paint reflected on the owning target.
+- **Selection mounts extra elements.** The trigger mounts its `tab-indicator`
+  only while an option is selected, and an option mounts its check mark only
+  while checked. `architecture:component-style-authoring` INV7 has states
+  expressed through attributes, classes, and styles on existing elements, never
+  through extra elements.
+
+## Ownership boundary
+
+**Owns**
+
+- The trigger, its label and tab stop, the option menu, and selection from it
+  (FR1–FR6).
+
+**Does not own / non-goals**
+
+- Selected value, size, and strip keyboard movement — owned by TabList and
+  uncontracted here; strip edge geometry — owned by `component:TabList`.
+- Popover hosting and light dismiss — owned by the shared popover and layer
+  runtime; Escape ordering — owned by `family:overlay-dismissal`.
+
+## Public concepts
+
+No component-local concept beyond the consumer props.
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Basis                    |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | The trigger is a `<button>` with `aria-haspopup="menu"`, `aria-expanded`, and `aria-controls` naming the menu; its props type omits `role`, and caller props cannot set its tab index or popup attributes. It carries `tab-menu` and forwards `ref` and other DOM props.                                                                                                                                                                                                                                  | Current source and tests |
+| FR2 | The trigger shows the label of the option whose value is selected, else `label`, reserving semibold width; when an option is selected it uses selected styling and shows the selected indicator. It takes part in the strip's single tab stop like a Tab (`component:Tab` FR3): it starts as the stop when one of its options is selected, and the stop moves with arrow-key focus; where the stop starts when nothing in the strip is selected, or the selected entry is disabled, is uncontracted here. | Current source and tests |
+| FR3 | Clicking the trigger toggles a non-modal popover below it and, on open, focuses the first option; a caller `onClick` runs after the toggle.                                                                                                                                                                                                                                                                                                                                                               | Current source and tests |
+| FR4 | The menu is a `role="menu"` named by `label`, carrying `tab-menu-dropdown`, with a presentational heading repeating `label`, then one `role="menuitemradio"` per option with `aria-checked` for the selected value, an optional icon, and a check mark when selected.                                                                                                                                                                                                                                     | Current source and tests |
+| FR5 | Inside the menu one option is a tab stop, and ArrowUp, ArrowDown, Home, and End move it; ArrowLeft and ArrowRight are left to the strip; Enter, Space, or click on an option selects its value through the TabList and closes the menu; Escape and Tab close it. Closing returns focus to the trigger.                                                                                                                                                                                                    | Current source and tests |
+| FR6 | The trigger and options paint the shared focus outline.                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Current source           |
+| FR7 | In the open menu, a press (finger, pen or mouse) that lands on an option and slides across the options picks the one it lifts on, once, through that option's own activation, with the highlight following the pointer; a lift outside acts on nothing, and a mouse released outside closes the menu. The menu adopts `module:DropdownMenu/useMenuPress` for this (`family:action-groups` FR1–FR5; `module:DropdownMenu/useMenuPress` DEC-7). Keyboard and assistive-technology behavior is unchanged.    | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Options.** Any number of options, each with an optional icon.
+
+### Representative states
+
+| State              | Required invariant                                                                                                                                                                                  | Allowed variation |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| No option selected | Trigger shows `label`; while another enabled entry is selected it is not the starting stop (Tab FR3); with nothing selected, or the selected entry disabled, where the stop starts is uncontracted. | —                 |
+| Option selected    | Trigger shows that option's label and indicator.                                                                                                                                                    | —                 |
+| Open               | Named menu; first option focused; one tab stop.                                                                                                                                                     | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Trigger label.** Selected option's label, then `label`.
+
+### Performance and resources
+
+- No resource rule.
+
+## Accessibility contract
+
+- **AR1 — Menu button.** FR1 and FR5 follow the APG menu-button pattern.
+- **AR2 — Radio options.** Options are `menuitemradio` with `aria-checked`.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                    | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Trigger          | Tab-styled button with chevron and indicator.         | Current source and public docs | Prominent      | FR2                |
+| Menu             | Heading, then options with a check mark on selection. | Current source                 | Supporting     | FR4                |
+
+`TabMenu.doc.mjs` declares no anatomy of its own, so no anatomy-theming map is
+recorded.
+
+## Family and system relationships
+
+- TabList supplies value, size, and the strip; `component:TabList` contracts
+  its edge geometry.
+- `family:overlay-dismissal` owns shared Escape ordering.
+
+## Verification map
+
+| Contract | Verification                                                       | Representative states                             | Mutation or failure expectation              | Audit section                 |
+| -------- | ------------------------------------------------------------------ | ------------------------------------------------- | -------------------------------------------- | ----------------------------- |
+| FR1, FR3 | `TabList.test.tsx` TabMenu and host-attribute tests                | Closed, open                                      | Lost popup attributes fail.                  | `audit:TabMenu/accessibility` |
+| FR2, FR4 | `TabList.test.tsx` TabMenu label, heading, and menuitemradio tests | Selected and unselected                           | Wrong label or missing `aria-checked` fails. | `audit:TabMenu/behavior`      |
+| FR5      | `TabList.test.tsx` TabMenu keyboard navigation tests               | ArrowUp, ArrowDown, Home, End, Tab, Escape, Enter | Extra tab stops or a menu left open fails.   | `audit:TabMenu/accessibility` |
+| FR7      | `TabList.test.tsx` TabMenu suite (touch and mouse slides)          | Touch and mouse slides across options             | Removing the adoption fails the slide tests. | —                             |
+
+Read from source, with no focused test yet:
+
+- FR1: the `tab-menu` target, the forwarded `ref`, and owned attributes winning
+  over caller props.
+- FR2: the reserved semibold width, the selected styling and indicator, and the
+  trigger's part in the strip's tab stop.
+- FR3: the popover's placement, focus moving to the first option on open, and
+  the caller `onClick` running after the toggle.
+- FR4: the `tab-menu-dropdown` and `tab-menu-item` targets, option icons, and
+  the check mark.
+- FR3: a second click closing the menu.
+- FR5: Space selecting, the menu closing on selection, ArrowLeft and ArrowRight
+  left to the strip, and focus returning to the trigger on close.
+- FR6.
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, or TabList strip
+behavior. It links to their owners.

package/src/TabList/TabMenu.tsx

@@ -34,6 +34,9 @@ import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {usePopover} from '../Popover/usePopover';
 import {MENU_ITEM_SELECTOR} from '../DropdownMenu/menuItemRoles';
 import {useListFocus} from '../hooks/useListFocus';
+import {useMenuPress} from '../hooks/useMenuPress';
+import {menuTouchActionStyles} from '../DropdownMenu/menuTouchAction.stylex';
+import {useMenuOverflow} from '../DropdownMenu/useMenuOverflow';
 import {useTabListContext} from './TabListContext';
 import type {TabListSize} from './TabListContext';
 import {tabScope} from './tab.markers.stylex';
@@ -74,6 +77,8 @@ export interface TabMenuProps extends Omit<
 const styles = stylex.create({
   trigger: {
     position: 'relative',
+    // Keeps its label's width in a strip that scrolls, as a hugging tab does.
+    flexShrink: 0,
     display: 'inline-flex',
     alignItems: 'center',
     justifyContent: 'center',
@@ -170,6 +175,8 @@ const styles = stylex.create({
     transform: 'rotate(180deg)',
   },
   dropdown: {
+    // A held pointer slides across the items; it selects no text.
+    userSelect: 'none',
     display: 'flex',
     flexDirection: 'column',
     gap: spacingVars['--spacing-0-5'],
@@ -300,6 +307,16 @@ export function TabMenu({
     onEscape: () => popover.hide(),
   });
 
+  // A press that slides across the options picks the one it lifts on, the
+  // highlight following the pointer, as DropdownMenu's does
+  // (`family:action-groups` FR1-FR3, FR5); a mouse released outside closes it.
+  const menuPress = useMenuPress({
+    menuRef: listRef,
+    itemSelector: MENU_ITEM_SELECTOR,
+    onDismiss: popover.hide,
+  });
+  const hasOverflow = useMenuOverflow(listRef, options.length, popover.isOpen);
+
   const handleToggle = useCallback(() => {
     if (popover.isOpen) {
       popover.hide();
@@ -402,11 +419,17 @@ export function TabMenu({
           id={menuId}
           role="menu"
           aria-label={label}
+          {...menuPress.menuProps}
           onKeyDown={handleMenuKeyDown}
           onFocus={handleFocus}
           {...mergeProps(
             themeProps('tab-menu-dropdown'),
-            stylex.props(styles.dropdown),
+            stylex.props(
+              styles.dropdown,
+              hasOverflow
+                ? menuTouchActionStyles.scrolls
+                : menuTouchActionStyles.fits,
+            ),
           )}>
           <span role="presentation" {...stylex.props(styles.menuHeading)}>
             {label}