@astryxdesign/core 0.4.3 → 0.4.4-canary.0e8af82

package/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx

@@ -23,6 +23,7 @@ import {spacingVars, colorVars, radiusVars} from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
 import {resolveContextActions} from '../../tableContextMenu';
 import {useTranslator} from '../../../i18n';
+import {rtlStyles} from '../../../utils';
 import type {
   TablePlugin,
   TableColumn,
@@ -92,8 +93,20 @@ const expansionStyles = stylex.create({
       color: colorVars['--color-icon-primary'],
     },
   },
+  // The RTL mirror is folded into each state's transform rather than living
+  // on a parent span, matching TreeListItem's chevron (both are `transform`,
+  // so on one element the later value would win).
   chevronExpanded: {
-    transform: 'rotate(90deg)',
+    transform: {
+      default: 'rotate(90deg)',
+      ':is([dir="rtl"] *)': 'scaleX(-1) rotate(90deg)',
+    },
+  },
+  chevronCollapsed: {
+    transform: {
+      default: 'rotate(0deg)',
+      ':is([dir="rtl"] *)': 'scaleX(-1) rotate(0deg)',
+    },
   },
   expandedRow: {
     backgroundColor: colorVars['--color-background-muted'],
@@ -121,7 +134,9 @@ function ExpansionChevron({
       type="button"
       {...stylex.props(
         expansionStyles.chevronButton,
-        isExpanded && expansionStyles.chevronExpanded,
+        isExpanded
+          ? expansionStyles.chevronExpanded
+          : expansionStyles.chevronCollapsed,
       )}
       onClick={e => {
         e.stopPropagation();
@@ -249,6 +264,9 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
                   icon={isExpanded ? 'chevronDown' : 'chevronRight'}
                   size="xsm"
                   aria-hidden
+                  // chevronDown needs no mirroring; chevronRight (collapsed,
+                  // pointing toward the reveal direction) does.
+                  xstyle={!isExpanded && rtlStyles.mirror}
                 />
               ),
               onSelect: () => onToggle(key),

package/src/TextArea/TextArea.tsx

@@ -52,6 +52,7 @@ import type {SizeValue} from '../utils/types';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
 import {useAnnounce} from '../hooks/useAnnounce';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useSize} from '../SizeContext/SizeContext';
 import {themeProps} from '../utils/themeProps';
 import {characterCount} from '../utils/characters';
@@ -394,6 +395,7 @@ export function TextArea({
 }: TextAreaProps) {
   const size = useSize(sizeProp, 'md');
   const t = useTranslator();
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const announce = useAnnounce();
   const id = useId();
   const descriptionID = useId();
@@ -598,7 +600,7 @@ export function TextArea({
           autoFocus={hasAutoFocus}
           data-autofocus={hasAutoFocus || undefined}
           aria-describedby={ariaDescribedBy}
-          aria-required={isRequired && !isOptional ? 'true' : undefined}
+          aria-required={isEffectivelyRequired ? 'true' : undefined}
           aria-invalid={
             status?.type === 'error' ||
             (maxLength != null && valueLength > maxLength)

package/src/TextInput/TextInput.tsx

@@ -101,6 +101,7 @@ import {mergeProps, mergeRefs} from '../utils';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
@@ -301,6 +302,7 @@ export function TextInput({
   ...rest
 }: TextInputProps) {
   const t = useTranslator();
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const size = useSize(sizeProp, 'md');
 
   const id = useId();
@@ -445,7 +447,7 @@ export function TextInput({
         autoFocus={hasAutoFocus}
         data-autofocus={hasAutoFocus || undefined}
         aria-describedby={ariaDescribedBy}
-        aria-required={isRequired === true ? 'true' : undefined}
+        aria-required={isEffectivelyRequired ? 'true' : undefined}
         aria-invalid={status?.type === 'error' ? 'true' : undefined}
         aria-busy={isBusy || undefined}
         aria-labelledby={ariaLabelledBy}

package/src/TimeInput/TimeInput.test.tsx

@@ -42,6 +42,29 @@ describe('TimeInput', () => {
     expect(screen.getByPlaceholderText('Pick a time')).toBeInTheDocument();
   });
 
+  it('does not step the time on a composing ArrowUp/ArrowDown (IME)', () => {
+    const onChange = vi.fn();
+    render(
+      <TimeInput
+        label="Time"
+        value={'14:30' as ISOTimeString}
+        onChange={onChange}
+      />,
+    );
+    const input = screen.getByLabelText('Time');
+
+    // An IME candidate window navigates with the arrows; a composing keydown
+    // (isComposing / legacy keyCode 229) must not step the time value.
+    fireEvent.keyDown(input, {key: 'ArrowUp', isComposing: true});
+    expect(onChange).not.toHaveBeenCalled();
+    fireEvent.keyDown(input, {key: 'ArrowDown', keyCode: 229});
+    expect(onChange).not.toHaveBeenCalled();
+
+    // A real, non-composing ArrowUp still steps the time by one minute.
+    fireEvent.keyDown(input, {key: 'ArrowUp'});
+    expect(onChange).toHaveBeenCalledWith('14:31');
+  });
+
   it('displays formatted time in 12h format', () => {
     render(
       <TimeInput

package/src/TimeInput/TimeInput.tsx

@@ -55,6 +55,7 @@ import {
   formatDisplayTime24h,
   formatISOTime,
   adjustTime,
+  isImeKeyEvent,
   isTimeInRange,
   mergeProps,
   mergeRefs,
@@ -66,6 +67,7 @@ import {useSize} from '../SizeContext/SizeContext';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 import {groupStyles} from '../InputGroup/groupStyles';
 import {useTooltip} from '../Tooltip';
@@ -346,6 +348,7 @@ export function TimeInput({
   ref,
 }: TimeInputProps) {
   const t = useTranslator();
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const placeholder =
     placeholderFromProps ?? t('@astryx.timeInput.placeholder');
   const size = useSize(sizeProp, 'md');
@@ -530,6 +533,13 @@ export function TimeInput({
   // Handle keyboard navigation on input
   const handleInputKeyDown = useCallback(
     (e: KeyboardEvent<HTMLInputElement>) => {
+      // ArrowUp/ArrowDown step the time and preventDefault; an IME candidate
+      // window uses those same arrows to navigate candidates, so guard the
+      // composing keydown (fires before compositionend) to avoid stealing them
+      // mid-composition. See utils/ime.ts.
+      if (isImeKeyEvent(e.nativeEvent)) {
+        return;
+      }
       // Arrow-key adjustment mutates the value; block it while showing a
       // disabled reason (the input keeps focusability via aria-disabled).
       if (isDisabled) {
@@ -656,7 +666,7 @@ export function TimeInput({
         autoFocus={hasAutoFocus}
         data-autofocus={hasAutoFocus || undefined}
         aria-describedby={ariaDescribedBy}
-        aria-required={isRequired === true ? 'true' : undefined}
+        aria-required={isEffectivelyRequired ? 'true' : undefined}
         aria-invalid={
           status?.type === 'error' || !isInputValid ? 'true' : undefined
         }

package/src/Tokenizer/Tokenizer.test.tsx

@@ -16,6 +16,16 @@ import {Tokenizer} from './Tokenizer';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import type {SearchSource, SearchableItem} from '../Typeahead/types';
 import {TestIcon} from '../__tests__/TestIcon';
+import {InternationalizationProvider} from '../i18n';
+
+// Test-supplied announcement strings: the assertions below depend on no
+// catalog, and no hardcoded English in the component can satisfy them.
+const TOKEN_MESSAGES = {
+  fr: {
+    '@astryx.tokenizer.tokenAdded': 'Ajouté : {label}',
+    '@astryx.tokenizer.tokenRemoved': 'Retiré : {label}',
+  },
+};
 
 function politeRegion(): HTMLElement | null {
   return document.querySelector('[data-astryx-live-region="polite"]');
@@ -980,12 +990,14 @@ describe('Tokenizer', () => {
     it('announces removal politely on Backspace with an empty input', async () => {
       const onChange = vi.fn();
       render(
-        <Tokenizer
-          label="Members"
-          searchSource={userSource}
-          value={[users[0], users[1]]}
-          onChange={onChange}
-        />,
+        <InternationalizationProvider locale="fr" overrides={TOKEN_MESSAGES}>
+          <Tokenizer
+            label="Members"
+            searchSource={userSource}
+            value={[users[0], users[1]]}
+            onChange={onChange}
+          />
+        </InternationalizationProvider>,
       );
       const input = screen.getByRole('combobox');
       fireEvent.keyDown(input, {key: 'Backspace'});
@@ -994,35 +1006,39 @@ describe('Tokenizer', () => {
         type: 'remove',
       });
       await waitFor(() => {
-        expect(politeRegion()).toHaveTextContent('Removed Bob');
+        expect(politeRegion()?.textContent).toBe('Retiré : Bob');
       });
     });
 
     it("announces removal politely when clicking a token's remove button", async () => {
       render(
-        <Tokenizer
-          label="Members"
-          searchSource={userSource}
-          value={[users[0], users[1]]}
-          onChange={() => {}}
-        />,
+        <InternationalizationProvider locale="fr" overrides={TOKEN_MESSAGES}>
+          <Tokenizer
+            label="Members"
+            searchSource={userSource}
+            value={[users[0], users[1]]}
+            onChange={() => {}}
+          />
+        </InternationalizationProvider>,
       );
       fireEvent.click(screen.getByRole('button', {name: 'Remove Alice'}));
       await waitFor(() => {
-        expect(politeRegion()).toHaveTextContent('Removed Alice');
+        expect(politeRegion()?.textContent).toBe('Retiré : Alice');
       });
     });
 
     it('announces addition politely when selecting a search result', async () => {
       render(
-        <Tokenizer
-          label="Members"
-          searchSource={userSource}
-          value={[]}
-          onChange={() => {}}
-          hasEntriesOnFocus
-          debounceMs={0}
-        />,
+        <InternationalizationProvider locale="fr" overrides={TOKEN_MESSAGES}>
+          <Tokenizer
+            label="Members"
+            searchSource={userSource}
+            value={[]}
+            onChange={() => {}}
+            hasEntriesOnFocus
+            debounceMs={0}
+          />
+        </InternationalizationProvider>,
       );
       const input = screen.getByRole('combobox');
       fireEvent.focus(input);
@@ -1031,7 +1047,7 @@ describe('Tokenizer', () => {
       });
       fireEvent.click(screen.getByText('Alice'));
       await waitFor(() => {
-        expect(politeRegion()).toHaveTextContent('Added Alice');
+        expect(politeRegion()?.textContent).toBe('Ajouté : Alice');
       });
     });
 
@@ -1041,14 +1057,16 @@ describe('Tokenizer', () => {
         bootstrap: () => [],
       };
       render(
-        <Tokenizer
-          label="Tags"
-          searchSource={emptySource}
-          value={[]}
-          onChange={() => {}}
-          hasCreate
-          debounceMs={0}
-        />,
+        <InternationalizationProvider locale="fr" overrides={TOKEN_MESSAGES}>
+          <Tokenizer
+            label="Tags"
+            searchSource={emptySource}
+            value={[]}
+            onChange={() => {}}
+            hasCreate
+            debounceMs={0}
+          />
+        </InternationalizationProvider>,
       );
       const input = screen.getByRole('combobox');
       await act(async () => {
@@ -1059,7 +1077,7 @@ describe('Tokenizer', () => {
       });
       fireEvent.click(screen.getByText('Create "new-tag"'));
       await waitFor(() => {
-        expect(politeRegion()).toHaveTextContent('Added new-tag');
+        expect(politeRegion()?.textContent).toBe('Ajouté : new-tag');
       });
     });
 

package/src/Tokenizer/Tokenizer.tsx

@@ -600,7 +600,7 @@ export function Tokenizer<T extends SearchableItem>({
         const realItem = base as T;
         const newItems = [...value, realItem];
         onChange(newItems, {item: realItem, type: 'create'});
-        announce(`Added ${createdValue}`);
+        announce(t('@astryx.tokenizer.tokenAdded', {label: createdValue}));
         return;
       }
 
@@ -609,9 +609,9 @@ export function Tokenizer<T extends SearchableItem>({
       }
       const newItems = [...value, item];
       onChange(newItems, {item, type: 'add'});
-      announce(`Added ${item.label}`);
+      announce(t('@astryx.tokenizer.tokenAdded', {label: item.label}));
     },
-    [value, onChange, isAtMax, selectedIds, hasCreate, announce],
+    [value, onChange, isAtMax, selectedIds, hasCreate, announce, t],
   );
 
   // Handle removing an item. Single removal path: both Backspace on an empty
@@ -621,10 +621,10 @@ export function Tokenizer<T extends SearchableItem>({
     (item: T) => {
       const newItems = value.filter(v => v.id !== item.id);
       onChange(newItems, {item, type: 'remove'});
-      announce(`Removed ${item.label}`);
+      announce(t('@astryx.tokenizer.tokenRemoved', {label: item.label}));
       inputRef.current?.focus();
     },
-    [value, onChange, announce],
+    [value, onChange, announce, t],
   );
 
   // Handle clearing all items

package/src/Tooltip/useTooltip.tsx

@@ -28,6 +28,7 @@ import {
 } from '../Layer/useLayer';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import {themeProps} from '../utils/themeProps';
+import {isImeKeyEvent} from '../utils/ime';
 import {
   colorVars,
   radiusVars,
@@ -454,7 +455,9 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       if (e.key !== 'Escape') {
         return;
       }
-      if (e.isComposing || e.keyCode === 229) {
+      if (isImeKeyEvent(e)) {
+        // Ignore Escape that is committing/cancelling an IME composition;
+        // see utils/ime.ts for why.
         return;
       }
       clearTimeouts();

package/src/Typeahead/BaseTypeahead.tsx

@@ -30,7 +30,7 @@ import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {usePopover} from '../Popover/usePopover';
 import {useAnnounce} from '../hooks/useAnnounce';
-import {isImeKeyEvent} from '../hooks/useFocusTrap';
+import {isImeKeyEvent} from '../utils/ime';
 import {TypeaheadItem} from './TypeaheadItem';
 import {Icon} from '../Icon';
 import {
@@ -449,7 +449,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
           announce(
             shown.length === 0
               ? emptySearchResultsText
-              : `${shown.length} ${shown.length === 1 ? 'result' : 'results'}`,
+              : t('@astryx.typeahead.resultCount', {count: shown.length}),
           );
         }
       } catch {
@@ -464,7 +464,14 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         }
       }
     },
-    [searchSource, maxMenuItems, showLayer, announce, emptySearchResultsText],
+    [
+      searchSource,
+      maxMenuItems,
+      showLayer,
+      announce,
+      emptySearchResultsText,
+      t,
+    ],
   );
 
   // Perform bootstrap

package/src/Typeahead/Typeahead.test.tsx

@@ -23,6 +23,7 @@ import userEvent from '@testing-library/user-event';
 import {Typeahead} from './Typeahead';
 import {BaseTypeahead} from './BaseTypeahead';
 import type {SearchSource, SearchableItem} from './types';
+import {InternationalizationProvider} from '../i18n';
 
 // Store original matches to restore later
 const originalMatches = HTMLElement.prototype.matches;
@@ -132,21 +133,94 @@ describe('BaseTypeahead', () => {
 
   it('announces the result count to a live region (comboboxes-6)', async () => {
     render(
-      <BaseTypeahead
-        searchSource={fruitSource}
-        value={null}
-        onChange={() => {}}
-        debounceMs={0}
-      />,
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{
+          fr: {
+            '@astryx.typeahead.resultCount':
+              '{count, number} {count, plural, one {résultat} other {résultats}}',
+          },
+        }}>
+        <BaseTypeahead
+          searchSource={fruitSource}
+          value={null}
+          onChange={() => {}}
+          debounceMs={0}
+        />
+      </InternationalizationProvider>,
     );
     const input = screen.getByRole('combobox');
+    // "Ap" matches Apple only — the singular ICU branch.
     fireEvent.change(input, {target: {value: 'Ap'}});
 
     await waitFor(() => {
       const region = document.querySelector(
         '[data-astryx-live-region="polite"]',
       );
-      expect(region?.textContent).toMatch(/\d+ results?/);
+      // Exact, so the plural branch ("1 résultats") would fail.
+      expect(region?.textContent).toBe('1 résultat');
+    });
+  });
+
+  it('announces the plural result count', async () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{
+          fr: {
+            '@astryx.typeahead.resultCount':
+              '{count, number} {count, plural, one {résultat} other {résultats}}',
+          },
+        }}>
+        <BaseTypeahead
+          searchSource={fruitSource}
+          value={null}
+          onChange={() => {}}
+          debounceMs={0}
+        />
+      </InternationalizationProvider>,
+    );
+    const input = screen.getByRole('combobox');
+    // "err" matches Cherry and Elderberry.
+    fireEvent.change(input, {target: {value: 'err'}});
+
+    await waitFor(() => {
+      const region = document.querySelector(
+        '[data-astryx-live-region="polite"]',
+      );
+      expect(region?.textContent).toBe('2 résultats');
+    });
+  });
+
+  it('speaks the result count from a provider catalog', async () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        messages={{
+          fr: {
+            '@astryx.typeahead.resultCount': {
+              defaultMessage:
+                '{count, number} {count, plural, one {résultat} other {résultats}}',
+            },
+          },
+        }}>
+        <BaseTypeahead
+          searchSource={fruitSource}
+          value={null}
+          onChange={() => {}}
+          debounceMs={0}
+        />
+      </InternationalizationProvider>,
+    );
+    const input = screen.getByRole('combobox');
+    fireEvent.change(input, {target: {value: 'err'}});
+
+    await waitFor(() => {
+      const region = document.querySelector(
+        '[data-astryx-live-region="polite"]',
+      );
+      // Same key through the catalog path rather than `overrides`.
+      expect(region?.textContent).toBe('2 résultats');
     });
   });
 
@@ -796,6 +870,41 @@ describe('Typeahead edit mode', () => {
     // onChange should not have been called — value restored
     expect(onChange).not.toHaveBeenCalled();
   });
+
+  it('does not exit edit mode on a composing Escape (IME)', async () => {
+    const onChange = vi.fn();
+    render(
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={fruits[0]}
+        onChange={onChange}
+      />,
+    );
+
+    // Enter edit mode by clicking the token; the input uncollapses and
+    // rejoins the Tab order (tabindex is cleared).
+    const tokenText = screen.getByText(fruits[0].label);
+    fireEvent.click(tokenText.closest('div')!);
+    await act(async () => {
+      await new Promise(r => requestAnimationFrame(r));
+    });
+    const input = screen.getByRole('combobox');
+    expect(input).not.toHaveAttribute('tabindex', '-1');
+
+    // BaseTypeahead invokes this external handler before its own IME guard, so
+    // a composing Escape (isComposing / legacy keyCode 229) — which an IME uses
+    // to cancel the pending candidate — must not exit edit mode here.
+    fireEvent.keyDown(input, {key: 'Escape', isComposing: true});
+    expect(screen.getByRole('combobox')).not.toHaveAttribute('tabindex', '-1');
+    fireEvent.keyDown(input, {key: 'Escape', keyCode: 229});
+    expect(screen.getByRole('combobox')).not.toHaveAttribute('tabindex', '-1');
+
+    // A real, non-composing Escape still exits edit mode: the token is
+    // restored and the collapsed input drops back out of the Tab order.
+    fireEvent.keyDown(input, {key: 'Escape'});
+    expect(screen.getByRole('combobox')).toHaveAttribute('tabindex', '-1');
+  });
 });
 
 describe('Typeahead collapsed input tab order', () => {

package/src/Typeahead/Typeahead.tsx

@@ -45,7 +45,7 @@ import {VisuallyHidden} from '../VisuallyHidden';
 import {spacingVars, sizeVars} from '../theme/tokens.stylex';
 import {groupStyles} from '../InputGroup/groupStyles';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
-import {getInputARIA, mergeProps, mergeRefs} from '../utils';
+import {getInputARIA, isImeKeyEvent, mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import type {SearchableItem, SearchSource} from './types';
@@ -369,6 +369,15 @@ export function Typeahead<T extends SearchableItem>({
   // Handle Escape during edit mode — restore token
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent<HTMLInputElement>) => {
+      // BaseTypeahead invokes this external handler *before* its own IME
+      // guard, so we must guard here too: an IME candidate window uses Escape
+      // to cancel the pending composition, and that composing Escape fires
+      // before compositionend. Without this, a Korean/Japanese/Chinese user
+      // cancelling a candidate would instead exit edit mode and blur the
+      // field. See utils/ime.ts.
+      if (isImeKeyEvent(e.nativeEvent)) {
+        return;
+      }
       if (e.key === 'Escape' && editingValue) {
         e.preventDefault();
         setIsEditing(false);

package/src/__tests__/stubMatchMedia.test.ts

@@ -0,0 +1,79 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file stubMatchMedia.test.ts
+ * @input Uses vitest, stubMatchMedia
+ * @output Unit coverage for the shared query-aware matchMedia stub
+ * @position Testing; guards the helper other suites trust to route queries
+ *
+ * The helper exists because a stub that ignores its query silently reroutes
+ * code branching on a different one — the failure mode leaves every test
+ * green. A helper sold on that promise has to be held to it, so these assert
+ * the routing itself rather than any component behaviour.
+ */
+
+import {describe, it, expect, afterEach, vi} from 'vitest';
+import {stubMatchMedia} from './stubMatchMedia';
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('stubMatchMedia', () => {
+  it('routes prefers-reduced-motion independently of every other query', () => {
+    // The exact combination the blanket stub could not express: below a
+    // breakpoint (matches) while motion is NOT reduced.
+    stubMatchMedia({reduceMotion: false, matches: true});
+
+    expect(matchMedia('(prefers-reduced-motion: reduce)').matches).toBe(false);
+    expect(matchMedia('(max-width: 768px)').matches).toBe(true);
+  });
+
+  it('answers no-preference as the opposite of reduce', () => {
+    // Two spellings, opposite meanings. A substring test on
+    // 'prefers-reduced-motion' alone would hand both the same answer.
+    stubMatchMedia({reduceMotion: true});
+
+    expect(matchMedia('(prefers-reduced-motion: reduce)').matches).toBe(true);
+    expect(matchMedia('(prefers-reduced-motion: no-preference)').matches).toBe(
+      false,
+    );
+  });
+
+  it('treats the bare preference query as reduce', () => {
+    stubMatchMedia({reduceMotion: true});
+    expect(matchMedia('(prefers-reduced-motion)').matches).toBe(true);
+
+    stubMatchMedia({reduceMotion: false});
+    expect(matchMedia('(prefers-reduced-motion)').matches).toBe(false);
+  });
+
+  it('defaults to full motion and matching everything else', () => {
+    stubMatchMedia();
+
+    expect(matchMedia('(prefers-reduced-motion: reduce)').matches).toBe(false);
+    expect(matchMedia('(max-width: 768px)').matches).toBe(true);
+  });
+
+  it('lets a non-motion query be answered false', () => {
+    // Above the breakpoint, motion still reduced — the other axis of the
+    // combination, so neither knob can be quietly driving both.
+    stubMatchMedia({reduceMotion: true, matches: false});
+
+    expect(matchMedia('(prefers-reduced-motion: reduce)').matches).toBe(true);
+    expect(matchMedia('(max-width: 768px)').matches).toBe(false);
+  });
+
+  it('echoes the query and exposes the listener API components subscribe to', () => {
+    stubMatchMedia();
+    const mql = matchMedia('(max-width: 768px)');
+
+    // useMediaQuery subscribes; a stub without these throws on mount rather
+    // than failing an assertion, which reads as an unrelated crash.
+    expect(mql.media).toBe('(max-width: 768px)');
+    expect(typeof mql.addEventListener).toBe('function');
+    expect(typeof mql.removeEventListener).toBe('function');
+    expect(typeof mql.addListener).toBe('function');
+    expect(typeof mql.removeListener).toBe('function');
+  });
+});