@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/SideNav/SideNav.test.tsx

@@ -26,6 +26,9 @@ import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {getForcedColorsRules} from '../__tests__/forcedColors';
 import {Button} from '../Button';
 import {SideNav} from './SideNav';
+import {__resetMenuPressForTest} from '../hooks/useMenuPress';
+import {expectNativeLinkClicks} from '../hooks/__tests__/menuLinkClicks';
+import {NavHeadingMenu, NavHeadingMenuItem} from '../NavMenu';
 import {SideNavCollapseButton} from './SideNavCollapseButton';
 import {SideNavHeading} from './SideNavHeading';
 import {SideNavItem} from './SideNavItem';
@@ -425,6 +428,138 @@ describe('SideNavHeading', () => {
       </>
     );
 
+    it('leaves a press on caller content that is not an item to that content: a button click and a link click run (interaction-modality INV4)', async () => {
+      __resetMenuPressForTest();
+      const user = userEvent.setup();
+      const onButton = vi.fn();
+      const onLink = vi.fn((event: React.MouseEvent) => event.preventDefault());
+      render(
+        <SideNavHeading
+          heading="My App"
+          menu={
+            <>
+              <button type="button" onClick={onButton}>
+                Switch account
+              </button>
+              <a href="#docs" onClick={onLink}>
+                Docs
+              </a>
+            </>
+          }
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Open menu'}));
+      for (const pointer of [
+        {pointerType: 'mouse', pointerId: 1, button: 0},
+        {pointerType: 'touch', pointerId: 2},
+      ]) {
+        onButton.mockClear();
+        onLink.mockClear();
+        const button = screen.getByRole('button', {
+          name: 'Switch account',
+          hidden: true,
+        });
+        fireEvent.pointerDown(button, pointer);
+        fireEvent.pointerUp(button, pointer);
+        // A pointer's click reports detail 1 (a keyboard's reports 0).
+        fireEvent.click(button, {detail: 1});
+        expect(onButton).toHaveBeenCalledTimes(1);
+        const link = screen.getByRole('link', {name: 'Docs', hidden: true});
+        fireEvent.pointerDown(link, pointer);
+        fireEvent.pointerUp(link, pointer);
+        fireEvent.click(link, {detail: 1});
+        expect(onLink).toHaveBeenCalledTimes(1);
+      }
+    });
+
+    it('leaves a Ctrl-, Cmd-, Shift- or middle click on a link item in its menu to the browser', async () => {
+      __resetMenuPressForTest();
+      const user = userEvent.setup();
+      render(
+        <SideNavHeading
+          heading="My App"
+          menu={
+            <NavHeadingMenu>
+              <NavHeadingMenuItem label="Docs" href="/docs" />
+              <NavHeadingMenuItem label="Status" href="/status" />
+            </NavHeadingMenu>
+          }
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Open menu'}));
+      expectNativeLinkClicks(
+        screen.getByRole('menuitem', {name: 'Docs', hidden: true}),
+      );
+    });
+
+    it('closes when a mouse pressed on a NavHeadingMenu item is released outside the menu (useMenuPress FR3)', async () => {
+      __resetMenuPressForTest();
+      const user = userEvent.setup();
+      render(
+        <>
+          <SideNavHeading
+            heading="My App"
+            menu={
+              <NavHeadingMenu>
+                <NavHeadingMenuItem label="Alpha" onClick={() => {}} />
+                <NavHeadingMenuItem label="Beta" onClick={() => {}} />
+              </NavHeadingMenu>
+            }
+          />
+          <button type="button">Outside</button>
+        </>,
+      );
+      const trigger = screen.getByRole('button', {name: 'Open menu'});
+      await user.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+      const mouse = {pointerType: 'mouse', pointerId: 3, button: 0};
+      const outside = screen.getByRole('button', {name: 'Outside'});
+      fireEvent.pointerDown(
+        screen.getByRole('menuitem', {name: 'Alpha', hidden: true}),
+        mouse,
+      );
+      fireEvent.pointerMove(outside, mouse);
+      fireEvent.pointerUp(outside, mouse);
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('acts on the item a press slid across the menu lifts on, once (family:action-groups FR1, FR2, FR5)', async () => {
+      __resetMenuPressForTest();
+      const user = userEvent.setup();
+      const onAlpha = vi.fn();
+      const onBeta = vi.fn();
+      render(
+        <SideNavHeading
+          heading="My App"
+          menu={
+            <>
+              <div role="menuitem" tabIndex={-1} onClick={onAlpha}>
+                Alpha
+              </div>
+              <div role="menuitem" tabIndex={-1} onClick={onBeta}>
+                Beta
+              </div>
+            </>
+          }
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Open menu'}));
+      const item = (name: string) =>
+        screen.getByRole('menuitem', {name, hidden: true});
+      for (const pointer of [
+        {pointerType: 'touch', pointerId: 1},
+        {pointerType: 'mouse', pointerId: 2, button: 0},
+      ]) {
+        onAlpha.mockClear();
+        onBeta.mockClear();
+        fireEvent.pointerDown(item('Alpha'), pointer);
+        fireEvent.pointerMove(item('Beta'), pointer);
+        fireEvent.pointerUp(item('Beta'), pointer);
+        expect(onBeta).toHaveBeenCalledTimes(1);
+        expect(onAlpha).not.toHaveBeenCalled();
+      }
+    });
+
     it('does not wrap the heading menu popup in a modal dialog', async () => {
       const user = userEvent.setup();
       render(<SideNavHeading heading="My App" menu={menuItems} />);
@@ -668,18 +803,27 @@ describe('SideNavHeading headerEndContent', () => {
     expect(screen.getByTestId('end-badge')).toBeInTheDocument();
   });
 
-  it('renders headerEndContent inside the link in isWholeHeadingLink path', () => {
+  it('renders headerEndContent beside the link, not inside it, in isWholeHeadingLink path', () => {
+    const onPress = vi.fn();
     render(
       <SideNavHeading
         heading="My App"
         headingHref="/home"
-        headerEndContent={<span data-testid="end-badge">3</span>}
+        headerEndContent={
+          <button type="button" onClick={onPress}>
+            Create
+          </button>
+        }
       />,
     );
-    const badge = screen.getByTestId('end-badge');
-    expect(badge).toBeInTheDocument();
-    // Badge renders inside the link
-    expect(badge.closest('a')).not.toBeNull();
+    const link = screen.getByRole('link', {name: 'My App'});
+    expect(link).toHaveAttribute('href', '/home');
+    // A control inside a link is invalid and its press would follow the link.
+    const button = screen.getByRole('button', {name: 'Create'});
+    expect(button.closest('a')).toBeNull();
+    expect(link.parentElement).toBe(button.parentElement?.parentElement);
+    fireEvent.click(button);
+    expect(onPress).toHaveBeenCalledTimes(1);
   });
 
   it('renders headerEndContent in isWholeHeadingTrigger path', () => {
@@ -2390,7 +2534,37 @@ describe('SideNav keyboard operation', () => {
 // Focus management (audit §6 V7)
 // =============================================================================
 
+/**
+ * Holds requestAnimationFrame callbacks until `flush`, so a test decides when
+ * a popover's auto-focus frame runs instead of racing a timer.
+ */
+function holdAnimationFrames() {
+  const frames = new Map<number, FrameRequestCallback>();
+  let nextFrame = 0;
+  vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+    nextFrame += 1;
+    frames.set(nextFrame, callback);
+    return nextFrame;
+  });
+  vi.stubGlobal('cancelAnimationFrame', (frame: number) => {
+    frames.delete(frame);
+  });
+  return {
+    flush() {
+      act(() => {
+        const due = [...frames.values()];
+        frames.clear();
+        due.forEach(callback => callback(performance.now()));
+      });
+    },
+  };
+}
+
 describe('SideNav focus management', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
   it('keeps focus on the toggle when a group collapses', async () => {
     const user = userEvent.setup();
     render(
@@ -2428,6 +2602,7 @@ describe('SideNav focus management', () => {
   });
 
   it('returns focus to the trigger when the collapsed submenu closes', async () => {
+    const frames = holdAnimationFrames();
     const user = userEvent.setup();
     renderCollapsed(
       <SideNavItem label="Settings" icon={StubIcon} data-testid="parent">
@@ -2438,10 +2613,33 @@ describe('SideNav focus management', () => {
     const trigger = screen.getByTestId('parent');
     await user.click(trigger);
     expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    // The submenu focuses its first link in the frame after it opens.
+    frames.flush();
+    expect(screen.getByText('General').closest('a')).toHaveFocus();
 
+    // Closing restores focus as part of the close itself.
     await user.keyboard('{Escape}');
-    // The layer restores focus asynchronously after it closes.
-    await waitFor(() => expect(trigger).toHaveFocus());
+    expect(trigger).toHaveFocus();
+  });
+
+  it('keeps focus on the trigger when the submenu closes before its first frame', async () => {
+    const frames = holdAnimationFrames();
+    const user = userEvent.setup();
+    renderCollapsed(
+      <SideNavItem label="Settings" icon={StubIcon} data-testid="parent">
+        <SideNavItem label="General" href="/settings/general" />
+      </SideNavItem>,
+    );
+
+    const trigger = screen.getByTestId('parent');
+    await user.click(trigger);
+    await user.keyboard('{Escape}');
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+    // The open's auto-focus frame, late on a busy runner, must not land
+    // focus in the closed submenu.
+    frames.flush();
+    expect(trigger).toHaveFocus();
   });
 });
 
@@ -3696,33 +3894,235 @@ describe('SideNav collapse conflict warning', () => {
 // SideNavItem — collapsed-from-mount rail tooltip
 // =============================================================================
 
+// Two interchangeable link components: switching between them remounts the
+// rendered link element.
+function RailLinkA({ref, ...props}: React.ComponentPropsWithRef<'a'>) {
+  return <a ref={ref} {...props} />;
+}
+
+function RailLinkB({ref, ...props}: React.ComponentPropsWithRef<'a'>) {
+  return <a ref={ref} {...props} />;
+}
+
 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(
+  // #7435 / #7692: a childless item that mounts inside an already-collapsed
+  // SideNav (the persisted-collapse case) must attach its tooltip on the first
+  // render, and the tooltip must describe the control that takes focus — the
+  // link or button — not the row around it.
+  function railTooltipFor(trigger: HTMLElement) {
+    const id = trigger.getAttribute('aria-describedby');
+    return id == null ? null : document.getElementById(id);
+  }
+
+  function renderRail(item: ReactNode) {
+    return render(
       <SideNav
         aria-label="Main"
         collapsible={{isCollapsed: true, hasButton: false}}>
-        <SideNavItem label="Dashboard" icon={StubIcon} href="/dashboard" />
+        {item}
       </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,
+  let showPopover: ReturnType<typeof vi.spyOn> | undefined;
+
+  afterEach(() => {
+    showPopover?.mockRestore();
+    showPopover = undefined;
+    vi.useRealTimers();
+  });
+
+  it('describes the rail link by its tooltip when the nav is collapsed at mount', () => {
+    renderRail(
+      <SideNavItem label="Dashboard" icon={StubIcon} href="/dashboard" />,
     );
+    const link = screen.getByRole('link', {name: 'Dashboard'});
+
+    const layer = railTooltipFor(link);
     expect(layer).not.toBeNull();
     expect(layer).toHaveAttribute('role', 'tooltip');
     expect(layer).toHaveTextContent('Dashboard');
   });
+
+  it('shows a disabled item its label when the pointer rests on its row', async () => {
+    // The disabled control is `pointer-events: none`, so in a browser the
+    // pointer lands on the row; the tooltip has to listen there.
+    vi.useFakeTimers();
+    const spy = vi.spyOn(HTMLElement.prototype, 'showPopover');
+    showPopover = spy;
+    renderRail(
+      <SideNavItem
+        label="Analytics (Coming Soon)"
+        icon={StubIcon}
+        href="/analytics"
+        isDisabled
+      />,
+    );
+    // Let the row's tooltip attach after the commit.
+    await act(async () => {});
+    const button = screen.getByRole('button', {
+      name: 'Analytics (Coming Soon)',
+    });
+    const row = button.parentElement as HTMLElement;
+    const layer = screen.getByRole('tooltip', {hidden: true});
+    expect(layer).toHaveTextContent('Analytics (Coming Soon)');
+
+    fireEvent.mouseEnter(row);
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    expect(spy.mock.contexts).toContain(layer);
+  });
+
+  it('describes the link once a disabled item is enabled in the rail', () => {
+    const item = (isDisabled: boolean) => (
+      <SideNavItem
+        label="Dashboard"
+        icon={StubIcon}
+        href="/dashboard"
+        isDisabled={isDisabled}
+      />
+    );
+    const {rerender} = renderRail(item(true));
+    rerender(
+      <SideNav
+        aria-label="Main"
+        collapsible={{isCollapsed: true, hasButton: false}}>
+        {item(false)}
+      </SideNav>,
+    );
+
+    const link = screen.getByRole('link', {name: 'Dashboard'});
+    expect(railTooltipFor(link)).toHaveTextContent('Dashboard');
+  });
+
+  it('describes the new control when a rail item gains an href', () => {
+    const item = (href?: string) => (
+      <SideNavItem
+        label="Dashboard"
+        icon={StubIcon}
+        href={href}
+        onClick={() => {}}
+      />
+    );
+    const {rerender} = renderRail(item());
+    const button = screen.getByRole('button', {name: 'Dashboard'});
+    expect(railTooltipFor(button)).toHaveTextContent('Dashboard');
+
+    rerender(
+      <SideNav
+        aria-label="Main"
+        collapsible={{isCollapsed: true, hasButton: false}}>
+        {item('/dashboard')}
+      </SideNav>,
+    );
+    const link = screen.getByRole('link', {name: 'Dashboard'});
+    expect(railTooltipFor(link)).toHaveTextContent('Dashboard');
+  });
+
+  it('binds the replacement when a rail link element is replaced', () => {
+    // Switching the link component remounts the element; the tooltip must
+    // follow the new element.
+    vi.useFakeTimers();
+    const spy = vi.spyOn(HTMLElement.prototype, 'showPopover');
+    showPopover = spy;
+    const item = (as: typeof RailLinkA) => (
+      <SideNavItem
+        label="Dashboard"
+        icon={StubIcon}
+        href="/dashboard"
+        as={as}
+      />
+    );
+    const {rerender} = renderRail(item(RailLinkA));
+    const first = screen.getByRole('link', {name: 'Dashboard'});
+    rerender(
+      <SideNav
+        aria-label="Main"
+        collapsible={{isCollapsed: true, hasButton: false}}>
+        {item(RailLinkB)}
+      </SideNav>,
+    );
+
+    const link = screen.getByRole('link', {name: 'Dashboard'});
+    expect(link).not.toBe(first);
+    const layer = railTooltipFor(link);
+    expect(layer).toHaveTextContent('Dashboard');
+    fireEvent.mouseEnter(link);
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    expect(spy.mock.contexts).toContain(layer);
+  });
+
+  it("keeps the tooltip beside a caller's changing aria-describedby", () => {
+    const item = (hint: string) => (
+      <SideNavItem
+        label="Dashboard"
+        icon={StubIcon}
+        href="/dashboard"
+        aria-describedby={hint}
+      />
+    );
+    const {rerender} = renderRail(item('hint-a'));
+    rerender(
+      <SideNav
+        aria-label="Main"
+        collapsible={{isCollapsed: true, hasButton: false}}>
+        {item('hint-b')}
+      </SideNav>,
+    );
+
+    const link = screen.getByRole('link', {name: 'Dashboard'});
+    const tooltip = screen.getByRole('tooltip', {hidden: true});
+    const ids = (link.getAttribute('aria-describedby') ?? '').split(' ');
+    expect(ids).toContain('hint-b');
+    expect(ids).toContain(tooltip.id);
+    expect(ids).not.toContain('hint-a');
+  });
+
+  it('shows the label when keyboard focus reaches a rail link', () => {
+    const spy = vi.spyOn(HTMLElement.prototype, 'showPopover');
+    showPopover = spy;
+    renderRail(
+      <SideNavItem label="Dashboard" icon={StubIcon} href="/dashboard" />,
+    );
+    const link = screen.getByRole('link', {name: 'Dashboard'});
+    const layer = railTooltipFor(link);
+    // jsdom does not model `:focus-visible`; stand in for a keyboard focus.
+    const realMatches = link.matches.bind(link);
+    vi.spyOn(link, 'matches').mockImplementation((selector: string) =>
+      selector === ':focus-visible' ? true : realMatches(selector),
+    );
+
+    fireEvent.focusIn(link);
+    expect(spy.mock.contexts).toContain(layer);
+  });
+
+  it('keeps a tooltip that was open when the rail expanded shut on the next collapse', () => {
+    vi.useFakeTimers();
+    const spy = vi.spyOn(HTMLElement.prototype, 'showPopover');
+    showPopover = spy;
+    const rail = (isCollapsed: boolean) => (
+      <SideNav aria-label="Main" collapsible={{isCollapsed, hasButton: false}}>
+        <SideNavItem label="Dashboard" icon={StubIcon} href="/dashboard" />
+      </SideNav>
+    );
+    const {rerender} = render(rail(true));
+    const link = screen.getByRole('link', {name: 'Dashboard'});
+    fireEvent.mouseEnter(link);
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    expect(spy.mock.contexts).toContain(railTooltipFor(link));
+
+    // Expanding (from a shortcut, say) removes the trigger without a leave.
+    rerender(rail(false));
+    spy.mockClear();
+    rerender(rail(true));
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+    expect(spy).not.toHaveBeenCalled();
+  });
 });

package/src/SideNav/SideNav.tsx

@@ -23,9 +23,12 @@
  */
 
 import {
+  use,
   useCallback,
   useId,
   useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
   useRef,
   type ReactNode,
 } from 'react';
@@ -52,6 +55,15 @@ import {useDevWarning} from '../hooks/useDevWarning';
 import {useTranslator} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {LayoutChangeSnapshot} from '../motion/LayoutChangeSnapshot';
+import {
+  createRailLayout,
+  playRail,
+  snapshotRail,
+  SideNavShellContext,
+  type RailMotion,
+  type RailSnapshot,
+} from './railMotion';
 // =============================================================================
 // Constants
 // =============================================================================
@@ -474,6 +486,70 @@ export function SideNav({
 
   const collapsed = resizableHook.isCollapsed;
 
+  // Every collapse or expand, whatever caused it, plays the rail's motion
+  // (`component:SideNav` FR6): measured in the commit before the DOM changes,
+  // played after it before paint. Inside AppShell the content area moves with
+  // it through AppShell's own handle (`component:AppShell` FR17); outside,
+  // SideNav holds its own over its parent.
+  const shell = use(SideNavShellContext);
+  const ownLayout = useMemo(() => createRailLayout(() => navRef.current), []);
+  const railSnapshotRef = useRef<RailSnapshot | null>(null);
+  const motionRef = useRef<{rail: RailMotion; endContent: () => void} | null>(
+    null,
+  );
+  const measureRail = useCallback(
+    (wasCollapsed: boolean) => {
+      // A change during a running motion starts from what the rail shows.
+      const running = motionRef.current;
+      const shown = running?.rail.shown() ?? null;
+      running?.rail.end();
+      running?.endContent();
+      motionRef.current = null;
+      railSnapshotRef.current = snapshotRail(
+        shell?.rail() ?? navRef.current,
+        shell?.animatedLayout ?? ownLayout,
+        shown,
+        wasCollapsed,
+      );
+      // A collapse covers the old rail with its copy; when the rail cannot
+      // be copied, the page lands at once with it, on one clock, a running
+      // glide included.
+      const snapshot = railSnapshotRef.current;
+      if (snapshot != null && snapshot.swap == null && !wasCollapsed) {
+        shell?.landContent();
+        return;
+      }
+      shell?.beforeRailChange();
+    },
+    [shell, ownLayout],
+  );
+  useLayoutEffect(() => {
+    const snapshot = railSnapshotRef.current;
+    railSnapshotRef.current = null;
+    if (snapshot == null) {
+      return;
+    }
+    // The content moves first: its glide starts before the rail rides it.
+    const endContent = shell?.afterRailChange() ?? (() => {});
+    motionRef.current = {
+      rail: playRail(
+        snapshot,
+        shell?.rail() ?? navRef.current,
+        shell?.animatedLayout ?? ownLayout,
+        shell?.column() ?? null,
+      ),
+      endContent,
+    };
+  }, [collapsed, shell, ownLayout]);
+  // An unmount mid-motion removes the copy at once.
+  useLayoutEffect(
+    () => () => {
+      motionRef.current?.rail.end();
+      motionRef.current?.endContent();
+    },
+    [],
+  );
+
   const toggle = useCallback(() => {
     const next = !collapsed;
 
@@ -673,7 +749,7 @@ export function SideNav({
   // Overlay drag handle inside the nav when resizable.
   // Uses ResizeHandle in overlay mode so the handle sits inside
   // the panel's overflow: clip bounds.
-  const content = showResizeHandle ? (
+  const rail = showResizeHandle ? (
     <div {...stylex.props(styles.resizableContainer)}>
       {navElement}
       <ResizeHandle
@@ -691,6 +767,14 @@ export function SideNav({
   ) : (
     navElement
   );
+  // The snapshot stays mounted outside the resize wrapper, which comes and
+  // goes with the collapse it measures.
+  const content = (
+    <>
+      <LayoutChangeSnapshot value={collapsed} onBeforeChange={measureRail} />
+      {rail}
+    </>
+  );
 
   if (isCollapsible) {
     return (