@astryxdesign/core 0.7.3-canary.b74cf21 → 0.7.3-canary.ca48bb7

package/src/Tooltip/__tests__/Tooltip.a11y.states.ts

@@ -0,0 +1,132 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tooltip.a11y.states.ts
+ * @input Tooltip's and useTooltip's representative states and the facts TOOLTIP_PATTERN reads
+ * @output TOOLTIP_BINDING_STATES and the explicit ownership exclusions for this binding
+ * @position Binding inventory shared by the jsdom test and the Chromium spec (Tooltip and useTooltip under spec:AST-020 FR15)
+ */
+
+import type {TooltipStateFacts} from '@astryxdesign/a11y-spec';
+
+/**
+ * How the caller attaches the tooltip: wrapping an element, wrapping plain
+ * text, pointing `anchorRef` at its own element, or calling `useTooltip`.
+ */
+export type TooltipAttachment =
+  'wrapped-element' | 'text' | 'anchor-ref' | 'hook';
+
+export interface TooltipBindingState {
+  readonly id: string;
+  readonly summary: string;
+  readonly storyId: string;
+  readonly attachment: TooltipAttachment;
+  /**
+   * The trigger's visible text. A `button` trigger is also named by it; a
+   * text trigger has no role, so the lanes find it by this text.
+   */
+  readonly triggerText: string;
+  readonly triggerRole: 'button' | null;
+  /** The tooltip `content`. */
+  readonly content: string;
+  /** A visible hint the trigger is already described by, besides the tooltip. */
+  readonly hint?: string;
+  readonly facts: TooltipStateFacts;
+}
+
+const story = (id: string) => `a11y-tooltip--${id}`;
+
+/** Tooltip's and useTooltip's default hover delay. */
+const DEFAULT_DELAY: TooltipStateFacts = {showsOnHover: true, showDelayMs: 200};
+
+export const TOOLTIP_BINDING_STATES = [
+  {
+    id: 'wrapped-button',
+    summary:
+      'a Tooltip wrapping a Button, which attaches to the Button and describes it',
+    storyId: story('wrapped-button'),
+    attachment: 'wrapped-element',
+    triggerText: 'Save',
+    triggerRole: 'button',
+    content: 'Saves your changes to this draft',
+    facts: DEFAULT_DELAY,
+  },
+  {
+    id: 'text-trigger',
+    summary:
+      'a Tooltip wrapping plain text, which renders its own focusable inline trigger',
+    storyId: story('text-trigger'),
+    attachment: 'text',
+    triggerText: 'Draft',
+    triggerRole: null,
+    content: 'Only you can see a draft',
+    facts: DEFAULT_DELAY,
+  },
+  {
+    id: 'anchor-ref-with-hint',
+    summary:
+      'a Tooltip attached through anchorRef to a caller button that is already described by a visible hint, so the trigger is described by both',
+    storyId: story('anchor-ref-with-hint'),
+    attachment: 'anchor-ref',
+    triggerText: 'Publish',
+    triggerRole: 'button',
+    content: 'Makes this page visible to everyone',
+    hint: 'Last published yesterday',
+    facts: DEFAULT_DELAY,
+  },
+  {
+    id: 'use-tooltip-hook',
+    summary:
+      "useTooltip on a caller button, which spreads the hook's ref and describedBy onto it and renders the tooltip",
+    storyId: story('use-tooltip-hook'),
+    attachment: 'hook',
+    triggerText: 'Archive',
+    triggerRole: 'button',
+    content: 'Moves this page out of the list',
+    facts: DEFAULT_DELAY,
+  },
+] as const satisfies ReadonlyArray<TooltipBindingState>;
+
+export const TOOLTIP_EXCLUSIONS = [
+  {
+    id: 'focus-trigger',
+    owner:
+      "the 24 core hosts that pass focusTrigger 'always' — the disabledMessage tooltips on the field and choice controls (TextInput, TextArea, NumberInput, Switch, CheckboxInput, CheckboxList, RadioList, Selector, MultiSelector, SegmentedControl, Slider, Typeahead, Tokenizer, FileInput, and the date and time inputs), the Slider value bubble and ProgressBar marks — each through its own suite (for example TextInput.test.tsx 'shows the reason tooltip on keyboard focus'); and any caller that passes 'never'",
+    reason:
+      "'always' attaches the focus listeners to a wrapper that is not itself focusable, so focusin bubbling from the control inside it shows the hint; the described element and the focused element differ, which this contract's trigger-centred rows do not model, so each host proves its own keyboard path. 'never' detaches focus showing for a trigger inside a composite widget that moves focus itself, which then owns how a keyboard user reaches the hint; no shipped composition uses it. Every state here uses the default 'auto'.",
+  },
+  {
+    id: 'touch-trigger',
+    owner:
+      'useTooltip.test.tsx and Tooltip.test.tsx (touchTrigger suites) through the shared useTouchTrigger hook',
+    reason:
+      'On a touch pointer there is no hover, so a tap opens the tooltip or leaves it to the control the tap operates; the APG defines no touch behaviour, and the Chromium lane drives a mouse and a keyboard only.',
+  },
+  {
+    id: 'controlled-and-disabled',
+    owner:
+      'Tooltip.test.tsx and useTooltip.test.tsx (isOpen, isDefaultOpen and isEnabled suites)',
+    reason:
+      'A controlled tooltip answers Escape by reporting instead of hiding, and a disabled one never shows; both hand visibility to the caller, so the hover and focus outcomes this contract reads belong to the uncontrolled, enabled tooltip every state renders.',
+  },
+  {
+    id: 'interactive-hover-content',
+    owner: 'the HoverCard binding and the overlay-dismissal family',
+    reason:
+      'Hover content a user can interact with is a non-modal dialog, not a tooltip, so HoverCard and other interactive popovers are reviewed separately; no state here places a focusable control inside a tooltip.',
+  },
+  {
+    id: 'host-compositions',
+    owner:
+      "the composing components' own contracts (Button for the IconButton label tooltip, the input status binding for useInputStatusIcon, which renders the on-field status tooltip) and their tests",
+    reason:
+      'IconButton, useInputStatusIcon and Lab InfoTip render Tooltip or useTooltip for their own purposes; this binding proves the tooltip they render, and what each host adds around it is that host.',
+  },
+  {
+    id: 'placement-and-paint',
+    owner:
+      'Tooltip.test.tsx (placement and alignment), the layer runtime anchor tests, and the repository visual gate',
+    reason:
+      'Placement, alignment, the inverted surface and the hover underline on a text trigger are layout and paint; they change no role, description, focus or dismissal outcome, so every state uses the default placement.',
+  },
+] as const;

