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

package/src/__tests__/stubMatchMedia.ts

@@ -0,0 +1,95 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file stubMatchMedia.ts
+ * @input Uses vitest
+ * @output stubMatchMedia — a query-aware window.matchMedia stub
+ * @position Shared test helper; imported by component tests that render below
+ *   a breakpoint while also exercising motion-sensitive behaviour
+ *
+ * jsdom has no matchMedia, so tests stub it. The usual stub answers every query
+ * with one boolean:
+ *
+ *   vi.stubGlobal('matchMedia', vi.fn().mockReturnValue({matches: true, ...}))
+ *
+ * That is enough to put AppShell below its breakpoint — and it silently also
+ * matches `prefers-reduced-motion`, rerouting any code that branches on motion.
+ * MobileNav's close delay is capped at 0 under reduced motion, so a suite using
+ * the blanket stub runs against an immediate close while its test names claim
+ * it is exercising the real delay. The failure mode is invisible: every test
+ * still passes.
+ *
+ * So the two answers are separate knobs here. `reduceMotion` answers
+ * `prefers-reduced-motion` only; `matches` answers everything else (breakpoint
+ * width queries, which tests below a breakpoint want to be true).
+ *
+ * SYNC: When modified, update this header.
+ */
+
+import {vi} from 'vitest';
+
+export interface StubMatchMediaOptions {
+  /** Whether the user prefers reduced motion. */
+  reduceMotion?: boolean;
+  /** Answer for every other query — width breakpoints, hover, etc. */
+  matches?: boolean;
+}
+
+/**
+ * Answer a `prefers-reduced-motion` query, or null if it isn't one.
+ *
+ * The preference has two spellings and they are opposites, so a single
+ * `includes('prefers-reduced-motion')` would answer `no-preference` with the
+ * value meant for `reduce` — the same answer-without-reading mistake this
+ * helper exists to prevent. Core only queries `reduce` today (MobileNav,
+ * Carousel); handling both is what keeps that true if one changes.
+ */
+function answerReducedMotion(
+  query: string,
+  reduceMotion: boolean,
+): boolean | null {
+  if (query.includes('prefers-reduced-motion: reduce')) {
+    return reduceMotion;
+  }
+  if (query.includes('prefers-reduced-motion: no-preference')) {
+    return !reduceMotion;
+  }
+  // Bare `(prefers-reduced-motion)` is true for any value other than
+  // no-preference, i.e. the same as `reduce`.
+  if (query.includes('prefers-reduced-motion')) {
+    return reduceMotion;
+  }
+  return null;
+}
+
+/**
+ * Install a `window.matchMedia` stub whose answer depends on the query.
+ *
+ * Call from `beforeEach` (or inside a test that needs different motion
+ * settings) and pair with `vi.unstubAllGlobals()` in `afterEach`.
+ *
+ * @example
+ * ```
+ * beforeEach(() => {
+ *   stubMatchMedia({reduceMotion: false});
+ * });
+ * ```
+ */
+export function stubMatchMedia({
+  reduceMotion = false,
+  matches = true,
+}: StubMatchMediaOptions = {}): void {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn((query: string) => ({
+      matches: answerReducedMotion(query, reduceMotion) ?? matches,
+      media: query,
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
+}

package/src/hooks/index.ts

@@ -11,13 +11,17 @@
  * SYNC: When modified, update this header
  */
 
-export {
-  hasActiveFocusTrapEscape,
-  isImeKeyEvent,
-  useFocusTrap,
-} from './useFocusTrap';
+export {hasActiveFocusTrapEscape, useFocusTrap} from './useFocusTrap';
 export type {UseFocusTrapOptions, UseFocusTrapReturn} from './useFocusTrap';
 
+/**
+ * @deprecated Import from `@astryxdesign/core/utils` instead — this is a pure
+ * predicate, not a hook, and the `hooks` barrel is a `'use client'` boundary.
+ * Re-exported here for one release so consumers can move; will be removed in
+ * an upcoming major.
+ */
+export {isImeKeyEvent} from '../utils/ime';
+
 export {useAnnounce} from './useAnnounce';
 export type {AnnounceFn, AnnouncePoliteness} from './useAnnounce';
 

package/src/hooks/useFocusTrap.ts

@@ -19,6 +19,7 @@
 import {useCallback, useEffect, useRef} from 'react';
 
 import {FOCUSABLE_SELECTOR} from './focusableSelector';
+import {isImeKeyEvent} from '../utils/ime';
 
 /**
  * Module-level stack of active focus-trap Escape handlers.
@@ -94,20 +95,6 @@ export function hasActiveFocusTrapEscape(): boolean {
   return escapeStack.length > 0;
 }
 
-/**
- * Whether an Escape keydown should be ignored because it is cancelling an
- * in-progress IME composition. CJK/IME users press Escape to cancel
- * composition; that must not close the surrounding overlay. `keyCode === 229`
- * covers browsers that fire keydown before `isComposing` is set. Exported so
- * other overlays (Dialog, Drawer, CommandPalette) share one definition.
- */
-export function isImeKeyEvent(event: {
-  isComposing?: boolean;
-  keyCode?: number;
-}): boolean {
-  return event.isComposing === true || event.keyCode === 229;
-}
-
 /**
  * Whether an element is currently perceivable/focusable — excludes ones hidden
  * via `display:none`/`visibility:hidden` or inside an `inert`/`hidden` subtree,

package/src/hooks/useInputStatusIcon.test.tsx

@@ -159,6 +159,25 @@ describe('useInputStatusIcon — no dangling aria-describedby (WCAG 1.3.1)', ()
     ).not.toBeInTheDocument();
     expectNoDanglingDescribedBy(container);
   });
+
+  it('keeps the tooltip status button interactive inside a non-interactive trailing slot', () => {
+    // TextArea positions its trailing slot as an absolute overlay with
+    // `pointer-events: none` (correct for the decorative spinner/icon it was
+    // built for). The focusable status button owns its own interactivity so
+    // hover still opens the tooltip there — keyboard focus always worked, the
+    // pointer path did not until the button set `pointer-events: auto`.
+    render(
+      <TextArea
+        label="Field"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Message'}}
+        statusVariant="tooltip"
+      />,
+    );
+    const statusButton = screen.getByRole('button', {name: 'Error details'});
+    expect(statusButton).toHaveStyle({pointerEvents: 'auto'});
+  });
 });
 
 describe('useInputStatusIcon — input-status-icon theme target', () => {

package/src/hooks/useInputStatusIcon.tsx

@@ -82,6 +82,13 @@ const styles = stylex.create({
     background: 'none',
     color: 'inherit',
     cursor: 'pointer',
+    // Own the interactivity so the tooltip opens on hover even when the field
+    // renders this affordance inside a non-interactive trailing slot. TextArea
+    // positions its end slot as an absolute overlay with `pointer-events: none`
+    // (right for the decorative spinner/icon it was built for), which otherwise
+    // swallows this button's hover — keyboard focus still worked, pointer did
+    // not.
+    pointerEvents: 'auto',
     borderRadius: radiusVars['--radius-full'],
     // Not the shared offset: this button sits inside the field, and measured at
     // the standard 3px its ring crosses the field border.

package/src/hooks/useResolvedRequired.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useResolvedRequired.ts
+ * @input Uses React, FormLayoutContext
+ * @output Exports useResolvedRequired
+ * @position Resolves a field's effective aria-required against the form default
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/FormLayout/FormLayoutContext.ts (defaultOptionality source)
+ * - /packages/core/src/FormLayout/FormLayout.tsx (prop doc: aria-required behavior)
+ */
+
+import {use} from 'react';
+import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
+
+/**
+ * Resolve a field's effective *required* state for `aria-required`, honoring a
+ * surrounding `FormLayout`'s `defaultOptionality`.
+ *
+ * Under `defaultOptionality="required"` a field is required unless it opts out
+ * with `isOptional`. The visible indicator is suppressed for the unmarked
+ * majority, so those fields must still expose `aria-required` — otherwise a
+ * sighted user reads them as required (form-wide default, no indicator) while a
+ * screen reader hears "not required". This closes that mismatch.
+ *
+ * Semantics only: this drives `aria-required`, never the native `required`
+ * attribute, so a layout-level default can't silently switch on browser
+ * validation bubbles. `isOptional` takes precedence, matching `FieldLabel`.
+ */
+export function useResolvedRequired({
+  isRequired = false,
+  isOptional = false,
+}: {
+  isRequired?: boolean;
+  isOptional?: boolean;
+}): boolean {
+  const {defaultOptionality} = use(FormLayoutContext);
+  return !isOptional && (isRequired || defaultOptionality === 'required');
+}

package/src/index.ts

@@ -22,6 +22,7 @@ export * from './AvatarGroup';
 export * from './Badge';
 export * from './Banner';
 export * from './Blockquote';
+export * from './BottomSheet';
 export * from './Breadcrumbs';
 export * from './Button';
 export * from './ButtonGroup';

package/src/theme/defineTheme.ts

@@ -248,20 +248,38 @@ export interface DefineThemeInput {
    */
   radius?: RadiusScaleConfig;
   /**
-   * Color scale configuration. Generates color token overrides from a
-   * single accent color using the HCT perceptual color model.
+   * Color scale configuration. Generates color token overrides from an
+   * accent seed using the HCT perceptual color model.
    *
    * Only generates tokens derivable from the accent — status colors,
    * categorical hues, and fixed tokens (on-dark/on-light) use defaults.
-   * Explicit `tokens` entries always take precedence.
+   *
+   * `accent` accepts a single hex (same seed for both color schemes) or a
+   * `[light, dark]` tuple, matching `TokenValue`. With a tuple, the light
+   * scheme's full palette derives from the light seed and the dark
+   * scheme's from the dark seed.
    *
    * `accent` is optional — omit it for a neutral-only theme, which keeps
    * the default accent tokens and only themes the neutrals.
    *
+   * Precedence vs `tokens`: explicit `tokens` entries win over generated
+   * values, token by token. Because `--color-accent-muted`,
+   * `--color-text-accent` and `--color-icon-accent` are generated as
+   * `var(--color-accent)` references, a `tokens['--color-accent']`
+   * override re-points them at runtime. `--color-on-accent` does NOT
+   * follow: it is baked from the `color.accent` seed (a contrast
+   * computation CSS cannot express), so overriding the accent through
+   * `tokens` without also overriding `--color-on-accent` leaves the two
+   * out of sync. To re-seat the whole palette per scheme, prefer a tuple
+   * `color.accent` over the `tokens['--color-accent']` workaround.
+   *
    * @example
-   * ```tsx
+   * ```
    * color: { accent: '#0064E0', neutralStyle: 'cool', contrast: 'standard' }
    *
+   * // Per-scheme accents — light palette from the first seed, dark from the second
+   * color: { accent: ['#0064E0', '#48CAE4'] }
+   *
    * // Neutral-only — accent tokens stay at their defaults
    * color: { neutralStyle: 'warm' }
    * ```

package/src/theme/expandColorScale.test.ts

@@ -192,6 +192,144 @@ describe('expandColorScale — neutral-only themes (#2279)', () => {
   });
 });
 
+describe('expandColorScale — tuple accent (#2279)', () => {
+  const LIGHT_SEED = '#B7410E';
+  const DARK_SEED = '#48CAE4';
+
+  it('accepts a [light, dark] tuple and generates the accent tokens', () => {
+    const tokens = expandColorScale({accent: [LIGHT_SEED, DARK_SEED]});
+    for (const key of ACCENT_TOKENS) {
+      expect(tokens).toHaveProperty(key);
+    }
+    expect(tokens['--color-accent']).toMatch(/^light-dark\(#/);
+    expect(tokens['--color-on-accent']).toMatch(/^light-dark\(#/);
+  });
+
+  it('a same-halves tuple matches the single-string expansion, token for token', () => {
+    // Pins the string path as the tuple fast path: introducing tuples must
+    // not re-color any existing single-accent theme.
+    const fromString = expandColorScale({accent: LIGHT_SEED});
+    const fromTuple = expandColorScale({accent: [LIGHT_SEED, LIGHT_SEED]});
+    expect(fromTuple).toEqual(fromString);
+  });
+
+  it('derives the light palette from the light seed and the dark palette from the dark seed', () => {
+    // Every generated light-dark() pair takes its light half from the light
+    // seed's palettes and its dark half from the dark seed's, so resolving
+    // each mode must agree with the matching single-accent expansion.
+    const tuple = defineTheme({
+      name: 'tuple',
+      color: {accent: [LIGHT_SEED, DARK_SEED]},
+    });
+    const fromLight = defineTheme({name: 'light', color: {accent: LIGHT_SEED}});
+    const fromDark = defineTheme({name: 'dark', color: {accent: DARK_SEED}});
+
+    const generatedKeys = Object.keys(
+      expandColorScale({accent: [LIGHT_SEED, DARK_SEED]}),
+    );
+    const tupleLight = resolveThemeTokens(tuple, {mode: 'light'});
+    const refLight = resolveThemeTokens(fromLight, {mode: 'light'});
+    const tupleDark = resolveThemeTokens(tuple, {mode: 'dark'});
+    const refDark = resolveThemeTokens(fromDark, {mode: 'dark'});
+    for (const key of generatedKeys) {
+      expect(tupleLight[key], `${key} (light)`).toBe(refLight[key]);
+      expect(tupleDark[key], `${key} (dark)`).toBe(refDark[key]);
+    }
+  });
+
+  it('differing seeds produce a dark half the light seed would not', () => {
+    // Regression guard: the dark half must not silently reuse the light seed.
+    const tuple = defineTheme({
+      name: 'tuple-differs',
+      color: {accent: [LIGHT_SEED, DARK_SEED]},
+    });
+    const single = defineTheme({
+      name: 'single',
+      color: {accent: LIGHT_SEED},
+    });
+    expect(
+      resolveThemeTokens(tuple, {mode: 'dark'})['--color-accent'],
+    ).not.toBe(resolveThemeTokens(single, {mode: 'dark'})['--color-accent']);
+  });
+
+  it('keeps the derived accent tokens as references with a tuple accent', () => {
+    const tokens = expandColorScale({accent: [LIGHT_SEED, DARK_SEED]});
+    expect(tokens['--color-text-accent']).toBe('var(--color-accent)');
+    expect(tokens['--color-icon-accent']).toBe('var(--color-accent)');
+    expect(tokens['--color-accent-muted']).toContain('var(--color-accent)');
+  });
+
+  it('honours neutralStyle with a tuple accent', () => {
+    const warm = expandColorScale({
+      accent: [LIGHT_SEED, DARK_SEED],
+      neutralStyle: 'warm',
+    });
+    const cool = expandColorScale({
+      accent: [LIGHT_SEED, DARK_SEED],
+      neutralStyle: 'cool',
+    });
+    expect(warm['--color-neutral']).not.toBe(cool['--color-neutral']);
+  });
+});
+
+describe('accent precedence — color config vs tokens overrides (#2279)', () => {
+  const CONFIG_ACCENT: [string, string] = ['#B7410E', '#48CAE4'];
+  const TOKEN_ACCENT: [string, string] = ['#AA0000', '#FF5555'];
+
+  it('tokens["--color-accent"] wins over the color-generated accent', () => {
+    const theme = defineTheme({
+      name: 'precedence-base',
+      color: {accent: CONFIG_ACCENT},
+      tokens: {'--color-accent': TOKEN_ACCENT},
+    });
+    expect(theme.tokens['--color-accent']).toBe(
+      `light-dark(${TOKEN_ACCENT[0]}, ${TOKEN_ACCENT[1]})`,
+    );
+  });
+
+  it('reference tokens follow the tokens override at runtime', () => {
+    const theme = defineTheme({
+      name: 'precedence-refs',
+      color: {accent: CONFIG_ACCENT},
+      tokens: {'--color-accent': TOKEN_ACCENT},
+    });
+    const light = resolveThemeTokens(theme, {mode: 'light'});
+    expect(light['--color-text-accent']).toBe(TOKEN_ACCENT[0]);
+    expect(light['--color-icon-accent']).toBe(TOKEN_ACCENT[0]);
+    const dark = resolveThemeTokens(theme, {mode: 'dark'});
+    expect(dark['--color-text-accent']).toBe(TOKEN_ACCENT[1]);
+  });
+
+  it('baked --color-on-accent stays derived from the color.accent seed', () => {
+    // Documented divergence: a tokens override of --color-accent does not
+    // re-derive --color-on-accent, which is a baked contrast computation
+    // against the color.accent seed. Consumers who override the accent via
+    // tokens must override --color-on-accent too (or pass the tuple through
+    // color.accent so the whole palette re-derives).
+    const overridden = defineTheme({
+      name: 'precedence-on-accent',
+      color: {accent: CONFIG_ACCENT},
+      tokens: {'--color-accent': TOKEN_ACCENT},
+    });
+    const generated = defineTheme({
+      name: 'generated-on-accent',
+      color: {accent: CONFIG_ACCENT},
+    });
+    expect(overridden.tokens['--color-on-accent']).toBe(
+      generated.tokens['--color-on-accent'],
+    );
+  });
+
+  it('an explicit --color-on-accent token wins over the generated one', () => {
+    const theme = defineTheme({
+      name: 'precedence-on-accent-explicit',
+      color: {accent: CONFIG_ACCENT},
+      tokens: {'--color-on-accent': '#FFFFFF'},
+    });
+    expect(theme.tokens['--color-on-accent']).toBe('#FFFFFF');
+  });
+});
+
 describe('expandColorScale + defineTheme integration', () => {
   it('explicit token overrides win over generated values', () => {
     const theme = defineTheme({