@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

package/src/hooks/useStreamingText.test.ts

@@ -8,6 +8,10 @@ describe('useStreamingText', () => {
   let rafCallbacks: ((time: number) => void)[];
   let originalRAF: typeof requestAnimationFrame;
   let originalCAF: typeof cancelAnimationFrame;
+  let originalMatchMedia: typeof window.matchMedia | undefined;
+  // Toggled per-test to drive the reduced-motion media query. Reset in
+  // beforeEach so the preference never leaks between tests.
+  let prefersReducedMotion: boolean;
 
   beforeEach(() => {
     rafCallbacks = [];
@@ -19,33 +23,44 @@ describe('useStreamingText', () => {
     });
     globalThis.cancelAnimationFrame = vi.fn();
 
-    // Mock matchMedia for useTheme → useMediaQuery
-    if (!window.matchMedia) {
-      Object.defineProperty(window, 'matchMedia', {
-        writable: true,
-        value: vi.fn().mockImplementation((query: string) => ({
-          matches: false,
-          media: query,
-          onchange: null,
-          addListener: vi.fn(),
-          removeListener: vi.fn(),
-          addEventListener: vi.fn(),
-          removeEventListener: vi.fn(),
-          dispatchEvent: vi.fn(),
-        })),
-      });
-    }
+    // Mock matchMedia for useTheme → useMediaQuery and the hook's own
+    // reduced-motion read. Only the reduced-motion query reflects
+    // `prefersReducedMotion`; theme media queries always report no match.
+    prefersReducedMotion = false;
+    originalMatchMedia = window.matchMedia;
+    Object.defineProperty(window, 'matchMedia', {
+      configurable: true,
+      writable: true,
+      value: vi.fn().mockImplementation((query: string) => ({
+        matches: query.includes('prefers-reduced-motion')
+          ? prefersReducedMotion
+          : false,
+        media: query,
+        onchange: null,
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      })),
+    });
   });
 
   afterEach(() => {
     globalThis.requestAnimationFrame = originalRAF;
     globalThis.cancelAnimationFrame = originalCAF;
+    // Restore matchMedia so the mock never leaks into other suites. jsdom
+    // has no matchMedia by default, so drop the property when there was none.
+    if (originalMatchMedia === undefined) {
+      // @ts-expect-error jsdom leaves matchMedia undefined by default
+      delete window.matchMedia;
+    } else {
+      window.matchMedia = originalMatchMedia;
+    }
   });
 
   it('returns full text when not streaming', () => {
-    const {result} = renderHook(() =>
-      useStreamingText('Hello world', false),
-    );
+    const {result} = renderHook(() => useStreamingText('Hello world', false));
     expect(result.current).toBe('Hello world');
   });
 
@@ -56,6 +71,26 @@ describe('useStreamingText', () => {
     expect(result.current).toBe('Hello world');
   });
 
+  it('snaps to full text immediately when reduced motion is preferred', () => {
+    prefersReducedMotion = true;
+    const {result} = renderHook(() => useStreamingText('Hello world', true));
+    expect(result.current).toBe('Hello world');
+  });
+
+  it('keeps snapping to the full text on updates when reduced motion is preferred', () => {
+    prefersReducedMotion = true;
+    const {result, rerender} = renderHook(
+      ({text}) => useStreamingText(text, true),
+      {initialProps: {text: 'Hello'}},
+    );
+
+    expect(result.current).toBe('Hello');
+
+    // A later chunk arrives — it should appear in full, not reveal char-by-char.
+    rerender({text: 'Hello world'});
+    expect(result.current).toBe('Hello world');
+  });
+
   it('starts with empty string when streaming', () => {
     const {result} = renderHook(() => useStreamingText('Hello world', true));
     expect(result.current).toBe('');

package/src/hooks/useStreamingText.ts

@@ -4,7 +4,7 @@
 
 /**
  * @file useStreamingText.ts
- * @input Uses React useState, useEffect, useRef, useTheme
+ * @input Uses React useState, useEffect, useRef, useMediaQuery, useTheme
  * @output Exports useStreamingText hook for smooth text streaming
  * @position Core hook; smooths bursty streamed text into steady character reveal
  *
@@ -23,6 +23,7 @@
  */
 
 import {useEffect, useMemo, useRef, useState} from 'react';
+import {useMediaQuery} from './useMediaQuery';
 import {useTheme} from '../theme/useTheme';
 
 /**
@@ -71,7 +72,9 @@ const CHARS_PER_TICK = {
  * Smooths bursty streamed text into a steady character-by-character reveal.
  *
  * Returns a string that grows steadily toward `targetText`. When `isStreaming`
- * is false, returns the full `targetText` immediately.
+ * is false, returns the full `targetText` immediately. When the user prefers
+ * reduced motion, the progressive reveal is skipped entirely and the full
+ * `targetText` is returned immediately.
  *
  * The hook advances on word and syntax boundaries, avoiding slices inside
  * markdown markers like `**`, backticks, `[]()`, etc. This prevents visual
@@ -143,9 +146,17 @@ export function useStreamingText(
     }
   }
 
+  // Respect the user's reduced-motion preference — skip the progressive
+  // reveal and snap straight to the full text. Uses the package's SSR-safe
+  // useMediaQuery (useMediaQuery.ts) so the read stays in sync if the
+  // preference changes mid-stream.
+  const prefersReducedMotion = useMediaQuery(
+    '(prefers-reduced-motion: reduce)',
+  );
+
   // Animation loop
   useEffect(() => {
-    if (!isStreaming || speed === 'instant') {
+    if (!isStreaming || speed === 'instant' || prefersReducedMotion) {
       return;
     }
 
@@ -174,9 +185,9 @@ export function useStreamingText(
         rafRef.current = null;
       }
     };
-  }, [isStreaming, charsPerTick, tickMs, speed]);
+  }, [isStreaming, charsPerTick, tickMs, speed, prefersReducedMotion]);
 
-  if (!isStreaming || speed === 'instant') {
+  if (!isStreaming || speed === 'instant' || prefersReducedMotion) {
     return targetText;
   }
 

package/src/hooks/useTreeFocus.test.tsx

@@ -44,9 +44,7 @@ function Tree({
   const nodes = isOpen && expanded.length > 0 ? expanded : collapsed;
   const {treeRef, handleKeyDown} = useTreeFocus<HTMLUListElement>({
     onToggleExpand: () => setIsOpen(o => !o),
-    onActivate: onActivate
-      ? (_item, id) => onActivate(id)
-      : undefined,
+    onActivate: onActivate ? (_item, id) => onActivate(id) : undefined,
   });
   return (
     <ul ref={treeRef} role="tree" onKeyDown={handleKeyDown}>

package/src/reset.css

@@ -200,6 +200,35 @@
     height: auto;
   }
 
+  /* ===========================================================================
+     AspectRatio Fit Baseline
+     =========================================================================== */
+
+  /*
+   * Child sizing for AspectRatio's `fit` prop — the component marks the
+   * child's direct parent with `data-astryx-aspect-ratio-override` (carrying
+   * the fit value), and these direct-child rules size the child, so
+   * consumers don't hand-write width/height/object-fit on every media child.
+   * The marker sits on the parent itself, so the rules don't depend on
+   * AspectRatio's internal element structure or its theming surface. As with
+   * the [data-astryx-media] baseline below, the rules are zero-specificity
+   * and any styling the child sets itself still wins. `fit="center"` needs
+   * no rules here — the component centers the child from its own wrapper.
+   */
+  :where([data-astryx-aspect-ratio-override="cover"], [data-astryx-aspect-ratio-override="contain"])
+    > :where(*) {
+    width: 100%;
+    height: 100%;
+  }
+
+  :where([data-astryx-aspect-ratio-override="cover"]) > :where(img, video) {
+    object-fit: cover;
+  }
+
+  :where([data-astryx-aspect-ratio-override="contain"]) > :where(img, video) {
+    object-fit: contain;
+  }
+
   /* ===========================================================================
      Forms
      =========================================================================== */

package/src/theme/SyntaxTheme.doc.mjs

@@ -50,9 +50,9 @@ export const docs = {
           'Syntax themes support light-dark() tuples: each token can have different values for light and dark mode, resolved automatically by the color scheme.',
       },
       {
-        guidance: false,
+        guidance: true,
         description:
-          'Wrap individual CodeBlock instances with SyntaxTheme: use the syntaxTheme prop on CodeBlock directly for per-instance overrides.',
+          'For a single CodeBlock, pass the syntaxTheme prop directly: it is shorthand for wrapping that block in SyntaxTheme. Use the SyntaxTheme wrapper when theming a whole region of code components.',
       },
     ],
   },
@@ -96,9 +96,9 @@ export const docsDense = {
           'Syntax themes support light-dark() tuples: each token can have different values for light/dark mode, resolved automatically by color scheme.',
       },
       {
-        guidance: false,
+        guidance: true,
         description:
-          'Wrap individual CodeBlock instances w/ SyntaxTheme: use syntaxTheme prop on CodeBlock directly for per-instance overrides instead.',
+          'Single CodeBlock: pass syntaxTheme prop (shorthand for wrapping in SyntaxTheme). Whole region of code components: wrap w/ SyntaxTheme.',
       },
     ],
   },

