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

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/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/timeParser.test.ts

@@ -260,6 +260,17 @@ describe('adjustTime', () => {
     expect(adjustTime('10:00' as ISOTimeString, NaN)).toBe('10:00');
   });
 
+  it('returns the input unchanged for a fractional delta', () => {
+    // `increment` is documented as minutes and typed `number`, so a caller can
+    // hand ArrowUp a fraction. A fractional minute reaching formatISOTime is
+    // not rounded: it pads to "30.5" and the field is left holding a string
+    // that is no longer a parseable time.
+    expect(adjustTime('10:30' as ISOTimeString, 0.5)).toBe('10:30');
+    expect(adjustTime('10:30:45' as ISOTimeString, -0.5, true)).toBe(
+      '10:30:45',
+    );
+  });
+
   it('wraps large negative deltas in constant time', () => {
     expect(adjustTime('10:00' as ISOTimeString, -1440 * 1e7)).toBe('10:00');
     expect(adjustTime('10:00' as ISOTimeString, -1440 * 1e7 - 30)).toBe(

package/src/utils/timeParser.ts

@@ -372,6 +372,10 @@ export function clampTime(
 
 /**
  * Adjusts a time by adding/subtracting minutes.
+ *
+ * `deltaMinutes` is a whole number of minutes. A fractional delta leaves the
+ * time unchanged rather than returning a value that is no longer a time —
+ * `HH:MM` has no place for a fraction of a minute.
  */
 export function adjustTime(
   time: ISOTimeString,
@@ -384,8 +388,11 @@ export function adjustTime(
   }
 
   // A non-finite delta would spin the wrap-around forever (-Infinity) or
-  // produce "NaN:NaN" (NaN) — return the input unchanged instead.
-  if (!Number.isFinite(deltaMinutes)) {
+  // produce "NaN:NaN" (NaN), and a fractional one is never rounded on the way
+  // out — formatISOTime pads "30.5" to two characters and leaves it, so the
+  // caller gets back a value that is no longer a time. Steps are whole
+  // minutes: return the input unchanged instead.
+  if (!Number.isInteger(deltaMinutes)) {
     return time;
   }