@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

package/src/MetadataList/MetadataListItem.spec.md

@@ -0,0 +1,165 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:MetadataListItem
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-31
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/MetadataList/MetadataList.test.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [architecture:component-theming-surface, architecture:public-component-api]
+contributing: []
+system_specs: [spec:AST-009]
+---
+
+# MetadataListItem component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | `label` (a string), `children` (the value), optional `icon`, root `BaseProps`, and a `ref`.                                                |
+| Behavior                | One label and value pair, rendered as a `dt` and `dd` either side by side in the list's grid or stacked inside a wrapper.                  |
+| End-user impact         | People read each fact's label next to or above its value, and assistive technology pairs them.                                             |
+| Builder impact          | None; the record describes shipped behavior.                                                                                               |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes.                                                                 |
+| Review checks           | Reject a pair that is not `dt` and `dd`, a wrapper in the side-by-side layout, or caller props that move off the element carrying the ref. |
+| Governing rules         | `architecture:public-component-api` INV5–INV8; `architecture:component-theming-surface`; WCAG 2.2 SC 1.3.1.                                |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+MetadataListItem is one key and value entry inside a MetadataList. It owns the
+entry's term and definition markup and their type; the caller owns the label,
+icon, and value.
+
+Consumer syntax and examples belong in `MetadataListItem.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes` — side by side outside a stacked list.
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  target, or styling output changes.
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The entry's `dt` and `dd`, the stacked wrapper, and the `metadata-list-item`
+  target that `component:MetadataList` maps.
+- Label and value type, the icon slot, and where caller inputs land.
+
+**Does not own / non-goals**
+
+- Label position, columns, and orientation — owned by
+  `component:MetadataList`.
+- The label, icon, and value content — owned by the caller.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning                                  | Availability by variant/orientation/state | Default      | Owner                    | Stability | Invalid-value behavior |
+| ------- | ----------------------- | ---------------------------------------- | ----------------------------------------- | ------------ | ------------------------ | --------- | ---------------------- |
+| Label   | string                  | The entry's key.                         | Always                                    | —            | caller                   | Stable    | —                      |
+| Value   | ReactNode (`children`)  | The entry's value.                       | Always                                    | —            | caller                   | Stable    | —                      |
+| Icon    | ReactNode; unset        | Content shown before the label.          | Always                                    | unset        | caller                   | Stable    | —                      |
+| Layout  | side by side; stacked   | Set by the parent list, not by the item. | Always                                    | side by side | `component:MetadataList` | Stable    | —                      |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                               | Basis                                                                   |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| FR1 | Side by side (labels at the start, or outside a MetadataList), the item renders a `dt` holding the icon and label, then a `dd` holding the value, as direct children of the list's grid. The `dt` carries the `metadata-list-item` target, the `ref`, and the caller's props and styling inputs; a `data-testid` becomes `<id>-label` on the `dt` and `<id>-value` on the `dd`. Both cells are at least 24px tall and break long words. | Current source and tests                                                |
+| FR2 | Stacked (labels on top, or a horizontal list), the item renders a `div` wrapper carrying the `metadata-list-item` target, the `ref`, `data-testid`, and the caller's props and styling inputs, holding the `dt` above the `dd` with a `--spacing-0-5` gap.                                                                                                                                                                              | Current source and tests                                                |
+| FR3 | The label uses medium-weight body type in secondary text color; the value uses body type in primary text color. An icon sits before the label with a `--spacing-2` gap.                                                                                                                                                                                                                                                                 | Current source and docs                                                 |
+| FR4 | `xstyle`, `className`, and `style` compose after component styles on the element carrying the target, and caller props reach that element after the component's own attributes.                                                                                                                                                                                                                                                         | Current source and tests; `architecture:public-component-api` INV5–INV8 |
+
+### Allowed variation
+
+- **AV1 — Content.** Any string may be the label; any ReactNode may be the
+  icon or value.
+
+### Representative states
+
+| State        | Required invariant                                                   | Allowed variation |
+| ------------ | -------------------------------------------------------------------- | ----------------- |
+| Side by side | `dt` and `dd` as grid siblings; target, ref, and props on the `dt`.  | Content.          |
+| Stacked      | One wrapper with the target, ref, and props, holding `dt` over `dd`. | Content.          |
+| With icon    | The icon precedes the label inside the `dt`.                         | Icon.             |
+
+### Transformation and precedence order
+
+- **ORD1 — Layout.** The parent list's horizontal orientation or `top` label
+  position → stacked; otherwise side by side.
+
+### Performance and resources
+
+- **PR1 — No resources.** MetadataListItem reads its parent list's label
+  position and orientation and holds no state.
+
+## Accessibility contract
+
+- **AR1 — Term and definition.** The label is a `dt` and the value its `dd`,
+  so assistive technology pairs them (WCAG 2.2 SC 1.3.1). The icon adds no
+  semantics of its own.
+
+## Design relationships
+
+| Anatomy or state | Design requirement          | Representation authority | Hierarchy role | Component contract |
+| ---------------- | --------------------------- | ------------------------ | -------------- | ------------------ |
+| Label            | Secondary-color medium key. | Current source and docs  | Supporting     | FR1–FR3            |
+| Metadata         | Primary-color value.        | Current source and docs  | Prominent      | FR1–FR3            |
+
+Theming: the `dt` (side by side) or the wrapper (stacked) carries the
+`metadata-list-item` target, which `MetadataList.doc.mjs` declares and
+`component:MetadataList` maps. `MetadataListItem.doc.mjs` declares no anatomy of
+its own, so no anatomy-theming block is declared here.
+
+## Family and system relationships
+
+- `component:MetadataList` owns layout, label position, and the target
+  mapping.
+- `architecture:public-component-api` owns caller-input routing; FR4 applies
+  it.
+- `spec:AST-009` owns accessibility-tree evidence; the verification map names
+  its gap.
+
+## Verification map
+
+| Contract | Verification                                                             | Representative states           | Mutation or failure expectation                                                                                                                                                                                                                                                                                                       | Audit section                     |
+| -------- | ------------------------------------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| FR1      | `MetadataList.test.tsx` item, label-width, and pass-through-target tests | Side by side                    | A missing label or value, a `dt` or `dd` that is not a direct child of the `dl`, wrong `-label` and `-value` test ids, or props or click handling that leave the `dt`, fails. Gap: no test attaches a `ref`, and the 24px minimum height has no check. No check fails if the side-by-side `dt` loses the `metadata-list-item` target. | `audit:MetadataListItem/layout`   |
+| FR2      | `MetadataList.test.tsx` stacked and stacked pass-through tests           | Stacked                         | A missing wrapper, `dt`, or `dd`, or props that leave the wrapper, fails. Gap: the stacked gap has no check. No test attaches a `ref` to the stacked wrapper.                                                                                                                                                                         | `audit:MetadataListItem/layout`   |
+| FR3      | `MetadataList.test.tsx` icon test                                        | With icon                       | A missing icon fails. Gap: label and value type and color and the icon gap have no automated check.                                                                                                                                                                                                                                   | `audit:MetadataListItem/design`   |
+| FR4      | `MetadataList.test.tsx` pass-through tests                               | `aria-label`, `id`, data; click | A dropped attribute or handler fails. Gap: no test covers `className`, `style`, or the `xstyle` merge order.                                                                                                                                                                                                                          | `audit:MetadataListItem/api`      |
+| AR1      | `MetadataList.test.tsx` role queries                                     | Term and definition             | A missing `term` or `definition` role in the DOM fails. Gap: no accessibility-tree check proves the pairing (`spec:AST-009` FR3).                                                                                                                                                                                                     | `audit:MetadataListItem/a11y`     |
+| PR1      | Source review                                                            | Every state                     | Gap: no automated check fails if MetadataListItem adds state.                                                                                                                                                                                                                                                                         | `audit:MetadataListItem/behavior` |
+
+## Decision log
+
+None recorded. The record describes shipped behavior.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or list layout rules. It links to their owners.