package/src/theme/defineTheme.ts

@@ -56,14 +56,8 @@ import {
   generateTypeScaleComponents,
   type TypeScaleConfig,
 } from './expandTypeScale';
-import {
-  expandMotionScale,
-  type MotionScaleConfig,
-} from './expandMotionScale';
-import {
-  expandRadiusScale,
-  type RadiusScaleConfig,
-} from './expandRadiusScale';
+import {expandMotionScale, type MotionScaleConfig} from './expandMotionScale';
+import {expandRadiusScale, type RadiusScaleConfig} from './expandRadiusScale';
 import {expandColorScale, type ColorScaleConfig} from './expandColorScale';
 
 import type {DomainTokenName} from './domainTokens';
@@ -153,10 +147,7 @@ export type StyleOverrides = Record<string, string | Record<string, string>>;
  * }
  * ```
  */
-export type ComponentStyleMap = Record<
-  string,
-  Record<string, StyleOverrides>
->;
+export type ComponentStyleMap = Record<string, Record<string, StyleOverrides>>;
 
 /** Input to defineTheme */
 export interface DefineThemeInput {
@@ -287,7 +278,7 @@ export interface DefineThemeInput {
   /**
    * Default syntax highlighting theme for code components.
    * Sets --color-syntax-* tokens at the theme root. Can be overridden
-   * per-region via SyntaxTheme or per-instance via syntaxTheme prop.
+   * per-region (or per-instance) by wrapping in SyntaxTheme.
    *
    * @example
    * ```tsx