package/src/Tooltip/__tests__/Tooltip.a11y.test.tsx

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file Tooltip.a11y.test.tsx
+ * @input TOOLTIP_PATTERN bound to Tooltip's and useTooltip's representative states
+ * @output jsdom-lane proof of the DOM expectations and an honest "unrun" report for the browser layers
+ * @position Binding test for Tooltip and useTooltip (the Chromium spec covers the rest)
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+  TOOLTIP_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {renderTooltipState} from './Tooltip.a11y.renders';
+import {
+  TOOLTIP_BINDING_STATES,
+  TOOLTIP_EXCLUSIONS,
+  type TooltipBindingState,
+} from './Tooltip.a11y.states';
+
+function triggerFor(state: TooltipBindingState): HTMLElement {
+  return state.triggerRole == null
+    ? screen.getByText(state.triggerText, {exact: true})
+    : screen.getByRole(state.triggerRole, {name: state.triggerText});
+}
+
+function relatedFor(): Readonly<Record<string, Element>> {
+  return {
+    // The tooltip stays in the page while hidden; it is found with hidden
+    // elements included so the DOM rows can read it before it shows.
+    tooltip: screen.getByRole('tooltip', {hidden: true}),
+    before: screen.getByRole('button', {name: 'Before the trigger'}),
+    after: screen.getByRole('button', {name: 'After the trigger'}),
+  };
+}
+
+async function checkState(state: TooltipBindingState): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: TOOLTIP_PATTERN,
+    binding: 'Tooltip',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      render(renderTooltipState(state));
+      return createJsdomHarness({
+        subject: triggerFor(state),
+        related: relatedFor(),
+      });
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('Tooltip — tooltip pattern, jsdom lane', () => {
+  it.each(
+    TOOLTIP_BINDING_STATES.map(
+      state => [state.id, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: TOOLTIP_PATTERN,
+      binding: 'Tooltip',
+      state: state.id,
+      facts: state.facts,
+      render: () => {
+        render(renderTooltipState(state));
+      },
+      subject: () => triggerFor(state),
+      related: () => relatedFor(),
+      cleanup,
+    });
+  });
+
+  it('runs the DOM layer and reports the browser-owned outcomes as unrun', async () => {
+    const results: BindingResult[] = [];
+    for (const state of TOOLTIP_BINDING_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(TOOLTIP_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('tooltip binding inventory', () => {
+  it('gives every representative state a distinct checked-in story', () => {
+    const stories = TOOLTIP_BINDING_STATES.map(state => state.storyId);
+    expect(new Set(stories).size).toBe(stories.length);
+  });
+
+  it('keeps focus-trigger opt-outs, touch, controlled visibility, interactive hover content, host compositions and paint explicit', () => {
+    expect(TOOLTIP_EXCLUSIONS.map(row => row.id)).toEqual([
+      'focus-trigger',
+      'touch-trigger',
+      'controlled-and-disabled',
+      'interactive-hover-content',
+      'host-compositions',
+      'placement-and-paint',
+    ]);
+    for (const exclusion of TOOLTIP_EXCLUSIONS) {
+      expect(exclusion.owner.length, exclusion.id).toBeGreaterThan(20);
+      expect(exclusion.reason.length, exclusion.id).toBeGreaterThan(80);
+    }
+  });
+
+  it('renders the trigger, one tooltip and both page buttons for every state', () => {
+    for (const state of TOOLTIP_BINDING_STATES) {
+      render(renderTooltipState(state));
+      expect(triggerFor(state), state.id).toBeTruthy();
+      expect(
+        screen.getAllByRole('tooltip', {hidden: true}),
+        state.id,
+      ).toHaveLength(1);
+      expect(Object.keys(relatedFor())).toEqual(['tooltip', 'before', 'after']);
+      cleanup();
+    }
+  });
+});

package/src/TopNav/TopNav.tsx

@@ -94,10 +94,18 @@ const styles = stylex.create({
     padding: spacingVars['--spacing-2'],
     boxSizing: 'border-box',
   },
+  // The heading gives up space first so the end content and toggle stay in view
+  mobileBarHeading: {
+    display: 'flex',
+    alignItems: 'center',
+    flex: '0 1 auto',
+    minWidth: 0,
+  },
   mobileBarEnd: {
     display: 'flex',
     alignItems: 'center',
     gap: spacingVars['--spacing-1'],
+    flexShrink: 0,
     marginInlineStart: 'auto',
   },
   // Drawer mode — vertical list of nav items
@@ -215,7 +223,9 @@ export function TopNav({
           style,
         )}
         {...props}>
-        {heading && <div {...stylex.props(styles.heading)}>{heading}</div>}
+        {heading && (
+          <div {...stylex.props(styles.mobileBarHeading)}>{heading}</div>
+        )}
         <div {...stylex.props(styles.mobileBarEnd)}>
           {endContent}
           {hasMobileDrawerContent && hasAutoToggle && <MobileNavToggle />}

package/src/TopNav/TopNavHeading.tsx

@@ -52,6 +52,7 @@ const styles = stylex.create({
     alignItems: 'center',
     gap: spacingVars['--spacing-2'],
     minHeight: spacingVars['--spacing-8'],
+    minWidth: 0,
     paddingInlineStart: {
       default: spacingVars['--spacing-2'],
       ':has(.astryx-nav-icon)': 0,

package/src/TopNav/__tests__/TopNavMobileLongHeading.a11y.chromium.spec.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TopNavMobileLongHeading.a11y.chromium.spec.ts
+ * @input The `Core/AppShell` Long Heading On Mobile story in a built Storybook
+ *   at a 320px phone viewport.
+ * @output Real-engine proof that a long TopNav heading gives way on a narrow
+ *   screen: the menu toggle stays inside the compact bar, and the drawer's
+ *   close button stays inside the drawer.
+ * @position Run with `pnpm test:a11y-contract`. jsdom has no layout, so where
+ *   the toggle lands is only observable here.
+ */
+
+import {expect, test, type Locator} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+const STORY = 'core-appshell--long-heading-on-mobile';
+
+async function boxOf(locator: Locator) {
+  const box = await locator.boundingBox();
+  if (box == null) {
+    throw new Error('the element has no layout box');
+  }
+  return box;
+}
+
+test('a long heading keeps the menu toggle and the drawer close button on screen', async ({
+  page,
+}) => {
+  await page.setViewportSize({width: 320, height: 568});
+  await page.goto(`${storybook.origin}/iframe.html?id=${STORY}&viewMode=story`);
+
+  const bar = page.getByRole('navigation', {name: 'Main navigation'});
+  const toggle = page.getByRole('button', {name: 'Open navigation'});
+  await expect(toggle).toBeVisible();
+
+  const barBox = await boxOf(bar);
+  const toggleBox = await boxOf(toggle);
+  expect(toggleBox.x).toBeGreaterThanOrEqual(barBox.x);
+  expect(toggleBox.x + toggleBox.width).toBeLessThanOrEqual(
+    barBox.x + barBox.width,
+  );
+
+  await toggle.click();
+
+  const drawer = page.getByRole('dialog', {name: 'Navigation'});
+  const close = drawer.getByRole('button', {name: 'Close navigation'});
+  await expect(close).toBeVisible();
+
+  // The drawer slides in from the inline end; measure once it has settled.
+  await expect(close).toBeInViewport({ratio: 1});
+  const drawerBox = await boxOf(drawer);
+  const closeBox = await boxOf(close);
+  expect(closeBox.x).toBeGreaterThanOrEqual(drawerBox.x);
+  expect(closeBox.x + closeBox.width).toBeLessThanOrEqual(
+    drawerBox.x + drawerBox.width,
+  );
+});

package/src/TreeList/TreeList.test.tsx

@@ -942,6 +942,34 @@ describe('TreeList', () => {
         expect(screen.queryByText('File')).not.toBeInTheDocument();
       });
 
+      it("exposes a disabled row's toggle and action as aria-disabled and keeps them inert", () => {
+        const onClick = vi.fn();
+        const {container} = render(
+          <TreeList
+            items={underRoot([
+              {id: 'run', label: 'Run', onClick, isDisabled: true},
+              {...folder, isDisabled: true},
+            ])}
+          />,
+        );
+        // spec:AST-085 FR1/FR2: no native disabled anywhere, and a click
+        // dispatched straight on the inner controls does nothing.
+        expect(container.querySelector('[disabled]')).toBeNull();
+        const toggle = container.querySelector<HTMLElement>(
+          '[data-tree-toggle][aria-disabled="true"]',
+        )!;
+        expect(toggle).not.toBeNull();
+        toggle.click();
+        fireEvent.keyDown(toggle, {key: 'Enter'});
+        expect(screen.queryByText('File')).not.toBeInTheDocument();
+        const action = Array.from(container.querySelectorAll('button')).find(
+          button => button.textContent?.includes('Run'),
+        )!;
+        expect(action).toHaveAttribute('aria-disabled', 'true');
+        action.click();
+        expect(onClick).not.toHaveBeenCalled();
+      });
+
       it('leaves a role-based control in start or end content to itself', () => {
         // Native and role-based controls alike keep their own activation,
         // the same rule link rows get from the shared enlarged-surface hook.

package/src/TreeList/TreeListItem.tsx

@@ -38,6 +38,7 @@ import {TreeListBranches} from './TreeListBranches';
 import type {TreeListDensity, TreeListVariant} from './TreeListTypes';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
+import {disabledInteractionProps} from '../utils/disabledInteraction';
 
 // =============================================================================
 // Styles
@@ -552,11 +553,13 @@ export function TreeListItem({
         // Stable identity for TreeList's activateItem selector — do not
         // remove without also updating TreeList.tsx.
         data-tree-toggle=""
-        disabled={isDisabled}
+        // Disabled stays focusable (spec:AST-085 FR1) but inert (FR2).
+        aria-disabled={isDisabled || undefined}
         // Roving tabindex lives on the treeitem row; the chevron toggle is not
         // a separate tab stop. Row-level Enter/Space forwards to this button.
         tabIndex={-1}
         onClick={handleToggle}
+        {...(isDisabled ? disabledInteractionProps() : null)}
         {...mergeProps(
           // Stable theme target for the expand/collapse control. `data-tree-toggle`
           // stays as the functional activation hook; this adds a themeable
@@ -608,7 +611,8 @@ export function TreeListItem({
         <button
           type="button"
           onClick={onClick}
-          disabled={isDisabled}
+          aria-disabled={isDisabled || undefined}
+          {...(isDisabled ? disabledInteractionProps() : null)}
           aria-labelledby={labelId}
           aria-describedby={description != null ? descriptionId : undefined}
           // Roving tabindex lives on the treeitem row; inner action is not a

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

@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DisabledTriggerFocus.a11y.chromium.spec.ts
+ * @input The `a11y/Disabled trigger focus` stories in a built Storybook.
+ * @output Real-engine proof of `spec:AST-085` FR4 for Selector and
+ *   ComplexSelector: a trigger disabled while it holds keyboard focus keeps
+ *   focus and reports itself disabled.
+ * @position Run in `pr-a11y`; a DOM emulator does not move focus off an
+ *   element that becomes disabled, so it cannot show the loss.
+ */
+
+import {expect, test} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+const CASES = [
+  {
+    storyId: 'a11y-disabled-trigger-focus--selector-trigger',
+    role: 'combobox',
+    name: 'Fruit',
+  },
+  {
+    storyId: 'a11y-disabled-trigger-focus--complex-selector-trigger',
+    role: 'button',
+    name: 'View options',
+  },
+] as const;
+
+for (const {storyId, role, name} of CASES) {
+  test(`${name}: a focused trigger keeps focus when it becomes disabled`, async ({
+    page,
+  }) => {
+    await page.goto(
+      `${storybook.origin}/iframe.html?id=${storyId}&viewMode=story`,
+    );
+    const trigger = page.getByRole(role, {name});
+    await trigger.focus();
+    await expect(trigger).toBeFocused();
+
+    await page.evaluate(id => {
+      const channel = (
+        window as unknown as {
+          __STORYBOOK_ADDONS_CHANNEL__?: {
+            emit: (event: string, payload: unknown) => void;
+          };
+        }
+      ).__STORYBOOK_ADDONS_CHANNEL__;
+      if (channel == null) {
+        throw new Error('Storybook channel is unavailable');
+      }
+      channel.emit('updateStoryArgs', {
+        storyId: id,
+        updatedArgs: {isDisabled: true},
+      });
+    }, storyId);
+
+    // Wait for the disabled re-render in either form, so focus is checked
+    // after it lands.
+    await expect
+      .poll(async () =>
+        trigger.evaluate(
+          el =>
+            el.hasAttribute('disabled') ||
+            el.getAttribute('aria-disabled') === 'true',
+        ),
+      )
+      .toBe(true);
+    await expect(trigger).toBeFocused();
+  });
+}

package/src/hooks/useGridFocus.ts

@@ -298,7 +298,22 @@ export function useGridFocus<T extends HTMLElement = HTMLElement>(
     for (const el of targets) {
       setTabIndex(el, el === tabbable ? 0 : -1);
     }
-  }, [getFocusTargets, setTabIndex]);
+    // A cell that stopped being focusable (an aria-disabled day, for example,
+    // which stays reachable by focus) can still hold the stop from earlier
+    // navigation; it never stays tabbable, so the grid keeps one Tab stop.
+    for (const cell of getCells()) {
+      const el = cellFocusable(cell) ? null : resolveFocusTarget(cell);
+      if (el != null) {
+        setTabIndex(el, -1);
+      }
+    }
+  }, [
+    getFocusTargets,
+    getCells,
+    cellFocusable,
+    resolveFocusTarget,
+    setTabIndex,
+  ]);
 
   // Keep the tab stop valid across renders (cells added/removed, focusability
   // toggled). Runs after every commit but only when roving tabindex is on.

package/src/hooks/useMenuPress.ts

@@ -36,7 +36,9 @@
  *
  * The menu root is marked `data-astryx-menu-press` so a nested flyout (a DOM
  * descendant of its parent menu) can tell which level owns a press, and so a
- * surface can be recognised as carrying this model.
+ * surface can be recognised as carrying this model. A menu the root renders
+ * beside itself names the root with `data-astryx-menu-press-surface` and counts
+ * as nested in it.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
@@ -60,6 +62,14 @@ import {useLongPress, type UseLongPressHandlers} from './useLongPress';
 /** Marks a menu root that carries this press model. */
 export const MENU_PRESS_MARKER = 'data-astryx-menu-press';
 const MENU_PRESS_ROOT_SELECTOR = `[${MENU_PRESS_MARKER}]`;
+/**
+ * Carried by a menu root that another root renders beside itself rather than
+ * inside it, naming that root's `id`: the menu of a sub-menu with a header or
+ * footer, in a dialog beside the root's menu, is nested in that root for the
+ * press model, as a flyout inside the root's DOM is. Nothing else beside the
+ * root carries it, so a picker placed in a header or footer stays its own root.
+ */
+export const MENU_PRESS_SURFACE_ATTR = 'data-astryx-menu-press-surface';
 
 /** How long after a tracked release the browser's click is still swallowed. */
 export const MENU_PRESS_STRAY_CLICK_MS = 400;
@@ -246,16 +256,44 @@ function isRowFocusable(row: HTMLElement): boolean {
 function getOutermostRoot(menu: HTMLElement): HTMLElement {
   let root = menu;
   for (;;) {
-    const parent = root.parentElement?.closest<HTMLElement>(
-      MENU_PRESS_ROOT_SELECTOR,
-    );
-    if (parent == null) {
+    const parent =
+      root.parentElement?.closest<HTMLElement>(MENU_PRESS_ROOT_SELECTOR) ??
+      getSurfaceOwner(root);
+    if (parent == null || parent === root) {
       return root;
     }
     root = parent;
   }
 }
 
+/**
+ * The menu root that renders `menu` beside itself, if any (see
+ * `MENU_PRESS_SURFACE_ATTR`). Read off the menu itself, never an ancestor, so
+ * a root placed in a region of that surface is not adopted.
+ */
+function getSurfaceOwner(menu: HTMLElement): HTMLElement | null {
+  const ownerId = menu.getAttribute(MENU_PRESS_SURFACE_ATTR);
+  if (!ownerId) {
+    return null;
+  }
+  const owner = menu.ownerDocument.getElementById(ownerId);
+  return owner?.matches(MENU_PRESS_ROOT_SELECTOR) === true ? owner : null;
+}
+
+/**
+ * Whether `element` is inside the menu tree whose outermost root is `root`:
+ * inside the root itself, or inside a menu nested in it through a surface
+ * the root renders beside itself. Anything else in such a surface (a header
+ * field, say) is outside the menu, as the root's own regions are.
+ */
+function isInMenuTree(element: Element, root: HTMLElement): boolean {
+  if (root.contains(element)) {
+    return true;
+  }
+  const owner = element.closest<HTMLElement>(MENU_PRESS_ROOT_SELECTOR);
+  return owner != null && getOutermostRoot(owner) === root;
+}
+
 interface ResolvedPoint {
   row: HTMLElement | null;
   isInMenu: boolean;
@@ -332,14 +370,14 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
       }
       const root = menu == null ? null : getOutermostRoot(menu);
       const isInMenu =
-        root != null && element != null && root.contains(element);
+        root != null && element != null && isInMenuTree(element, root);
       const trigger = triggerRef?.current ?? null;
       const isOnTrigger =
         trigger != null && element != null && trigger.contains(element);
       let row: HTMLElement | null = null;
       if (isInMenu && element != null) {
         row = element.closest<HTMLElement>(itemSelector);
-        if (row != null && !root.contains(row)) {
+        if (row != null && !isInMenuTree(row, root)) {
           row = null;
         }
       }

package/src/utils/disabledInteraction.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file disabledInteraction.ts
+ * @input An optional caller keydown handler
+ * @output Event props that keep a focusable, aria-disabled control inert
+ * @position Shared by controls that replace native `disabled` with
+ *   `aria-disabled` under spec:AST-085 (FR1, FR2)
+ */
+
+import type {KeyboardEvent, KeyboardEventHandler, MouseEvent} from 'react';
+
+/**
+ * Event props for a disabled control that stays focusable. Native `disabled`
+ * dispatched no click at all; without it, Enter and Space still synthesize a
+ * click that native listeners on the element (a wrapping Popover's trigger)
+ * receive. Cancelling those keys keeps the click from existing, and the click
+ * handler cancels pointer clicks and keeps them from reaching ancestors. Other
+ * keys still reach the caller's handler.
+ */
+export function disabledInteractionProps<T extends HTMLElement>(
+  onKeyDown?: KeyboardEventHandler<T>,
+): {
+  onClick: (event: MouseEvent<T>) => void;
+  onKeyDown: (event: KeyboardEvent<T>) => void;
+} {
+  return {
+    onClick: event => {
+      event.preventDefault();
+      event.stopPropagation();
+    },
+    onKeyDown: event => {
+      if (event.key === 'Enter' || event.key === ' ') {
+        event.preventDefault();
+      } else {
+        onKeyDown?.(event);
+      }
+    },
+  };
+}