package/src/MobileNav/MobileNav.test.tsx

@@ -54,6 +54,21 @@ describe('MobileNav', () => {
     expect(dialog).not.toHaveAttribute('open');
   });
 
+  it('stays open when a file picker inside it is dismissed', () => {
+    const handleClose = vi.fn();
+    render(
+      <MobileNav isOpen={true} onOpenChange={handleClose}>
+        <input type="file" aria-label="Picture" />
+      </MobileNav>,
+    );
+    // A dismissed picker fires a bubbling `cancel` at the input; it is not a
+    // close request for the navigation.
+    const fromPicker = new Event('cancel', {bubbles: true, cancelable: true});
+    screen.getByLabelText('Picture').dispatchEvent(fromPicker);
+    expect(handleClose).not.toHaveBeenCalled();
+    expect(fromPicker.defaultPrevented).toBe(false);
+  });
+
   it('calls onOpenChange(false) on native cancel event (Escape)', () => {
     const handleClose = vi.fn();
     render(

package/src/MobileNav/MobileNav.tsx

@@ -225,7 +225,10 @@ const styles = stylex.create({
     display: 'flex',
     alignItems: 'center',
     justifyContent: 'space-between',
-    height: spacingVars['--spacing-12'],
+    // At least one bar high, and taller for header content that needs it (a
+    // stacked title and search, or a title wrapped at a larger text size), so
+    // it never runs into the first item below.
+    minHeight: spacingVars['--spacing-12'],
     paddingInline: spacingVars['--spacing-2'],
     flexShrink: 0,
     borderBlockEndWidth: borderVars['--border-width'],
@@ -648,6 +651,11 @@ export function MobileNav({
   // only, and never while an IME composition is in progress.
   const handleCancel = useCallback(
     (event: React.SyntheticEvent<HTMLDialogElement>) => {
+      // A cancel that bubbles up from inside (a dismissed file picker) is not
+      // a close request; the platform's is fired at the dialog itself.
+      if (event.target !== event.currentTarget) {
+        return;
+      }
       event.preventDefault();
       if (!shouldDismissOnCloseRequest()) {
         return;

package/src/MobileNav/__tests__/MobileNavHeader.a11y.chromium.spec.ts

@@ -0,0 +1,89 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MobileNavHeader.a11y.chromium.spec.ts
+ * @input Built MobileNav stories in a phone context in real Chromium
+ * @output Browser evidence that the header row is at least one bar high and
+ *   grows with taller header content: a stacked title and search field stay
+ *   inside the row, and the first navigation item starts below it
+ * @position Chromium proof for MobileNav's header row (`styles.header` in
+ *   MobileNav.tsx, `minHeight`); jsdom has no layout to measure it
+ */
+
+import {expect, test, type Page} 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();
+});
+
+test.use({
+  hasTouch: true,
+  isMobile: true,
+  viewport: {width: 390, height: 844},
+  deviceScaleFactor: 1,
+});
+
+/** Opens a story's drawer and returns the boxes of its header row and first item. */
+async function openAndMeasure(page: Page, story: string, firstItem: string) {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=core-mobilenav--${story}&viewMode=story`,
+  );
+  await page.getByRole('button', {name: 'Open Navigation'}).click();
+  const nav = page.getByRole('dialog');
+  await expect(nav).toBeVisible();
+  const close = nav.getByRole('button', {name: 'Close navigation'});
+  // The Close button sits in the header row.
+  const header = close.locator('xpath=..');
+  const headerBox = await header.boundingBox();
+  const itemBox = await nav
+    .getByRole('link', {name: firstItem})
+    .first()
+    .boundingBox();
+  if (headerBox == null || itemBox == null) {
+    throw new Error('the drawer did not render');
+  }
+  return {nav, header, headerBox, itemBox};
+}
+
+test('a one-line header keeps the one-bar row', async ({page}) => {
+  const {headerBox, itemBox} = await openAndMeasure(
+    page,
+    'default',
+    'Dashboard',
+  );
+  // --spacing-12 at the default root size, as before.
+  expect(headerBox.height).toBeCloseTo(48, 0);
+  expect(itemBox.y).toBeGreaterThanOrEqual(headerBox.y + headerBox.height);
+});
+
+test('a taller header grows its row, and the first item starts below it', async ({
+  page,
+}) => {
+  const {nav, headerBox, itemBox} = await openAndMeasure(
+    page,
+    'tall-header',
+    'Dashboard',
+  );
+  expect(headerBox.height).toBeGreaterThan(48);
+  const search = await nav.getByRole('textbox', {name: 'Search'}).boundingBox();
+  if (search == null) {
+    throw new Error('the search field did not render');
+  }
+  // The search field is inside the row, and nothing overlaps the first item.
+  expect(search.y).toBeGreaterThanOrEqual(headerBox.y);
+  expect(search.y + search.height).toBeLessThanOrEqual(
+    headerBox.y + headerBox.height,
+  );
+  expect(itemBox.y).toBeGreaterThanOrEqual(headerBox.y + headerBox.height);
+});

package/src/MoreMenu/MoreMenu.test.tsx

@@ -9,6 +9,7 @@
  * SYNC: When MoreMenu.tsx changes, update tests to match new behavior
  */
 
+import {createRef} from 'react';
 import {describe, it, expect, vi, beforeAll, beforeEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
@@ -256,6 +257,16 @@ describe('MoreMenu', () => {
     expect(handleEdit).not.toHaveBeenCalled();
   });
 
+  it('forwards its ref to the bottom-sheet trigger', () => {
+    const ref = createRef<HTMLButtonElement>();
+    render(
+      <MoreMenu items={defaultItems} ref={ref} presentation="bottom-sheet" />,
+    );
+    expect(ref.current).toBe(
+      screen.getByRole('button', {name: 'More options'}),
+    );
+  });
+
   it('supports forwardRef', () => {
     const ref = vi.fn();
     render(<MoreMenu items={defaultItems} ref={ref} />);

package/src/MultiSelector/CreateRow.a11y.chromium.spec.ts

@@ -78,10 +78,11 @@ async function politeSince(page: Page, since: number): Promise<string> {
 }
 
 /**
- * Matches a polite region whose newest message is `message`. Messages written
- * before the region exposes the previous one are joined in order
- * (spec:AST-086 FR9), so typing faster than a frame can leave the previous
- * keystroke's message ahead of the one under test.
+ * Matches a polite region whose newest message is `message`. Messages from
+ * different announcers written before the region exposes the previous one are
+ * joined in order (spec:AST-086 FR9), so the creation can follow a search
+ * status still waiting. The search's own statuses replace each other instead
+ * (its `hasReplace` announcer), so they are read whole.
  */
 function newestMessage(message: string): RegExp {
   const escaped = message.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -108,9 +109,7 @@ test('the create row is announced as it appears and the highlight survives it va
   // "Bu": a partial match plus the create row above it.
   await search.pressSequentially('Bu');
   await expect(page.getByRole('option')).toHaveText(['Create "Bu"', 'Bug']);
-  await expect
-    .poll(async () => politeSince(page, 0))
-    .toMatch(newestMessage('1 result'));
+  await expect.poll(async () => politeSince(page, 0)).toBe('1 result');
 
   // Highlight the create row, then type the letter that makes it vanish: the
   // highlight must not be left pointing at a row that no longer exists.
@@ -132,7 +131,7 @@ test('the create row is announced as it appears and the highlight survives it va
   await expect(page.getByRole('option')).toHaveText(['Create "Urgent"']);
   await expect
     .poll(async () => politeSince(page, beforeUrgent))
-    .toMatch(newestMessage('Create "Urgent"'));
+    .toBe('Create "Urgent"');
 
   // Enter commits: the caller adds the option, the search clears, and the new
   // label is a real row.

package/src/MultiSelector/MultiSelector.spec.md

@@ -182,10 +182,13 @@ and `aria-controls` for the listbox, the listbox carries `aria-label` from
 focused element that owns arrow, Enter, Escape, and typeahead keys while open,
 so an anchor that cannot take focus still leaves a keyboard path.
 
-The create row is a `role="option"` with `aria-selected="false"` and no
-checkbox indicator. When it is the only result, the polite live region
-announces its label rather than the empty-search message, so what is announced
-matches what is on screen; picking it announces the creation.
+The create row is a `role="option"` with `aria-selected="false"` and no checkbox
+indicator. When it is the only result, the polite live region announces its
+label rather than the empty-search message, so what is announced matches what is
+on screen; picking it announces the creation. The result count and the create
+row's label come from the search's own `useAnnounce({hasReplace: true})`
+instance, so a newer one replaces one not yet spoken (`spec:AST-086` FR9), and
+selection messages keep their own instance.
 
 ## Design relationships