package/src/theme/derivedVarRegistry.test.ts

@@ -14,8 +14,8 @@
 
 import {describe, it, expect} from 'vitest';
 import {derivedVarRegistry, getDerivedVars} from './derivedVarRegistry';
-import {readdirSync, readFileSync} from 'fs';
-import {join} from 'path';
+import {readdirSync, readFileSync} from 'node:fs';
+import {join} from 'node:path';
 
 const SRC_DIR = join(__dirname, '..');
 

package/src/theme/expandColorScale.test.ts

@@ -3,6 +3,7 @@
 import {describe, it, expect} from 'vitest';
 import {expandColorScale} from './expandColorScale';
 import {defineTheme} from './defineTheme';
+import {generateThemeRules} from './generateThemeRules';
 
 describe('expandColorScale', () => {
   it('produces all expected token keys', () => {
@@ -60,6 +61,19 @@ describe('expandColorScale', () => {
     expect(warm['--color-neutral']).not.toBe(neutral['--color-neutral']);
   });
 
+  it('emits derived accent tokens as references to --color-accent', () => {
+    const tokens = expandColorScale({accent: '#0064E0'});
+    // Reference tokens follow a scoped --color-accent override at runtime.
+    expect(tokens['--color-text-accent']).toBe('var(--color-accent)');
+    expect(tokens['--color-icon-accent']).toBe('var(--color-accent)');
+    expect(tokens['--color-accent-muted']).toBe(
+      'light-dark(color-mix(in srgb, var(--color-accent) 20%, transparent), color-mix(in srgb, var(--color-accent) 25%, transparent))',
+    );
+    // The base token and the contrast-computed on-accent stay resolved.
+    expect(tokens['--color-accent']).toMatch(/^light-dark\(#/);
+    expect(tokens['--color-on-accent']).toMatch(/^light-dark\(#/);
+  });
+
   it('contrast high produces different --color-text-primary than standard', () => {
     const standard = expandColorScale({
       accent: '#0064E0',
@@ -81,4 +95,19 @@ describe('expandColorScale + defineTheme integration', () => {
     });
     expect(theme.tokens['--color-accent']).toBe('red');
   });
+
+  it('generated theme CSS keeps the accent references (#3495)', () => {
+    const theme = defineTheme({
+      name: 'test-accent-refs',
+      color: {accent: '#DC2626'},
+    });
+    const css = generateThemeRules(theme).join('\n');
+    expect(css).toContain('--color-text-accent: var(--color-accent);');
+    expect(css).toContain('--color-icon-accent: var(--color-accent);');
+    expect(css).toContain(
+      '--color-accent-muted: light-dark(color-mix(in srgb, var(--color-accent) 20%, transparent), color-mix(in srgb, var(--color-accent) 25%, transparent));',
+    );
+    // The base token itself stays a resolved color pair.
+    expect(css).toMatch(/--color-accent: light-dark\(#/);
+  });
 });

package/src/theme/expandColorScale.ts

@@ -77,6 +77,10 @@ function ld(light: string, dark: string): string {
   return `light-dark(${light}, ${dark})`;
 }
 
+function accentWithAlpha(alpha: number): string {
+  return `color-mix(in srgb, var(--color-accent) ${alpha * 100}%, transparent)`;
+}
+
 /**
  * Expand a color scale config into Astryx color token overrides.
  *
@@ -117,10 +121,11 @@ export function expandColorScale(
   return {
     // Core semantic
     '--color-accent': ld(P[40], P[80]),
-    '--color-accent-muted': ld(
-      hexWithAlpha(P[40], 0.2),
-      hexWithAlpha(P[80], 0.25),
-    ),
+    // Derived accent tokens reference --color-accent instead of baking its
+    // resolved hex, so a scoped override of the base token re-accents the
+    // whole subtree at runtime. --color-on-accent stays baked: it is a
+    // contrast computation against the accent, which CSS cannot express.
+    '--color-accent-muted': ld(accentWithAlpha(0.2), accentWithAlpha(0.25)),
     '--color-on-accent': ld(P[100], P[20]),
     '--color-neutral': ld(hexWithAlpha(N[10], 0.1), hexWithAlpha(N[90], 0.2)),
     '--color-background-surface': ld(N[99], N[10]),
@@ -146,10 +151,10 @@ export function expandColorScale(
       NV[textSecondaryDarkTone],
     ),
     '--color-text-disabled': ld(NV[60], NV[40]),
-    '--color-text-accent': ld(P[30], P[80]),
+    '--color-text-accent': 'var(--color-accent)',
 
     // Icon
-    '--color-icon-accent': ld(P[40], P[80]),
+    '--color-icon-accent': 'var(--color-accent)',
     '--color-icon-primary': ld(N[textPrimaryLightTone], N[textPrimaryDarkTone]),
     '--color-icon-secondary': ld(
       NV[textSecondaryLightTone],

package/src/theme/hct.ts

@@ -16,6 +16,8 @@
  * - Tone from L* (CIE Lightness, 0=black, 100=white)
  */
 
+import {parseHex, formatHex} from '../utils/color';
+
 // =============================================================================
 // Types
 // =============================================================================
@@ -121,21 +123,11 @@ export function yToTone(y: number): number {
 // =============================================================================
 
 function hexToRgb(hex: string): [number, number, number] {
-  const h = hex.replace('#', '');
-  const full =
-    h.length === 3 ? h[0] + h[0] + h[1] + h[1] + h[2] + h[2] : h.slice(0, 6);
-  const n = parseInt(full, 16);
-  return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
-}
-
-function rgbToHex(r: number, g: number, b: number): string {
-  return (
-    '#' +
-    [r, g, b]
-      .map(c => c.toString(16).padStart(2, '0'))
-      .join('')
-      .toUpperCase()
-  );
+  const parsed = parseHex(hex);
+  if (parsed === null) {
+    return [0, 0, 0];
+  }
+  return [parsed.r, parsed.g, parsed.b];
 }
 
 // =============================================================================
@@ -181,7 +173,7 @@ export function hctToHex(hct: HCT): string {
   }
   if (chroma < 0.5) {
     const gray = toneToGray(tone);
-    return rgbToHex(gray, gray, gray);
+    return formatHex(gray, gray, gray);
   }
 
   let lo = 0;
@@ -241,7 +233,7 @@ function hctComponentToHex(
     return null;
   }
 
-  return rgbToHex(r, g, bVal);
+  return formatHex(r, g, bVal);
 }
 
 // =============================================================================