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

package/src/DropdownMenu/__tests__/SubMenuHeaderFooter.a11y.chromium.spec.ts

@@ -0,0 +1,267 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SubMenuHeaderFooter.a11y.chromium.spec.ts
+ * @input The built Storybook "Submenu / header and footer" story (a Labels
+ *   sub-menu with a filter field above its checkbox rows and a "Create label"
+ *   button below them) and real Chromium, once as a laptop (fine pointer) and
+ *   once as a phone (coarse pointer, touch).
+ * @output Evidence for component:DropdownMenu FR20: a sub-menu's header and
+ *   footer sit with its rows in a modal dialog named by its row, beside every
+ *   menu element rather than inside one; the row says it opens a dialog; Tab
+ *   and Shift+Tab walk field, rows and button and wrap; typing filters the
+ *   rows and Escape returns to the row; a pick keeps the sub-menu open. On a
+ *   phone the drilled-in view holds the same regions while the root menu
+ *   steps aside. On the "Submenu / header with a choice" story, a flyout the
+ *   pointer has left stays open while an arrow moves the header's radio choice.
+ * @position Browser proof behind the jsdom suite: the accessibility tree, real
+ *   Tab order and the pointer decision are what jsdom cannot exercise.
+ */
+
+import {devices, expect, test, type Locator, type Page} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+const storyId = 'core-dropdownmenu--sub-menu-header-and-footer';
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+async function mount(page: Page) {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=${storyId}&viewMode=story`,
+  );
+  await expect(page.getByTestId('submenu-regions-fixture')).toBeVisible();
+}
+
+/** Whether the element sits inside any role="menu" element. */
+async function isInsideAMenu(page: Page, testName: string): Promise<boolean> {
+  return page
+    .getByRole('dialog', {name: testName})
+    .evaluate(el => el.parentElement?.closest('[role="menu"]') != null);
+}
+
+async function bounds(locator: Locator) {
+  const rect = await locator.boundingBox();
+  if (rect == null) {
+    throw new Error('no rendered bounds');
+  }
+  return rect;
+}
+
+test.describe('on a laptop (fine pointer)', () => {
+  test('the sub-menu opens a dialog beside the menu, named by its row, holding field, rows and button', async ({
+    page,
+  }) => {
+    await mount(page);
+    await page.getByRole('button', {name: 'Session'}).click();
+    const row = page.getByRole('menuitem', {name: 'Labels'});
+    await expect(row).toHaveAttribute('aria-haspopup', 'dialog');
+    await row.click();
+
+    const dialog = page.getByRole('dialog', {name: 'Labels'});
+    await expect(dialog).toBeVisible();
+    await expect(dialog).toHaveAttribute('aria-modal', 'true');
+    await expect(row).toHaveAttribute(
+      'aria-controls',
+      (await dialog.getAttribute('id')) ?? '',
+    );
+    expect(await isInsideAMenu(page, 'Labels')).toBe(false);
+    // The sub-menu's own menu holds only its rows.
+    const menu = dialog.getByRole('menu', {name: 'Labels'});
+    expect(
+      await menu.evaluate(el =>
+        Array.from(el.querySelectorAll('[role]')).map(child =>
+          child.getAttribute('role'),
+        ),
+      ),
+    ).toEqual(Array(5).fill('menuitemcheckbox'));
+    await expect(
+      dialog.getByRole('textbox', {name: 'Filter labels'}),
+    ).toBeVisible();
+    await expect(
+      dialog.getByRole('button', {name: 'Create label'}),
+    ).toBeVisible();
+  });
+
+  test('Tab and Shift+Tab walk field, rows and button and wrap; typing filters; Escape returns to the row', async ({
+    page,
+  }) => {
+    await mount(page);
+    const trigger = page.getByRole('button', {name: 'Session'});
+    await trigger.focus();
+    await page.keyboard.press('Enter');
+    // A keyboard open lands on the first row; let it land before moving on.
+    await expect(page.getByRole('menuitem', {name: 'Rename'})).toBeFocused();
+    const row = page.getByRole('menuitem', {name: 'Labels'});
+    await page.keyboard.press('ArrowDown');
+    await expect(row).toBeFocused();
+    await page.keyboard.press('ArrowRight');
+
+    const dialog = page.getByRole('dialog', {name: 'Labels'});
+    const field = dialog.getByRole('textbox', {name: 'Filter labels'});
+    const create = dialog.getByRole('button', {name: 'Create label'});
+    const menu = dialog.getByRole('menu', {name: 'Labels'});
+    // A keyboard open lands on the first row, not the field.
+    await expect(
+      dialog.getByRole('menuitemcheckbox', {name: 'Bug'}),
+    ).toBeFocused();
+
+    await page.keyboard.press('Tab');
+    await expect(create).toBeFocused();
+    await page.keyboard.press('Tab');
+    await expect(field).toBeFocused();
+    await page.keyboard.press('Tab');
+    await expect(menu).toBeFocused();
+    await page.keyboard.press('Shift+Tab');
+    await expect(field).toBeFocused();
+    await page.keyboard.press('Shift+Tab');
+    await expect(create).toBeFocused();
+    await expect(dialog).toBeVisible();
+
+    // The field keeps its keys: letters type and filter the rows, and the
+    // arrow that closes a sub-menu from a row moves the caret instead.
+    await field.focus();
+    await page.keyboard.type('doc');
+    await page.keyboard.press('ArrowLeft');
+    await expect(field).toHaveValue('doc');
+    await expect(dialog.getByRole('menuitemcheckbox')).toHaveText([
+      'Documentation',
+    ]);
+
+    await page.keyboard.press('Escape');
+    await expect(dialog).toBeHidden();
+    await expect(row).toBeFocused();
+    await expect(page.getByRole('menu', {name: 'Session'})).toBeVisible();
+  });
+
+  test('a pick keeps the sub-menu open; the button acts without closing anything', async ({
+    page,
+  }) => {
+    await mount(page);
+    await page.getByRole('button', {name: 'Session'}).click();
+    await page.getByRole('menuitem', {name: 'Labels'}).click();
+    const dialog = page.getByRole('dialog', {name: 'Labels'});
+    await dialog.getByRole('menuitemcheckbox', {name: 'Feature'}).click();
+    await expect(page.getByTestId('picked')).toHaveText('Bug, Feature');
+    await expect(dialog).toBeVisible();
+    await dialog.getByRole('button', {name: 'Create label'}).click();
+    await expect(page.getByTestId('created')).toHaveText('1');
+    await expect(dialog).toBeVisible();
+  });
+});
+
+test.describe('the press model', () => {
+  test('a press on the row, dragged into the flyout and released on a row, picks it', async ({
+    page,
+  }) => {
+    await mount(page);
+    await page.getByRole('button', {name: 'Session'}).click();
+    const row = page.getByRole('menuitem', {name: 'Labels'});
+    await row.hover();
+    const dialog = page.getByRole('dialog', {name: 'Labels'});
+    await expect(dialog).toBeVisible();
+    const feature = dialog.getByRole('menuitemcheckbox', {name: 'Feature'});
+    const [from, to] = await Promise.all([row, feature].map(bounds));
+    await page.mouse.move(from.x + from.width / 2, from.y + from.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(from.x + from.width - 4, from.y + from.height / 2, {
+      steps: 4,
+    });
+    await page.mouse.move(to.x + to.width / 2, to.y + to.height / 2, {
+      steps: 8,
+    });
+    await page.mouse.up();
+    await expect(page.getByTestId('picked')).toHaveText('Bug, Feature');
+    // A checkbox pick keeps the sub-menu, and the menu, open.
+    await expect(dialog).toBeVisible();
+  });
+});
+
+test.describe('on a phone (coarse pointer)', () => {
+  const {defaultBrowserType: _browser, ...phone} = devices['Pixel 7'];
+  test.use(phone);
+
+  test('the drilled-in view holds field, rows and button beside the root menu, which steps aside', async ({
+    page,
+  }) => {
+    await mount(page);
+    const trigger = page.getByRole('button', {name: 'Session'});
+    await trigger.tap();
+    const rootMenu = page.getByRole('menu', {name: 'Session'});
+    await expect(rootMenu).toBeVisible();
+    await page.getByRole('menuitem', {name: 'Labels'}).tap();
+
+    const dialog = page.getByRole('dialog', {name: 'Labels'});
+    await expect(dialog).toBeVisible();
+    await expect(rootMenu).toBeHidden();
+    expect(await isInsideAMenu(page, 'Labels')).toBe(false);
+    // Same popover: the view replaces the root's rows in place.
+    expect(
+      await dialog.evaluate(
+        el =>
+          el.closest('[popover]') ===
+          document
+            .querySelector('[role="menu"][aria-label="Session"]')
+            ?.closest('[popover]'),
+      ),
+    ).toBe(true);
+    await expect(
+      dialog.getByRole('menuitem', {name: 'Back to Session'}),
+    ).toBeVisible();
+    await expect(
+      dialog.getByRole('textbox', {name: 'Filter labels'}),
+    ).toBeVisible();
+    await expect(
+      dialog.getByRole('button', {name: 'Create label'}),
+    ).toBeVisible();
+
+    await dialog.getByRole('menuitem', {name: 'Back to Session'}).tap();
+    await expect(dialog).toBeHidden();
+    await expect(rootMenu).toBeVisible();
+  });
+});
+
+test.describe('a header with a choice', () => {
+  test('a flyout the pointer has left stays open while an arrow moves the choice in its header', async ({
+    page,
+  }) => {
+    await page.goto(
+      `${storybook.origin}/iframe.html?id=core-dropdownmenu--sub-menu-header-choice&viewMode=story`,
+    );
+    await expect(page.getByTestId('submenu-choice-fixture')).toBeVisible();
+    await page.getByRole('button', {name: 'Filters'}).click();
+    const row = page.getByRole('menuitem', {name: 'Labels'});
+    await row.hover();
+    const dialog = page.getByRole('dialog', {name: 'Labels'});
+    await expect(dialog).toBeVisible();
+    const anyLabel = dialog.getByRole('radio', {name: 'Any label'});
+    const allLabels = dialog.getByRole('radio', {name: 'All labels'});
+    await anyLabel.click();
+    await expect(anyLabel).toBeFocused();
+
+    // The pointer leaves the flyout and the menu, and its hide delay runs out
+    // with focus still inside.
+    const viewport = page.viewportSize() ?? {width: 1280, height: 720};
+    await page.mouse.move(viewport.width - 8, viewport.height - 8, {steps: 4});
+    await page.waitForTimeout(500);
+    await expect(dialog).toBeVisible();
+
+    // The browser moves focus and the choice for the arrow itself.
+    await page.keyboard.press('ArrowDown');
+    await expect(allLabels).toBeFocused();
+    await expect(allLabels).toBeChecked();
+    await expect(page.getByTestId('match')).toHaveText('all');
+    await expect(dialog).toBeVisible();
+  });
+});

package/src/DropdownMenu/menuRegionStops.ts

@@ -8,8 +8,8 @@
  * @output `tabbablesIn`, `focusRegionControl`, `moveRegionsTab`: the Tab stops
  *   of a header or footer region and the walk through a menu with regions,
  *   with a named radio group as one stop
- * @position Internal; DropdownMenu's walk through its header and footer, in a
- *   module of its own so another menu level with regions can share it.
+ * @position Internal; used by DropdownMenu (the root menu's header and footer)
+ *   and DropdownMenuSubMenu (a sub-menu's header and footer).
  *
  * A menu with a header or footer is a dialog: Tab and Shift+Tab walk the
  * header's controls, the menu as one stop, then the footer's controls, and

package/src/DropdownMenu/modules/useMenuPress.spec.md

@@ -163,6 +163,14 @@ Consumer migration instructions belong in consumer docs and release notes.
   claimed by the innermost root carrying `data-astryx-menu-press` (a flyout
   before its parent); the outermost root decides what counts as "inside the
   menu" for the release.
+- **ORD1a (proposed) — A menu beside the root.** A root carrying
+  `data-astryx-menu-press-surface`, which names another root's `id`, is nested
+  in that root for ORD1, as a flyout inside the root's DOM is: a release on
+  its rows is inside the menu. Only the menu of a sub-menu with a header or
+  footer, which the root renders beside itself (`component:DropdownMenu`
+  FR20), carries it. Anything else beside the root, a header field or a picker
+  placed in a region say, is outside the menu, as the root's own regions are,
+  and a picker there stays its own root. Pending owner review.
 - **ORD2 — Release resolution.** Enabled row under the point → `act`; inside
   the menu or on the trigger with no row → `settle` (stray click swallowed,
   menu stays); outside → `settle` with `dismiss` only for a mouse.
@@ -238,6 +246,7 @@ owned by the item components.
 | FR4 (scroll)           | `MenuPress.a11y.chromium.spec.ts` (real Chromium)                                                                          | Chromium touch pan in an overflowing menu; touch-action by overflow; finger slide and its stray click                                                    | Not provable in jsdom; a pan that acts on a row, or a slide that acts on the press row, fails                                   |
 | FR4 (pinch)            | `MenuPinchZoom.a11y.chromium.spec.ts` (real Chromium, phone emulation)                                                     | two-finger pinch over a menu whose rows fit, over one that scrolls, and over a picker listbox                                                            | Not provable in jsdom; a pinch that leaves the page at scale 1, or acts on a row, fails                                         |
 | FR8, FR9 (proposed)    | `menuPressGesture.test.ts` trigger states; `useMenuPress.test.tsx` trigger suite; `DropdownMenu.test.tsx` press-open cases | mouse opens at once, finger tap, held finger, settle before/after, cancel; press-open + drag-release, unsettled release, trigger toggle, held touch, tap | A menu that does not open on a mouse press, an unsettled release that acts, or a trigger that reopens in the same gesture fails |
+| ORD1a (proposed)       | `DropdownMenuSubMenu.test.tsx` press cases; `SubMenuHeaderFooter.a11y.chromium.spec.ts` press-drag case                    | a mouse press on a menu row released on a row of a sub-menu rendered beside the menu; the same press released on that sub-menu's header field            | A release on such a row that acts on nothing or closes the menu, or a release on its header field that acts, fails.             |
 
 ## Decision log
 

package/src/SideNav/SideNav.test.tsx

@@ -3691,3 +3691,38 @@ describe('SideNav collapse conflict warning', () => {
     expect(warn).not.toHaveBeenCalled();
   });
 });
+
+// =============================================================================
+// SideNavItem — collapsed-from-mount rail tooltip
+// =============================================================================
+
+describe('SideNavItem collapsed-from-mount rail tooltip', () => {
+  // #7692: a childless item that mounts inside an already-collapsed SideNav
+  // renders its Tooltip inside the very element anchorRef points at. React
+  // attaches that ref only after the tooltip's layout effect has run, so the
+  // tooltip never attached and a persisted collapsed rail lost all tooltips
+  // on page load.
+  it('anchors the rail tooltip when the nav is collapsed at mount', async () => {
+    render(
+      <SideNav
+        aria-label="Main"
+        collapsible={{isCollapsed: true, hasButton: false}}>
+        <SideNavItem label="Dashboard" icon={StubIcon} href="/dashboard" />
+      </SideNav>,
+    );
+    const link = screen.getByRole('link', {name: 'Dashboard'});
+    const anchor = link.parentElement as HTMLElement;
+
+    // The tooltip attaches despite mounting inside its own anchor: the item
+    // row is described by the tooltip layer.
+    await waitFor(() => {
+      expect(anchor.getAttribute('aria-describedby')).not.toBe('');
+    });
+    const layer = document.getElementById(
+      anchor.getAttribute('aria-describedby') as string,
+    );
+    expect(layer).not.toBeNull();
+    expect(layer).toHaveAttribute('role', 'tooltip');
+    expect(layer).toHaveTextContent('Dashboard');
+  });
+});

package/src/TimeInput/TimeInput.doc.mjs

@@ -212,7 +212,7 @@ export const docs = {
       name: 'increment',
       type: 'number',
       description:
-        'Number of minutes to add or subtract when the user presses the up or down arrow key.',
+        'Number of minutes to add or subtract when the user presses the up or down arrow key. Steps are whole minutes; a fractional value leaves the time unchanged.',
       default: '1',
     },
     {
@@ -392,7 +392,8 @@ export const docsZh = {
     {
       name: 'increment',
       type: 'number',
-      description: '用户按上或下方向键时增加或减少的分钟数。',
+      description:
+        '用户按上或下方向键时增加或减少的分钟数。步长为整分钟；传入小数时时间保持不变。',
       default: '1',
     },
     {
@@ -623,7 +624,8 @@ export const docsDense = {
     hasClear: 'Shows clear button when value set+not disabled.',
     hourFormat:
       "Display format. '12h' shows AM/PM; '24h' uses 24-hour notation.",
-    increment: 'Minutes to add/subtract on arrow up/down.',
+    increment:
+      'Minutes to add/subtract on arrow up/down. Whole minutes only; a fractional value leaves the time unchanged.',
     presentation:
       "picker surface: 'adaptive-native' (default) = typed field fine / browser/OS coarse (hasSeconds or increment!=1 retains typed); 'native' = browser/OS always, no fallback; 'adaptive-bottom-sheet' = typed fine / Astryx wheel sheet coarse; 'bottom-sheet' = sheet always; 'text-input'/'popover' = typed field only.",
     nativePicker:

package/src/TimeInput/TimeInput.test.tsx

@@ -65,6 +65,26 @@ describe('TimeInput', () => {
     expect(onChange).toHaveBeenCalledWith('14:31');
   });
 
+  it('does not step into a fractional minute when increment is fractional', () => {
+    const onChange = vi.fn();
+    render(
+      <TimeInput
+        label="Time"
+        value={'14:30' as ISOTimeString}
+        increment={0.5}
+        onChange={onChange}
+      />,
+    );
+    const input = screen.getByLabelText('Time');
+
+    // `increment` is documented as minutes and typed `number`. A fractional one
+    // used to reach formatISOTime unrounded, which pads "30.5" to two
+    // characters and leaves it, so the arrow key handed the consumer a value
+    // that is no longer a time at all.
+    fireEvent.keyDown(input, {key: 'ArrowUp'});
+    expect(onChange).toHaveBeenCalledWith('14:30');
+  });
+
   it('displays formatted time in 12h format', () => {
     render(
       <TimeInput

package/src/TimeInput/TimeInput.tsx

@@ -286,7 +286,8 @@ export interface TimeInputProps extends Omit<
   hourFormat?: TimeInputHourFormat;
 
   /**
-   * Increment in minutes when using arrow keys.
+   * Increment in minutes when using arrow keys. Steps are whole minutes: a
+   * fractional value leaves the time unchanged.
    * @default 1
    */
   increment?: number;

package/src/Tooltip/Tooltip.test.tsx

@@ -25,6 +25,7 @@ import {
   fireEvent,
   waitFor,
 } from '@testing-library/react';
+import {useRef} from 'react';
 import {Tooltip} from './Tooltip';
 import {useTooltip} from './useTooltip';
 import {__resetInteractionModalityForTest} from '../utils/interactionModality';
@@ -84,17 +85,15 @@ describe('Tooltip', () => {
     expect(screen.getByRole('button', {name: 'Trigger'})).toBeInTheDocument();
   });
 
-  it('gives the tooltip layer role="tooltip" linked from the trigger', () => {
+  it('renders the content prop inside the tooltip layer', () => {
     render(
       <Tooltip content="Tooltip text">
         <button type="button">Trigger</button>
       </Tooltip>,
     );
-    const layer = screen.getByRole('tooltip', {hidden: true});
-    expect(layer).toHaveTextContent('Tooltip text');
-    // ARIA tooltip pattern: trigger references the layer via aria-describedby.
-    const trigger = screen.getByRole('button', {name: 'Trigger'});
-    expect(trigger.getAttribute('aria-describedby')).toBe(layer.id);
+    expect(screen.getByRole('tooltip', {hidden: true})).toHaveTextContent(
+      'Tooltip text',
+    );
   });
 
   it('calls onOpenChange(true) when shown via hover', async () => {
@@ -604,3 +603,49 @@ describe('Tooltip', () => {
     });
   });
 });
+
+describe('Tooltip sibling mode (anchorRef)', () => {
+  // SideNavItem's collapsed rail tooltip renders the Tooltip inside the very
+  // element anchorRef points at. React attaches an ancestor's ref after its
+  // descendants' layout effects, so on mount the tooltip's effect used to see
+  // a null anchor and never retried (#7692).
+  it('attaches to an anchor it is rendered inside of', async () => {
+    const onOpenChange = vi.fn();
+    function AnchorInside() {
+      const anchorRef = useRef<HTMLDivElement>(null);
+      return (
+        <div ref={anchorRef}>
+          <button type="button">Inner</button>
+          <Tooltip
+            content="Sibling tooltip"
+            anchorRef={anchorRef}
+            delay={0}
+            onOpenChange={onOpenChange}
+          />
+        </div>
+      );
+    }
+
+    const {unmount} = render(<AnchorInside />);
+    const anchor = screen.getByRole('button', {name: 'Inner'})
+      .parentElement as HTMLElement;
+
+    // The anchor is described by the tooltip once the commit has attached refs.
+    await waitFor(() => {
+      expect(anchor.getAttribute('aria-describedby')).not.toBe('');
+    });
+    const layer = screen.getByRole('tooltip', {hidden: true});
+    expect(anchor.getAttribute('aria-describedby')).toBe(layer.id);
+
+    // Hovering the anchor opens the tooltip: the interaction listeners were
+    // attached to the late anchor too.
+    fireEvent.mouseEnter(anchor);
+    await waitFor(() => {
+      expect(onOpenChange).toHaveBeenCalledWith(true);
+    });
+
+    // Unmounting detaches: the aria-describedby the tooltip added is removed.
+    unmount();
+    expect(anchor.getAttribute('aria-describedby')).toBe(null);
+  });
+});

package/src/Tooltip/Tooltip.tsx

@@ -242,28 +242,51 @@ export function Tooltip({
       return;
     }
 
+    const attach = (el: HTMLElement) => {
+      // Use combined ref for position + interaction
+      tooltip.ref(el);
+
+      // Set aria-describedby, merging with existing
+      const existingDescribedBy = el.getAttribute('aria-describedby');
+      el.setAttribute(
+        'aria-describedby',
+        mergeIds(existingDescribedBy, tooltip.describedBy) ?? '',
+      );
+
+      return () => {
+        tooltip.ref(null);
+        if (existingDescribedBy) {
+          el.setAttribute('aria-describedby', existingDescribedBy);
+        } else {
+          el.removeAttribute('aria-describedby');
+        }
+      };
+    };
+
     const el = anchorRef.current;
-    if (!el) {
-      return;
+    if (el) {
+      return attach(el);
     }
 
-    // Use combined ref for position + interaction
-    tooltip.ref(el);
-
-    // Set aria-describedby, merging with existing
-    const existingDescribedBy = el.getAttribute('aria-describedby');
-    el.setAttribute(
-      'aria-describedby',
-      mergeIds(existingDescribedBy, tooltip.describedBy) ?? '',
-    );
-
-    return () => {
-      tooltip.ref(null);
-      if (existingDescribedBy) {
-        el.setAttribute('aria-describedby', existingDescribedBy);
-      } else {
-        el.removeAttribute('aria-describedby');
+    // React attaches an ancestor's ref after its descendants' layout effects,
+    // so a tooltip rendered inside its own anchor (SideNavItem's collapsed
+    // rail tooltip) still sees null here on mount, and this effect's deps
+    // never change to re-run it. Re-check once the commit has attached all
+    // refs; if the anchor is still gone, this tooltip has no anchor, as before.
+    let detach: (() => void) | undefined;
+    let cancelled = false;
+    queueMicrotask(() => {
+      if (cancelled) {
+        return;
       }
+      const el = anchorRef.current;
+      if (el) {
+        detach = attach(el);
+      }
+    });
+    return () => {
+      cancelled = true;
+      detach?.();
     };
   }, [anchorRef, tooltip.ref, tooltip.describedBy]);