@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/SideNav/SideNavSection.spec.md

@@ -0,0 +1,153 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:SideNavSection
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-25
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility]
+verified_by:
+  [
+    packages/core/src/SideNav/SideNav.test.tsx,
+    apps/storybook/stories/SideNav.stories.tsx,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [architecture:public-component-api, architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# SideNavSection component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `SideNavSection` with `title`, `subtitle`, `endContent`, `isHeaderHidden`, and `children`; target `side-nav-section`.                                                   |
+| Behavior                | A labeled group of SideNav items. Its header is visible in an expanded rail and visually hidden, but still read, when `isHeaderHidden` is set or the rail is collapsed. |
+| End-user impact         | Screen-reader users hear each group's title in every rail state; sighted users see section titles only in the expanded rail.                                            |
+| Builder impact          | None.                                                                                                                                                                   |
+| Compatibility/readiness | Records shipped behavior; no public change. One implementation gap (see Current-state impact).                                                                          |
+| Review checks           | Reject a section without `role="group"` named by its title, or a hidden header removed from the accessibility tree.                                                     |
+| Governing rules         | `architecture:public-component-api` INV5–INV6; `architecture:component-theming-surface`.                                                                                |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+SideNavSection groups related SideNav items under a title. It owns the group's
+semantics and its header's visibility. Consumer usage lives in
+`SideNavSection.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **A hidden header keeps its end content focusable.** When the header is
+  visually hidden (`isHeaderHidden` or a collapsed rail), a control placed in
+  `endContent` stays in the tab order while it is clipped out of sight, so
+  keyboard users land on a control they cannot see. WCAG 2.4.7 requires visible
+  focus. OQ1 asks whether a hidden header renders `endContent`.
+
+## Ownership boundary
+
+**Owns**
+
+- The group element, its name, header visibility, and root styling (FR1–FR4).
+
+**Does not own / non-goals**
+
+- Item rendering and nesting — owned by `component:SideNavItem` and
+  `component:SideNav`.
+- Interactive content placed in `endContent` — owned by that content.
+
+## Public concepts
+
+No component-local concept beyond the consumer props.
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                     | Basis                    |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | The root is a `div` with `role="group"` and `aria-labelledby` pointing at the title. It carries `side-nav-section`, the forwarded `ref`, `data-testid`, and other DOM props; the role and label cannot be overridden by them. | Current source and tests |
+| FR2 | The header shows the title, an optional subtitle, and `endContent` at the inline end, followed by the items.                                                                                                                  | Current source and tests |
+| FR3 | When `isHeaderHidden` is true or the rail is collapsed, the header is visually hidden but stays in the accessibility tree, so the group keeps its name.                                                                       | Current source and tests |
+| FR4 | `className`, `style`, and `xstyle` merge onto the root after component styles.                                                                                                                                                | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Header content.** Subtitle and end content may be absent.
+
+### Representative states
+
+| State          | Required invariant                   | Allowed variation |
+| -------------- | ------------------------------------ | ----------------- |
+| Expanded rail  | Visible header; named group.         | End content.      |
+| Header hidden  | Hidden header still names the group. | —                 |
+| Collapsed rail | Hidden header still names the group. | —                 |
+
+### Transformation and precedence order
+
+- No precedence rule.
+
+### Performance and resources
+
+- No resource rule.
+
+## Accessibility contract
+
+- **AR1 — Named group.** FR1 and FR3.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                     | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Header           | Title, subtitle, trailing end content. | Current source and public docs | Supporting     | FR2, FR3           |
+
+`SideNavSection.doc.mjs` declares no anatomy of its own, so no anatomy-theming
+map is recorded.
+
+## Family and system relationships
+
+- `component:SideNav` hosts sections in its list.
+
+## Verification map
+
+| Contract      | Verification                                  | Representative states               | Mutation or failure expectation             | Audit section                        |
+| ------------- | --------------------------------------------- | ----------------------------------- | ------------------------------------------- | ------------------------------------ |
+| FR1, FR2, FR4 | `SideNav.test.tsx` SideNavSection suite       | Title, subtitle, end content, props | A lost role, name, or forwarded prop fails. | `audit:SideNavSection/accessibility` |
+| FR3           | `SideNav.test.tsx` hidden section header test | Header hidden                       | A header removed from the tree fails.       | `audit:SideNavSection/accessibility` |
+
+Read from source, with no focused test yet: the forwarded `ref`, the
+`side-nav-section` target, and the role and label winning over caller props
+(FR1); the header's part order and end placement (FR2); hiding the header in a
+collapsed rail (FR3); and `xstyle` on the root (FR4).
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+- **OQ1 — Does a hidden header render `endContent`?** (`human-api`) Today it
+  does, and a control there stays focusable while hidden (Current-state
+  impact).
+
+## Content boundary
+
+This file does not duplicate consumer prop tables or examples. It links to their
+owners.

package/src/SideNav/__tests__/SideNavRailMotion.interaction.browser.spec.ts

@@ -0,0 +1,417 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SideNavRailMotion.interaction.browser.spec.ts
+ * @input The built Storybook's `Core/AppShell` rail-collapse stories: an
+ *   AppShell whose collapsible SideNav's collapsed state the app holds, on a
+ *   phone (finger, coarse pointer) and at desktop width (mouse, fine pointer)
+ * @output The real-browser frame evidence `component:SideNav` FR6 and
+ *   `component:AppShell` FR17 ask for: every frame of a collapse and an
+ *   expand keeps the rail's edge on the content's edge with no width
+ *   animation, the rail's copy is hidden from assistive technology and gone at
+ *   rest, the rail ends icons-only or with its labels, a second press mid-motion
+ *   stays continuous, an expand whose old wrap is not copied keeps the edges
+ *   together, and Reduce Motion cross-fades under a finger (DR2) and changes at
+ *   once under a mouse (DR3)
+ * @position Testing; the components' unit cases are
+ *   SideNav/SideNavRailMotion.test.tsx
+ *
+ * SYNC: When modified, update FR6's state cell and Verification row in
+ *   SideNav.spec.md and the FR17 Verification row in AppShell.spec.md.
+ */
+
+import {expect, test, type Page} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+// The frame evidence is Chromium's: CI's interaction proofs run the chromium
+// project, and these cases have not been run in WebKit.
+test.skip(
+  ({browserName}) => browserName === 'webkit',
+  'Chromium frame evidence; not yet verified in WebKit',
+);
+
+let storybook: StaticServer | undefined;
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+const PHONE_STORY = 'core-appshell--rail-collapse-motion-phone';
+const DESKTOP_STORY = 'core-appshell--rail-collapse-motion';
+
+/** Loads a story and waits for its first render, its fonts and two frames. */
+async function openStory(page: Page, story: string): Promise<void> {
+  await page.goto(
+    `${storybook?.origin ?? ''}/iframe.html?id=${story}&viewMode=story`,
+  );
+  await page.locator('[role="main"]').first().waitFor({state: 'attached'});
+  await page.evaluate(async () => {
+    await document.fonts.ready;
+    await new Promise<void>(resolve => {
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+  });
+}
+
+/** What the frames of one motion showed, sampled every animation frame. */
+interface Frames {
+  readonly frames: number;
+  /** The largest distance between the rail's shown edge and the content's. */
+  readonly maxGap: number;
+  /** Whether any running animation changed a width. */
+  readonly animatesWidth: boolean;
+  /** Whether every rail copy seen was inert and hidden from AT. */
+  readonly copiesHidden: boolean;
+  /** Rail copies seen during the motion. */
+  readonly copiesSeen: number;
+  /** Other inert copies seen: the content's old wrap. */
+  readonly wrapCopiesSeen: number;
+  /** Distinct rail-edge positions seen: more than a few means it moved. */
+  readonly edges: number;
+}
+
+/**
+ * Presses the rail's collapse/expand button (`press` runs the press itself:
+ * a tap or a click) after `delays` ms each, then samples every frame until
+ * `durationMs` after the last press.
+ */
+async function sampleMotion(
+  page: Page,
+  press: () => Promise<void>,
+  {presses = 1, gapMs = 0, durationMs = 1000} = {},
+): Promise<Frames> {
+  await page.evaluate(() => {
+    const state = {
+      frames: 0,
+      maxGap: 0,
+      animatesWidth: false,
+      copiesHidden: true,
+      copiesSeen: 0,
+      wrapCopiesSeen: 0,
+      edges: new Set<number>(),
+      running: true,
+    };
+    (window as unknown as {railFrames: typeof state}).railFrames = state;
+    const panel = document.querySelector('.astryx-layout-panel');
+    const main = document.querySelector('[role="main"]');
+    if (panel == null || main == null) {
+      return;
+    }
+    let column = main;
+    while (
+      column.parentElement != null &&
+      !column.parentElement.contains(panel)
+    ) {
+      column = column.parentElement;
+    }
+    const shownRight = (element: Element) => {
+      const inset = /inset\(0px ([\d.]+)px/.exec(
+        getComputedStyle(element).clipPath,
+      );
+      return (
+        element.getBoundingClientRect().right - (inset ? Number(inset[1]) : 0)
+      );
+    };
+    const sample = () => {
+      if (!state.running) {
+        return;
+      }
+      state.frames++;
+      const copies = [...document.querySelectorAll('[inert]')].filter(
+        element => element.querySelector('nav') != null,
+      );
+      state.copiesSeen = Math.max(state.copiesSeen, copies.length);
+      state.wrapCopiesSeen = Math.max(
+        state.wrapCopiesSeen,
+        document.querySelectorAll('[inert]').length - copies.length,
+      );
+      for (const copy of copies) {
+        if (copy.getAttribute('aria-hidden') !== 'true') {
+          state.copiesHidden = false;
+        }
+      }
+      const edge = Math.max(shownRight(panel), ...copies.map(shownRight));
+      state.edges.add(Math.round(edge));
+      state.maxGap = Math.max(
+        state.maxGap,
+        Math.abs(edge - column.getBoundingClientRect().left),
+      );
+      for (const animation of document.getAnimations()) {
+        const frames = (animation.effect as KeyframeEffect).getKeyframes();
+        if (frames.some(frame => 'width' in frame || 'inlineSize' in frame)) {
+          state.animatesWidth = true;
+        }
+      }
+      requestAnimationFrame(sample);
+    };
+    requestAnimationFrame(sample);
+  });
+  for (let index = 0; index < presses; index++) {
+    if (index > 0) {
+      await page.waitForTimeout(gapMs);
+    }
+    await press();
+  }
+  await page.waitForTimeout(durationMs);
+  return page.evaluate(() => {
+    const state = (
+      window as unknown as {
+        railFrames: Omit<Frames, 'edges'> & {
+          running: boolean;
+          edges: Set<number>;
+        };
+      }
+    ).railFrames;
+    state.running = false;
+    const {frames, maxGap, animatesWidth, copiesHidden, copiesSeen} = state;
+    const {wrapCopiesSeen} = state;
+    const edges = state.edges.size;
+    return {
+      frames,
+      maxGap,
+      animatesWidth,
+      copiesHidden,
+      copiesSeen,
+      wrapCopiesSeen,
+      edges,
+    };
+  });
+}
+
+/** The rail's width and whether its labels show, at rest. */
+async function railAtRest(page: Page) {
+  return page.evaluate(() => {
+    const panel = document.querySelector('.astryx-layout-panel') as HTMLElement;
+    const label = [...panel.querySelectorAll('span, div')].find(
+      element =>
+        element.children.length === 0 && element.textContent === 'Analytics',
+    );
+    const shown =
+      label != null &&
+      label.getBoundingClientRect().width > 0 &&
+      label.checkVisibility({
+        opacityProperty: true,
+        visibilityProperty: true,
+      }) &&
+      label.getBoundingClientRect().right <=
+        panel.getBoundingClientRect().right + 0.5;
+    return {
+      width: Math.round(panel.getBoundingClientRect().width),
+      labelsShown: shown,
+      copies: document.querySelectorAll('[inert]').length,
+      running: document.getAnimations().length,
+    };
+  });
+}
+
+function toggleButton(page: Page) {
+  return page.getByRole('button', {name: /^(Collapse|Expand) sidebar$/});
+}
+
+/** Every running animation's animated properties and duration. */
+async function runningMotion(page: Page) {
+  return page.evaluate(() =>
+    document.getAnimations().map(animation => {
+      const effect = animation.effect as KeyframeEffect;
+      const properties = new Set<string>();
+      for (const frame of effect.getKeyframes()) {
+        for (const key of Object.keys(frame)) {
+          if (
+            !['offset', 'computedOffset', 'easing', 'composite'].includes(key)
+          ) {
+            properties.add(key);
+          }
+        }
+      }
+      return {
+        properties: [...properties],
+        duration: Number(effect.getTiming().duration),
+        holdsPage:
+          effect.target instanceof Element &&
+          effect.target.contains(document.querySelector('[role="main"]')),
+      };
+    }),
+  );
+}
+
+test.describe('component:SideNav FR6 and component:AppShell FR17 under a finger', () => {
+  test('a tap collapses and expands the rail with its edge on the content on every frame, no width animation, and a hidden copy gone at rest', async ({
+    page,
+  }) => {
+    await openStory(page, PHONE_STORY);
+    expect(
+      await page.evaluate(() => matchMedia('(pointer: coarse)').matches),
+    ).toBe(true);
+    const expanded = await railAtRest(page);
+    expect(expanded.labelsShown).toBe(true);
+
+    const collapse = await sampleMotion(page, async () => {
+      await toggleButton(page).tap();
+    });
+    expect(collapse.frames).toBeGreaterThan(20);
+    expect(collapse.maxGap).toBeLessThanOrEqual(1);
+    expect(collapse.edges).toBeGreaterThan(5);
+    expect(collapse.animatesWidth).toBe(false);
+    expect(collapse.copiesSeen).toBe(1);
+    expect(collapse.copiesHidden).toBe(true);
+    const collapsed = await railAtRest(page);
+    expect(collapsed).toMatchObject({
+      labelsShown: false,
+      copies: 0,
+      running: 0,
+    });
+    expect(collapsed.width).toBeLessThan(expanded.width);
+
+    const expand = await sampleMotion(page, async () => {
+      await toggleButton(page).tap();
+    });
+    expect(expand.maxGap).toBeLessThanOrEqual(1);
+    expect(expand.edges).toBeGreaterThan(5);
+    expect(expand.animatesWidth).toBe(false);
+    expect(expand.copiesHidden).toBe(true);
+    expect(await railAtRest(page)).toMatchObject({
+      width: expanded.width,
+      labelsShown: true,
+      copies: 0,
+      running: 0,
+    });
+  });
+
+  test('a second tap while the motion runs keeps the rail and the content together and lands in the second state', async ({
+    page,
+  }) => {
+    await openStory(page, PHONE_STORY);
+    const expanded = await railAtRest(page);
+    const frames = await sampleMotion(
+      page,
+      async () => {
+        await toggleButton(page).tap();
+      },
+      {
+        presses: 2,
+        gapMs: 150,
+      },
+    );
+    expect(frames.maxGap).toBeLessThanOrEqual(1);
+    expect(frames.edges).toBeGreaterThan(5);
+    expect(frames.animatesWidth).toBe(false);
+    expect(frames.copiesSeen).toBeLessThanOrEqual(1);
+    expect(await railAtRest(page)).toMatchObject({
+      width: expanded.width,
+      labelsShown: true,
+      copies: 0,
+      running: 0,
+    });
+  });
+
+  test('an expand whose old wrap cannot be copied keeps the rail and the content together', async ({
+    page,
+  }) => {
+    await openStory(page, PHONE_STORY);
+    await sampleMotion(page, async () => {
+      await toggleButton(page).tap();
+    });
+    // More elements than the swap copies: the old wrap is not copied.
+    await page.evaluate(() => {
+      const holder = document.createElement('div');
+      for (let index = 0; index < 1600; index++) {
+        holder.appendChild(document.createElement('span'));
+      }
+      document.querySelector('[role="main"]')?.appendChild(holder);
+    });
+    const expand = await sampleMotion(page, async () => {
+      await toggleButton(page).tap();
+    });
+    expect(expand.maxGap).toBeLessThanOrEqual(1);
+    expect(expand.edges).toBeGreaterThan(5);
+    expect(expand.animatesWidth).toBe(false);
+    // The fallback branch ran: no copy of the old wrap was made.
+    expect(expand.wrapCopiesSeen).toBe(0);
+    expect(await railAtRest(page)).toMatchObject({
+      labelsShown: true,
+      copies: 0,
+    });
+  });
+
+  test('under Reduce Motion a tap only cross-fades, in 200 ms or less, with the page surface still (design:reduced-motion DR2)', async ({
+    page,
+  }) => {
+    await page.emulateMedia({reducedMotion: 'reduce'});
+    await openStory(page, PHONE_STORY);
+    await toggleButton(page).tap();
+    const motion = await runningMotion(page);
+    expect(motion.length).toBeGreaterThan(0);
+    for (const {properties, duration, holdsPage} of motion) {
+      expect(properties).toEqual(['opacity']);
+      expect(duration).toBeLessThanOrEqual(200);
+      expect(holdsPage).toBe(false);
+    }
+    await page.waitForTimeout(400);
+    expect(await railAtRest(page)).toMatchObject({
+      labelsShown: false,
+      copies: 0,
+    });
+  });
+});
+
+test.describe('component:SideNav FR6 and component:AppShell FR17 under a mouse', () => {
+  test.use({
+    isMobile: false,
+    hasTouch: false,
+    viewport: {width: 1280, height: 800},
+  });
+
+  test('a click collapses and expands the rail with its edge on the content on every frame and no width animation', async ({
+    page,
+  }) => {
+    await openStory(page, DESKTOP_STORY);
+    expect(
+      await page.evaluate(() => matchMedia('(pointer: fine)').matches),
+    ).toBe(true);
+    const expanded = await railAtRest(page);
+    const collapse = await sampleMotion(page, async () => {
+      await toggleButton(page).click();
+    });
+    expect(collapse.maxGap).toBeLessThanOrEqual(1);
+    expect(collapse.edges).toBeGreaterThan(5);
+    expect(collapse.animatesWidth).toBe(false);
+    expect(collapse.copiesHidden).toBe(true);
+    expect(await railAtRest(page)).toMatchObject({
+      labelsShown: false,
+      copies: 0,
+      running: 0,
+    });
+    const expand = await sampleMotion(page, async () => {
+      await toggleButton(page).click();
+    });
+    expect(expand.maxGap).toBeLessThanOrEqual(1);
+    expect(expand.edges).toBeGreaterThan(5);
+    expect(expand.animatesWidth).toBe(false);
+    expect(await railAtRest(page)).toMatchObject({
+      width: expanded.width,
+      labelsShown: true,
+      copies: 0,
+    });
+  });
+
+  test('under Reduce Motion a click changes the rail and the page at once (design:reduced-motion DR3)', async ({
+    page,
+  }) => {
+    await page.emulateMedia({reducedMotion: 'reduce'});
+    await openStory(page, DESKTOP_STORY);
+    await toggleButton(page).click();
+    expect(await runningMotion(page)).toEqual([]);
+    expect(await railAtRest(page)).toMatchObject({
+      labelsShown: false,
+      copies: 0,
+    });
+  });
+});