@astryxdesign/core 0.7.5 → 0.7.6-canary.5cd7a15

package/src/List/ListItem.spec.md

@@ -0,0 +1,205 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:ListItem
+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]
+verified_by:
+  [
+    packages/core/src/List/List.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: [family:navigation-destinations]
+design_specs: []
+architecture:
+  [
+    architecture:component-style-authoring,
+    architecture:component-theming-surface,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: [spec:AST-057, spec:AST-103]
+---
+
+# ListItem component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                           |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | `ListItem` with `label`, `description`, `startContent`, `endContent`, `onClick`, `interactiveRef`, `href`, `target`, `rel`, `align`, `isDisabled`, `isSelected`, `swipeActions`, `swipeBehavior`, `xstyle`, `className`, `style`, and `ref`; the row carries `component:List`'s `list-item` target. `itemKey` (`spec:AST-103` DEC-4) is specified but not shipped. |
+| Behavior                | One `<li>` row rendered by `component:Item`, which receives every row prop. Inside a List the row takes the list's density, dividers, edge treatment, and marker; outside a List it uses Item's defaults and draws no marker.                                                                                                                                      |
+| End-user impact         | Each list entry reads as one list item, with the list's bullet, number, or task checkbox before it and the same interaction Item gives any row.                                                                                                                                                                                                                    |
+| Builder impact          | None.                                                                                                                                                                                                                                                                                                                                                              |
+| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps, listed under Current-state impact.                                                                                                                                                                                                                                                            |
+| Review checks           | Reject a row that is not an `<li>`, a ListItem-level edge, density, or divider prop, a marker drawn outside a marked List, or a dropped Item prop.                                                                                                                                                                                                                 |
+| Governing rules         | `component:Item` (`align` for start and end content); `component:List`; `family:navigation-destinations`; `spec:AST-057`; `spec:AST-103`; `architecture:component-theming-surface`; `architecture:component-style-authoring` INV7.                                                                                                                                 |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+ListItem is the row a List renders for each entry. It owns turning a row into
+a list item: the `<li>` element, what it reads from its List, the marker drawn
+before it, and how it applies `component:List`'s `list-item` target. Everything a row does as a row comes
+from `component:Item`. Consumer usage lives in `ListItem.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: not applicable; `isSelected` and
+  `isDisabled` are caller-owned
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Markers are extra elements.** A bullet marker is drawn as two decorative
+  `span` elements, and a number marker as one `span` carrying a counter
+  pseudo-element, beside the row's content. `architecture:component-style-authoring`
+  INV7 carries decoration with no semantic role on a pseudo-element rather than
+  an added element.
+- **ListItem has no `itemKey` yet.** `spec:AST-103` DEC-4 and `component:List`
+  FR12 have each reorderable row name its item through an `itemKey` prop;
+  ListItem does not accept one yet.
+
+## Ownership boundary
+
+**Owns**
+
+- Rendering the row as an `<li>` through `component:Item` and passing it every
+  row prop (FR1).
+- Reading density, dividers, edge treatment, and marker from the enclosing
+  List, and the defaults outside one (FR2, FR3).
+- Drawing the marker or a task item's read-only checkbox (FR4).
+- Applying `component:List`'s `list-item` target to the row (FR5).
+
+**Does not own / non-goals**
+
+- `align`, the start and end content's alignment — owned by `component:Item`; swipe actions — owned by
+  `spec:AST-057`; link destinations — owned by
+  `family:navigation-destinations`, of which ListItem is a member.
+- Item's label, description, slots, invisible button, delegated activation,
+  and disabled and selected semantics — Item's shipped behavior, uncontracted
+  here.
+- What each edge treatment does to row geometry and the row inset, the touch
+  target, press paint, row motion, and row menus — owned by `component:List`.
+- The `ListMarkerScope` that sets a marker or task state for Markdown's nested
+  lists — internal and uncontracted here.
+- Whole number markers and text alignment for Markdown lists — owned by
+  `spec:AST-061` FR11 and `component:List` DEC-5.
+
+## Public concepts
+
+No component-local concept beyond the consumer props; row props are
+`component:Item`'s.
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                               | Basis                    |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | ListItem renders `component:Item` as an `<li>` and passes `label`, `description`, `startContent`, `endContent`, `onClick`, `interactiveRef`, `href`, `target`, `rel`, `align`, `isDisabled`, `isSelected`, `swipeActions`, `swipeBehavior`, and `ref` to it unchanged, with other DOM and data props reaching the row.                                                                                                                                  | Current source and tests |
+| FR2 | Inside a List, the row takes the list's `density`, its `hasDividers` setting, which draws a divider between rows with no extra element and square corners, and its `edge` treatment.                                                                                                                                                                                                                                                                    | Current source and tests |
+| FR3 | Outside a List, the row uses `balanced` density, no dividers, the `padded` treatment, and no marker, keeping Item's inline inset.                                                                                                                                                                                                                                                                                                                       | Current source and tests |
+| FR4 | In a List whose `listStyle` is `disc`, `circle`, or `decimal`, the row draws that marker before its content: a disc or circle shape, or a counter number. A task state set for the row draws a read-only, labelled checkbox in the marker's place. Each marker and the task checkbox sit on the label's first line. A List whose `listStyle` is `none` draws neither. Other markers, set internally for Markdown's nested lists, are uncontracted here. | Current source and tests |
+| FR5 | The row carries `component:List`'s `list-item` target, merged with the caller's `className` and `style`; `xstyle` applies after ListItem's own styles.                                                                                                                                                                                                                                                                                                  | Current source           |
+
+### Allowed variation
+
+- **AV1 — Row content.** Label, description, and slot content vary.
+- **AV2 — Theme styling.** Themes restyle `list-item`.
+
+### Representative states
+
+| State                | Required invariant                               | Allowed variation |
+| -------------------- | ------------------------------------------------ | ----------------- |
+| Static row in a List | One `<li>`; no button or anchor.                 | Content.          |
+| Interactive row      | Item's invisible button or anchor; one tab stop. | Content.          |
+| Divided list         | A divider between rows; square corners.          | Density.          |
+| Numbered list        | A counter number before each row.                | Number style.     |
+| Task row             | A read-only checkbox in the marker's place.      | Checked state.    |
+| Row outside a List   | Item's inline inset; no marker.                  | Content.          |
+
+### Transformation and precedence order
+
+- **ORD1 — Marker.** No marker when the List's `listStyle` is `none`; otherwise
+  a task checkbox when the row has a task state, then the marker.
+- **ORD2 — Styling.** ListItem's own styles, then the caller's `xstyle`.
+
+### Performance and resources
+
+- No resource rule.
+
+## Accessibility contract
+
+- **AR1 — List semantics.** Inside a List, each row is an `<li>` in the List's
+  `<ul>` or `<ol>` (FR1).
+- **AR2 — Row semantics.** Item's interaction, disabled, and selected semantics
+  apply unchanged; they are Item's shipped behavior, uncontracted here.
+- **AR3 — Task state.** A task row's checkbox is read-only and labelled (FR4).
+
+## Design relationships
+
+| Anatomy or state | Design requirement                              | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Row              | Presents one list entry through Item.           | `component:Item`         | Prominent      | FR1, FR5           |
+| Marker           | Shows the list's bullet, number, or task state. | Current source           | Supporting     | FR4                |
+
+No anatomy-theming map is recorded yet; the block is optional during
+migration, so the map is deferred.
+
+## Family and system relationships
+
+- `component:Item` owns `align`, the start and end content's alignment; its
+  other row behavior is
+  uncontracted. `spec:AST-057` owns swipe actions and
+  `family:navigation-destinations` owns link destinations.
+- `component:List` owns the edge treatment and its row geometry and inset;
+  its record leaves the density, divider, and marker-style settings
+  uncontracted, and FR2 and FR4 here cover what a row does with them.
+- `architecture:component-theming-surface` owns target qualification;
+  `component:List` owns the `list-item` target, and FR5 covers how the row
+  applies it.
+
+## Verification map
+
+| Contract | Verification                                                                     | Representative states                          | Mutation or failure expectation                        | Audit section                  |
+| -------- | -------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------ | ------------------------------ |
+| FR1, AR1 | `List.test.tsx` row element, align, data attribute, and swipe pass-through tests | Static and interactive rows                    | A row that is not an `<li>`, or a dropped prop, fails. | `audit:ListItem/behavior`      |
+| FR2      | `List.test.tsx` density, divider, radius, and edge treatment tests               | Each density; dividers on and off; each edge   | A row that ignores its List's settings fails.          | `audit:ListItem/layout`        |
+| FR3      | `List.test.tsx` "keeps the inset of a ListItem outside a List"                   | Row outside a List                             | A row outside a List that loses its inset fails.       | `audit:ListItem/layout`        |
+| FR4, AR3 | `List.test.tsx` marker and ListMarkerScope tests                                 | Presence of a marker, none, scope marker, task | A missing, extra, or unlabelled marker fails.          | `audit:ListItem/anatomy`       |
+| AR2      | `List.test.tsx` invisible button, anchor, disabled, and selection tests          | Click, href, disabled, selected                | Lost row semantics fail.                               | `audit:ListItem/accessibility` |
+
+Read from source, with no focused test yet:
+
+- FR1: `interactiveRef`, `rel`, and `ref` reaching the Item row.
+- FR2: the divider border and square corners.
+- FR4: each marker and the task checkbox sitting on the label's first line.
+- FR3: `balanced` density, no dividers, and no marker outside a List.
+- FR4: the shape of each bullet marker (the disc's fill, the circle's ring),
+  and the number marker and its counter.
+- FR5: the `list-item` target, and `xstyle` applying after ListItem's styles.
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, Item's row behavior, or
+List's edge and geometry rules. It links to their owners.

package/src/List/ListItem.tsx

@@ -39,9 +39,9 @@ import {
 } from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import {ListContext, type ListMarker} from './ListContext';
-import {CheckboxInput} from '../CheckboxInput';
-import {mergeProps} from '../utils';
-import {Item} from '../Item';
+import {CheckboxInput} from '../CheckboxInput/CheckboxInput';
+import {mergeProps} from '../utils/mergeProps';
+import {Item} from '../Item/Item';
 import {ItemMarkerColumnsContext} from '../Item/ItemMarkerColumnsContext';
 import type {ItemAlign, ItemSwipeActions, ItemSwipeBehavior} from '../Item';
 import {themeProps} from '../utils/themeProps';

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/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
 

package/src/MultiSelector/MultiSelector.test.tsx

@@ -9,7 +9,15 @@
  * SYNC: When MultiSelector.tsx API changes, update these tests.
  */
 
-import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeAll,
+  beforeEach,
+  afterEach,
+} from 'vitest';
 import {
   act,
   render,
@@ -65,6 +73,15 @@ function politeRegion(): HTMLElement | null {
 }
 
 // Mock showPopover and hidePopover methods since they're not implemented in jsdom
+// The bottom-sheet presentation renders BottomSheet through React.lazy. Its
+// first import transforms the BottomSheet module tree, which on a loaded
+// runner takes longer than a query's 1 s wait, so the first sheet test timed
+// out before the dialog existed. Load the module once up front: lazy() then
+// resolves from the module cache and every sheet test waits only on the open.
+beforeAll(async () => {
+  await import('../BottomSheet/BottomSheet');
+});
+
 beforeEach(() => {
   __resetInteractionModalityForTest();
   HTMLDialogElement.prototype.showModal = vi.fn(function (
@@ -128,6 +145,13 @@ function expectSilentBusySpinner() {
   expect(screen.queryByRole('status', {name: 'Loading'})).toBeNull();
 }
 
+// The bottom sheet is loaded on demand (SelectorBottomSheet's lazy import).
+// Loading its module is not part of an open, so the file waits for it once
+// here, and each test's open waits only for the open.
+beforeAll(async () => {
+  await import('../BottomSheet/BottomSheet');
+});
+
 describe('MultiSelector', () => {
   const defaultOptions = ['Apple', 'Banana', 'Orange'];
 
@@ -1388,6 +1412,58 @@ describe('MultiSelector', () => {
     expect(within(listbox).getByText('Add a fruit first')).toBeInTheDocument();
   });
 
+  describe('count trigger text', () => {
+    it('shows the default count in the catalog message', () => {
+      render(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={['Apple', 'Banana']}
+          onChange={() => {}}
+          triggerDisplay="count"
+        />,
+      );
+      expect(screen.getByText('2 selected')).toBeInTheDocument();
+    });
+
+    it('translates the default count, with plural forms, under another locale', () => {
+      render(
+        <InternationalizationProvider
+          locale="fr"
+          overrides={{
+            fr: {
+              '@astryx.multiSelector.selectedCount':
+                '{count, number} {count, plural, one {sélectionné} other {sélectionnés}}',
+            },
+          }}>
+          <MultiSelector
+            label="Fruit"
+            options={defaultOptions}
+            value={['Apple', 'Banana']}
+            onChange={() => {}}
+            triggerDisplay="count"
+          />
+        </InternationalizationProvider>,
+      );
+      expect(screen.getByText('2 sélectionnés')).toBeInTheDocument();
+      expect(screen.queryByText('2 selected')).not.toBeInTheDocument();
+    });
+
+    it('still lets formatValue replace the count text', () => {
+      render(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={['Apple', 'Banana']}
+          onChange={() => {}}
+          triggerDisplay="count"
+          formatValue={items => `${items.length} fruits`}
+        />,
+      );
+      expect(screen.getByText('2 fruits')).toBeInTheDocument();
+    });
+  });
+
   describe('result announcements', () => {
     it('announces the match count politely while searching', async () => {
       const user = userEvent.setup();
@@ -3436,6 +3512,47 @@ describe('MultiSelector trigger render prop', () => {
     expect(screen.queryByText('Labels')).toBeNull();
   });
 
+  // spec:AST-055 AR3: a light dismiss returns focus to the caller's control,
+  // even when the press that closed the list focused another field.
+  it('returns focus to the caller control after a light dismiss onto another field', async () => {
+    const user = userEvent.setup();
+    render(
+      <>
+        <MultiSelector
+          label="Labels"
+          options={OPTIONS}
+          value={[]}
+          onChange={() => {}}
+          renderTrigger={props => (
+            <button type="button" {...props}>
+              Pick labels
+            </button>
+          )}
+        />
+        <input aria-label="Notes" />
+      </>,
+    );
+    const opener = screen.getByRole('button', {name: 'Pick labels'});
+    await user.click(opener);
+    expect(opener).toHaveAttribute('aria-expanded', 'true');
+
+    act(() => {
+      screen.getByRole('textbox', {name: 'Notes'}).focus();
+    });
+    const popover = document.querySelector('[popover]') as HTMLElement;
+    act(() => {
+      popover.dispatchEvent(
+        Object.assign(new Event('toggle'), {
+          oldState: 'open',
+          newState: 'closed',
+        }),
+      );
+    });
+
+    expect(opener).toHaveAttribute('aria-expanded', 'false');
+    expect(opener).toHaveFocus();
+  });
+
   it('opens against the caller control and names the listbox by label', async () => {
     const user = userEvent.setup();
     render(

package/src/MultiSelector/MultiSelector.tsx

@@ -905,7 +905,7 @@ export interface MultiSelectorProps<
    * Not called when nothing is selected — the placeholder shows instead — and
    * not called for triggerDisplay 'badges', which renders Badge elements
    * rather than text.
-   * @default items => `${items.length} selected` for 'count', "A, B, C, +N" for 'labels'
+   * @default the translated `@astryx.multiSelector.selectedCount` message ("2 selected") for 'count', "A, B, C, +N" for 'labels'
    */
   formatValue?: (items: MultiSelectorSelectedItem[]) => string;
 
@@ -1450,6 +1450,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     onHide: handleLayerHide,
     onShow: handleLayerShow,
     triggerRef,
+    isFocusReturnAlways: hasExternalTrigger,
     popoverOptions: {
       hasLightDismiss: true,
       hasCloseButton: false,
@@ -1890,7 +1891,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
         return (
           <span {...stylex.props(styles.triggerText)}>
             {formatValue?.(selectedItems) ??
-              `${optimisticValue.length} selected`}
+              t('@astryx.multiSelector.selectedCount', {
+                count: optimisticValue.length,
+              })}
           </span>
         );
 
@@ -1933,6 +1936,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     placeholder,
     formatValue,
     maxBadges,
+    t,
   ]);
 
   // Render search input

package/src/MultiSelector/__tests__/MultiSelector.listbox.a11y.test.tsx

@@ -9,7 +9,7 @@
 
 import {cleanup, render, screen, within} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {describe, expect, it} from 'vitest';
+import {beforeAll, describe, expect, it} from 'vitest';
 import {
   expectAccessibilitySpec,
   LISTBOX_PATTERN,
@@ -23,6 +23,13 @@ import {installListboxDialogStubs} from '../../Selector/__tests__/Listbox.a11y.d
 
 installListboxDialogStubs();
 
+// The bottom sheet is loaded on demand (SelectorBottomSheet's lazy import).
+// Loading its module is not part of an open, so the file waits for it once
+// here, and each scenario's open waits only for the open.
+beforeAll(async () => {
+  await import('../../BottomSheet/BottomSheet');
+});
+
 const scenarios = LISTBOX_SCENARIOS.filter(
   scenario => scenario.component === 'MultiSelector',
 );

package/src/NavMenu/NavHeadingMenu.spec.md

@@ -44,7 +44,7 @@ system_specs: [spec:AST-005/DEC-1, spec:AST-020, spec:AST-085]
 | Behavior                | A `role="menu"` list of `menuitem` rows inside a heading popover, with arrow, Home, End, typeahead, Enter, Space, and Escape support. Selecting an enabled item runs it and, where the host heading supplies a close action, closes the heading menu.                 |
 | End-user impact         | Users switch products or accounts from the heading menu by pointer or keyboard; disabled rows are skipped by keyboard and typeahead.                                                                                                                                  |
 | Builder impact          | None.                                                                                                                                                                                                                                                                 |
-| Compatibility/readiness | Records shipped behavior; no public change. Six implementation gaps (see Current-state impact).                                                                                                                                                                       |
+| Compatibility/readiness | Records shipped behavior; no public change. Five implementation gaps (see Current-state impact).                                                                                                                                                                       |
 | Review checks           | Reject losing `menu`/`menuitem` roles to caller props, keyboard focus landing on a disabled item, or a caller `onKeyDown` that silently disables the keyboard model.                                                                                                  |
 | Governing rules         | `family:navigation-destinations` FR7; `architecture:interaction-modality`; `architecture:component-theming-surface`; `architecture:layer-runtime`.                                                                                                                    |
 
@@ -81,10 +81,6 @@ Consumer migration instructions belong in consumer docs and release notes.
   `role="menu"` sits directly inside the heading's own `role="menu"` wrapper.
   WAI-ARIA 1.2 allows a `menu` to own only `menuitem`-family items and groups,
   so assistive technology meets a menu nested in a menu.
-- **Inside a heading, arrow keys move twice.** Inside SideNavHeading or
-  TopNavHeading, the heading's own list handler also moves focus over every
-  `menuitem`, so one ArrowDown moves two items, and in a two-item menu ArrowDown
-  never moves focus. The APG menu pattern moves focus one item per arrow press.
 - **The menu has no name of its own.** NavHeadingMenu's `menu` carries no
   accessible name unless the caller passes `aria-label`; inside a heading only
   the heading's wrapper `menu` is named. The APG menu pattern, which