@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/MultiSelector/MultiSelector.test.tsx

@@ -36,6 +36,21 @@ import {selectorPresentationStyles} from '../Selector/selectorPresentation.style
 import {groupStyles} from '../InputGroup/groupStyles';
 import {InputGroup, InputGroupText} from '../InputGroup';
 import {colorVars, focusVars} from '../theme/tokens.stylex';
+import {COMPACT_TOUCH_PRESENTATION_QUERY} from '../hooks/useAdaptivePresentation';
+
+/**
+ * Enters a search query as one change. Typing it key by key can land several
+ * keystrokes in one frame, whose result announcements are then joined into
+ * one (spec:AST-086 FR9), so a test of what one query announces pastes it.
+ */
+async function enterQuery(
+  user: ReturnType<typeof userEvent.setup>,
+  input: HTMLElement,
+  query: string,
+): Promise<void> {
+  await user.click(input);
+  await user.paste(query);
+}
 
 function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
   const {prose, component} = generateThemeCSS(theme);
@@ -146,7 +161,7 @@ describe('MultiSelector', () => {
     vi.stubGlobal(
       'matchMedia',
       vi.fn().mockImplementation((query: string) => ({
-        matches: query === '(max-width: 768px) and (pointer: coarse)',
+        matches: query === COMPACT_TOUCH_PRESENTATION_QUERY,
         media: query,
         onchange: null,
         addEventListener: vi.fn(),
@@ -1172,7 +1187,7 @@ describe('MultiSelector', () => {
     );
 
     await user.click(screen.getByRole('button', {name: 'Fruit'}));
-    await user.type(screen.getByRole('combobox', h), 'xyz');
+    await enterQuery(user, screen.getByRole('combobox', h), 'xyz');
 
     // The panel message is role="presentation", so the live region is the
     // only thing a screen reader gets — it has to say the same words.
@@ -1204,7 +1219,7 @@ describe('MultiSelector', () => {
     );
 
     await user.click(screen.getByRole('button', {name: 'Fruit'}));
-    await user.type(screen.getByRole('combobox', h), 'xyz');
+    await enterQuery(user, screen.getByRole('combobox', h), 'xyz');
 
     await waitFor(() =>
       expect(politeRegion()?.textContent).toBe(
@@ -1258,7 +1273,7 @@ describe('MultiSelector', () => {
     );
 
     await user.click(screen.getByRole('button', {name: 'Fruit'}));
-    await user.type(screen.getByRole('combobox', h), 'xyz');
+    await enterQuery(user, screen.getByRole('combobox', h), 'xyz');
 
     await waitFor(() =>
       expect(politeRegion()?.textContent).toBe('Nothing like that here'),
@@ -1396,7 +1411,7 @@ describe('MultiSelector', () => {
       );
       await user.click(screen.getByRole('button', {name: 'Fruit'}));
       // "an" matches Banana and Orange.
-      await user.type(screen.getByRole('combobox', h), 'an');
+      await enterQuery(user, screen.getByRole('combobox', h), 'an');
       await waitFor(() => {
         // The plural branch of a message no catalog supplies.
         expect(politeRegion()?.textContent).toBe('2 résultats');
@@ -1425,7 +1440,7 @@ describe('MultiSelector', () => {
       );
       await user.click(screen.getByRole('button', {name: 'Fruit'}));
       // "app" matches only Apple. Exact match, so "1 résultats" would fail.
-      await user.type(screen.getByRole('combobox', h), 'app');
+      await enterQuery(user, screen.getByRole('combobox', h), 'app');
       await waitFor(() => {
         expect(politeRegion()?.textContent).toBe('1 résultat');
       });
@@ -1449,7 +1464,7 @@ describe('MultiSelector', () => {
         </InternationalizationProvider>,
       );
       await user.click(screen.getByRole('button', {name: 'Fruit'}));
-      await user.type(screen.getByRole('combobox', h), 'xyz');
+      await enterQuery(user, screen.getByRole('combobox', h), 'xyz');
       await waitFor(() => {
         expect(politeRegion()?.textContent).toBe('Aucun résultat');
       });
@@ -1479,7 +1494,7 @@ describe('MultiSelector', () => {
       );
       await user.click(screen.getByRole('button', {name: 'Fruit'}));
       // "an" matches Banana and Orange.
-      await user.type(screen.getByRole('combobox', h), 'an');
+      await enterQuery(user, screen.getByRole('combobox', h), 'an');
       await waitFor(() => {
         // Same key through the catalog path rather than `overrides`.
         expect(politeRegion()?.textContent).toBe('2 résultats');
@@ -2183,7 +2198,7 @@ describe('MultiSelector', () => {
       vi.mocked(matchMedia).mockImplementation(
         (query: string) =>
           ({
-            matches: query === '(max-width: 768px) and (pointer: coarse)',
+            matches: query === COMPACT_TOUCH_PRESENTATION_QUERY,
             media: query,
             onchange: null,
             addEventListener: vi.fn(),
@@ -3884,7 +3899,7 @@ describe('MultiSelector hasCreate', () => {
       />,
     );
     await user.click(screen.getByRole('button', {name: 'Labels'}));
-    await user.type(screen.getByRole('combobox', h), 'Urgent');
+    await enterQuery(user, screen.getByRole('combobox', h), 'Urgent');
     // The empty-state message is role="presentation", so the live region is
     // what a screen reader gets — it must say what is on screen: a row.
     await waitFor(() => {
@@ -4588,3 +4603,100 @@ describe('MultiSelector in an InputGroup', () => {
     expect(groupClasses().some(c => classes.has(c))).toBe(false);
   });
 });
+
+describe('MultiSelector caller aria-labelledby', () => {
+  const FRUITS = ['Apple', 'Banana', 'Cherry'];
+
+  it('names the trigger by its label and a caller aria-labelledby', () => {
+    render(
+      <>
+        <span id="lunch-heading">Lunch</span>
+        <MultiSelector
+          label="Fruits"
+          options={FRUITS}
+          value={[]}
+          onChange={() => {}}
+          aria-labelledby="lunch-heading"
+        />
+      </>,
+    );
+    const trigger = screen.getByRole('combobox', {name: 'Fruits Lunch'});
+    expect(trigger.getAttribute('aria-labelledby')?.split(' ')).toContain(
+      'lunch-heading',
+    );
+  });
+
+  it('names a grouped trigger by the group, its label, and a caller aria-labelledby', () => {
+    render(
+      <>
+        <span id="lunch-heading">Lunch</span>
+        <InputGroup label="Order">
+          <MultiSelector
+            label="Fruits"
+            options={FRUITS}
+            value={[]}
+            onChange={() => {}}
+            aria-labelledby="lunch-heading"
+          />
+        </InputGroup>
+      </>,
+    );
+    expect(
+      screen.getByRole('combobox', {name: 'Order Fruits Lunch'}),
+    ).toBeInTheDocument();
+  });
+
+  it('leaves a standalone trigger named by its label element without a caller aria-labelledby', () => {
+    render(
+      <MultiSelector
+        label="Fruits"
+        options={FRUITS}
+        value={[]}
+        onChange={() => {}}
+      />,
+    );
+    const trigger = screen.getByRole('combobox', {name: 'Fruits'});
+    expect(trigger).not.toHaveAttribute('aria-labelledby');
+  });
+
+  it('still hands a caller aria-labelledby to a renderTrigger control unchanged', () => {
+    render(
+      <>
+        <span id="lunch-heading">Lunch</span>
+        <MultiSelector
+          label="Fruits"
+          options={FRUITS}
+          value={[]}
+          onChange={() => {}}
+          aria-labelledby="lunch-heading"
+          renderTrigger={props => (
+            <button type="button" {...props}>
+              Pick fruits
+            </button>
+          )}
+        />
+      </>,
+    );
+    const opener = screen.getByRole('button', {name: 'Lunch'});
+    expect(opener).toHaveAttribute('aria-labelledby', 'lunch-heading');
+  });
+
+  it("leaves a renderTrigger control's own aria-labelledby in place without a caller value", () => {
+    render(
+      <>
+        <span id="row-title">Lunch fruits</span>
+        <MultiSelector
+          label="Fruits"
+          options={FRUITS}
+          value={[]}
+          onChange={() => {}}
+          renderTrigger={props => (
+            <button type="button" aria-labelledby="row-title" {...props} />
+          )}
+        />
+      </>,
+    );
+    const opener = screen.getByRole('button', {name: 'Lunch fruits'});
+    expect(opener).toHaveAttribute('aria-labelledby', 'row-title');
+  });
+});

package/src/MultiSelector/MultiSelector.tsx

@@ -18,6 +18,7 @@
  */
 
 import React, {
+  use,
   useCallback,
   useEffect,
   useId,
@@ -74,6 +75,7 @@ import {
 } from '../Selector/utils';
 import {useMultiCombobox} from './hooks';
 import {getInputARIA, isImeKeyEvent, mergeProps} from '../utils';
+import {joinAriaIDs} from '../utils/inputAria';
 import {devWarn, warnOnce} from '../utils/devWarning';
 import {
   getInteractionModality,
@@ -99,8 +101,9 @@ import {themeProps} from '../utils/themeProps';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
-import {groupStyles} from '../InputGroup/groupStyles';
+import {groupStyles, inputGroupItemProps} from '../InputGroup/groupStyles';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
+import {InputGroupInternalContext} from '../InputGroup/InputGroupInternalContext';
 import {VisuallyHidden} from '../VisuallyHidden';
 import {useTranslator} from '../i18n';
 import type {AdaptivePresentation} from '../hooks/useAdaptivePresentation';
@@ -1087,7 +1090,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   description,
   isOptional = false,
   isRequired = false,
-  isDisabled = false,
+  isDisabled: isDisabledProp = false,
   isReadOnly = false,
   disabledMessage,
   options,
@@ -1134,8 +1137,12 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   onFocus,
   onKeyDown: onKeyDownProp,
   'aria-describedby': ariaDescribedByProp,
+  'aria-labelledby': ariaLabelledByProp,
   ...restProps
 }: MultiSelectorProps<T>) {
+  const inputGroup = useInputGroup();
+  const inputGroupState = use(InputGroupInternalContext);
+  const isDisabled = isDisabledProp || inputGroupState.isDisabled;
   const {rest, container} = useFieldInputStyling('MultiSelector', restProps, {
     containerXstyle,
     containerClassName,
@@ -1178,6 +1185,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   const listboxId = useId();
   const descriptionId = useId();
   const statusMessageId = useId();
+  const fieldLabelId = useId();
   const inputLabelId = useId();
   const readOnlyDescriptionId = useId();
   const searchId = useId();
@@ -1187,7 +1195,6 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   const triggerButtonRef = useMergedRefs<HTMLElement>(triggerRef, ref);
   const searchRef = useRef<HTMLInputElement>(null);
   const listboxRef = useRef<HTMLDivElement>(null);
-  const inputGroup = useInputGroup();
 
   const [searchQuery, setSearchQuery] = useState('');
   // A typed query shows the search row's clear (✕) button, which becomes
@@ -1241,6 +1248,12 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     ],
     inputGroup,
   );
+  // A caller aria-labelledby names the trigger together with the field's own
+  // label (the Field label standalone, the group and input labels in a group).
+  const triggerLabelledBy =
+    ariaLabelledByProp != null
+      ? joinAriaIDs(ariaLabelledBy ?? fieldLabelId, ariaLabelledByProp)
+      : ariaLabelledBy;
 
   // Flatten options for keyboard navigation
   const selectableItems = useMemo(
@@ -2445,7 +2458,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     'aria-describedby':
       [ariaDescribedByProp, ariaDescribedBy].filter(Boolean).join(' ') ||
       undefined,
-    'aria-labelledby': ariaLabelledBy,
+    'aria-labelledby': triggerLabelledBy,
     'aria-required': isEffectivelyRequired ? 'true' : undefined,
     'aria-invalid': status?.type === 'error' ? 'true' : undefined,
     'aria-busy': isBusy || undefined,
@@ -2481,6 +2494,11 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       // in this mode; the selector's own wiring below wins over them.
       ...rest,
       'aria-describedby': ariaDescribedByProp,
+      // Only a caller value is handed back, so a control that names itself
+      // with its own aria-labelledby before spreading keeps it.
+      ...(ariaLabelledByProp != null
+        ? {'aria-labelledby': ariaLabelledByProp}
+        : null),
       ref: mergeRefs<HTMLElement>(el => {
         popover.triggerRef(el);
         triggerRef.current = el;
@@ -2553,6 +2571,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
         }}
         onClick={handleControlBoxClick}
         {...pressable}
+        {...(inputGroup ? inputGroupItemProps : undefined)}
         {...mergeProps(
           themeProps('multi-selector', {
             variant,
@@ -2736,6 +2755,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={triggerId}
+      labelID={ariaLabelledByProp != null ? fieldLabelId : undefined}
       descriptionID={description ? descriptionId : undefined}
       isOptional={isOptional}
       isRequired={isRequired}

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

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y release-only
 
 /**
  * @file OptionActions.a11y.chromium.spec.ts

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

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y release-only
 
 /**
  * @file MultiSelector.a11y.chromium.spec.ts

package/src/NavIcon/NavIcon.spec.md

@@ -1,17 +1,22 @@
 ---
 schema_version: 3
-template_version: 3
+template_version: 7
 kind: component
 id: component:NavIcon
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-26
 owners: [cixzhang]
 review_triggers: [theming]
 verified_by:
-  [packages/core/src/NavIcon/NavIcon.test.tsx, scripts/check-knowledge.mjs]
+  [
+    packages/core/src/NavIcon/NavIcon.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    apps/storybook/stories/NavIcon.stories.tsx,
+    scripts/check-knowledge.mjs,
+  ]
 modules: []
 families: []
 design_specs: []
@@ -23,19 +28,33 @@ system_specs: []
 
 # NavIcon component contract
 
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                             |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | `NavIcon` with a required `icon`; target `nav-icon`.                                                                                 |
+| Behavior                | A display-only circular accent container, one medium element size square, that shows the caller's icon.                              |
+| End-user impact         | Users see a consistent product mark in navigation headings; NavIcon adds nothing to the accessibility tree beyond the caller's icon. |
+| Builder impact          | None.                                                                                                                                |
+| Compatibility/readiness | Records shipped behavior; no public change.                                                                                          |
+| Review checks           | Reject emitting any target besides `nav-icon`, or adding interaction semantics to the container.                                     |
+| Governing rules         | `architecture:component-theming-surface`; `architecture:public-component-api`.                                                       |
+
+This table is a review projection; the body below is authoritative.
+
 ## Intent
 
 NavIcon renders caller-supplied icon content inside a circular navigation
-container. This record preserves that runtime behavior while 0.7.0 removes the
-deprecated `navicon` theming alias.
+container, typically as the logo of TopNavHeading or SideNavHeading. Consumer
+usage lives in `NavIcon.doc.mjs`.
 
 ## Compatibility and migration
 
-- Released default preserved: `yes`; canonical `nav-icon` behavior is unchanged
-- Removed alias: 0.7.0 stops emitting `navicon`
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; the container emits only the
+  canonical `nav-icon` target
 - Controlled/uncontrolled behavior: not applicable
-- Migration decision: replace `navicon` theme keys and `.astryx-navicon` selectors
-  with `nav-icon` and `.astryx-nav-icon`, or run `astryx upgrade --from 0.6.3 --apply --path .`
+- Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
 
@@ -47,48 +66,54 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 **Does not own / non-goals**
 
-- The artwork or component supplied through `icon` — owned by the caller.
+- The artwork or component supplied through `icon` — owned by the caller,
+  including its accessible name or decorative status.
 - Interaction semantics — NavIcon remains a display-only container.
+- Spacing the heading applies around a NavIcon — owned by
+  `component:TopNavHeading` and `component:SideNavHeading`.
 
 ## Public concepts
 
-No new public concept is introduced. Consumer props and usage remain documented
-in `NavIcon.doc.mjs`.
+No component-local concept beyond the consumer props.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                    | Basis                           | Draft review state                                 |
-| --- | -------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
-| FR1 | The current render contains a circular container and the caller-supplied icon content. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
-| FR2 | The container carries the canonical `nav-icon` target.                                 | Current source, docs, and tests | Verified canonical behavior; 0.7 alias removed     |
+| ID  | Invariant                                                                                                                                                                           | Basis                           |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1 | NavIcon renders one `<span>` circular container, centered, sized to `--size-element-md` on both axes, painted with the accent color and on-accent foreground, that contains `icon`. | Current source, docs, and tests |
+| FR2 | The container carries only the canonical `nav-icon` target.                                                                                                                         | Current source, docs, and tests |
+| FR3 | The container forwards its `ref`, `data-testid`, and other DOM props, and merges `className`, `style`, and `xstyle` after component styles. It adds no role, name, or focus stop.   | Current source and tests        |
 
 ### Allowed variation
 
-- Caller-supplied icon artwork and implementation may vary without becoming
-  NavIcon-owned anatomy.
+- **AV1 — Artwork.** Caller-supplied icon artwork and implementation may vary
+  without becoming NavIcon-owned anatomy.
 
 ### Representative states
 
-- The documented anatomy is the same for every caller-supplied icon.
+| State    | Required invariant                  | Allowed variation |
+| -------- | ----------------------------------- | ----------------- |
+| Any icon | Same circular container and target. | Artwork.          |
 
 ### Transformation and precedence order
 
-- No new ordering rule is introduced.
+- No precedence rule.
 
 ### Performance and resources
 
-- No new performance or resource rule is introduced.
+- No resource rule.
 
 ## Accessibility contract
 
-This draft does not change or extend NavIcon's existing accessibility behavior.
+- **AR1 — Transparent container.** NavIcon contributes no semantics; the
+  caller's icon decides what assistive technology perceives (FR3).
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                             | Representation authority       | Hierarchy role    | Component contract |
-| ---------------- | ---------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
-| Container        | Presents the current circular painted surface. | Current source and public docs | Supporting        | FR1, FR2           |
-| Icon             | Presents caller-supplied visual content.       | Caller-supplied content        | Context-dependent | FR1                |
+| Anatomy or state | Design requirement                            | Representation authority       | Hierarchy role    | Component contract |
+| ---------------- | --------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
+| Container        | Presents the circular accent painted surface. | Current source and public docs | Supporting        | FR1, FR2           |
+| Icon             | Presents caller-supplied visual content.      | Caller-supplied content        | Context-dependent | FR1                |
 
 ### Theming anatomy
 
@@ -103,22 +128,25 @@ This draft does not change or extend NavIcon's existing accessibility behavior.
 
 ## Family and system relationships
 
-This draft references the current shared owners without restating their rules:
-`architecture:component-theming-surface` and
-`architecture:public-component-api`.
+- `architecture:component-theming-surface` owns the target and its
+  qualification.
+- `architecture:public-component-api` owns how the forwarded inputs compose.
 
 ## Verification map
 
-| Contract            | Verification                         | Representative states                | Mutation or failure expectation                                                       | Audit section           |
-| ------------------- | ------------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------- | ----------------------- |
-| FR1                 | `NavIcon.test.tsx` content suite     | Caller-supplied icon                 | Removing the container or supplied content fails existing render and ref assertions.  | `audit:NavIcon/anatomy` |
-| FR2                 | `NavIcon.test.tsx` target-name suite | Canonical target class               | Missing or renamed canonical target fails the target assertion.                       | `audit:NavIcon/theming` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`        | Canonical anatomy and current target | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:NavIcon/theming` |
+| Contract            | Verification                                                   | Representative states                | Mutation or failure expectation                                                                                                                    | Audit section           |
+| ------------------- | -------------------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| FR1, FR3            | `NavIcon.test.tsx` content, ref, and test-id suites            | Caller-supplied icon                 | Removing the container, content, ref, or test id fails.                                                                                            | `audit:NavIcon/anatomy` |
+| FR2                 | `NavIcon.test.tsx` target-name suite; `themingTargets.test.ts` | Canonical target class               | A missing or renamed canonical target, or the removed `navicon` alias, fails the target assertion; an extra target fails `themingTargets.test.ts`. | `audit:NavIcon/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                  | Canonical anatomy and current target | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation.                                                              | `audit:NavIcon/theming` |
+
+Read from source, with no focused test yet: the container's circular shape, size, and accent colors (FR1); and other DOM props, the `className`,
+`style`, and `xstyle` merge, and the absence of a role, name, or focus stop
+(FR3).
 
 ## Decision log
 
-None. This draft records current facts and introduces no component-local design
-decision.
+No component-local decision is recorded.
 
 ## Open questions