@astryxdesign/core 0.1.3 → 0.1.4-canary.01e5b29

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/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);
 }
 
 // =============================================================================

package/src/theme/tokens.test.ts

@@ -20,9 +20,7 @@ const testTheme = defineTheme({
 
 describe('tokenVar', () => {
   it('returns a CSS var() reference for known token names', () => {
-    expect(tokenVar('--color-text-primary')).toBe(
-      'var(--color-text-primary)',
-    );
+    expect(tokenVar('--color-text-primary')).toBe('var(--color-text-primary)');
   });
 
   it('returns a CSS var() reference for custom token names', () => {
@@ -32,9 +30,7 @@ describe('tokenVar', () => {
 
 describe('tokenVars', () => {
   it('contains var() references for known tokens', () => {
-    expect(tokenVars['--color-text-primary']).toBe(
-      'var(--color-text-primary)',
-    );
+    expect(tokenVars['--color-text-primary']).toBe('var(--color-text-primary)');
     expect(tokenVars['--spacing-4']).toBe('var(--spacing-4)');
   });
 });
@@ -87,9 +83,9 @@ describe('resolveThemeTokens', () => {
 
 describe('resolveThemeToken', () => {
   it('resolves one token', () => {
-    expect(
-      resolveThemeToken(testTheme, '--color-accent', {mode: 'dark'}),
-    ).toBe('#FF5555');
+    expect(resolveThemeToken(testTheme, '--color-accent', {mode: 'dark'})).toBe(
+      '#FF5555',
+    );
   });
 
   it('returns fallback for unknown token names', () => {
@@ -107,3 +103,180 @@ describe('resolveThemeToken', () => {
     ).toBe('');
   });
 });
+
+describe('resolveThemeTokens — reference resolution', () => {
+  it('resolves a token that references another token to a raw value', () => {
+    const theme = defineTheme({
+      name: 'ref',
+      tokens: {
+        '--color-accent': ['#0058D2', '#BBC2FF'],
+        '--color-text-accent': 'var(--color-accent)',
+      },
+    });
+
+    const light = resolveThemeTokens(theme, {mode: 'light'});
+    const dark = resolveThemeTokens(theme, {mode: 'dark'});
+
+    expect(light['--color-text-accent']).toBe('#0058D2');
+    expect(dark['--color-text-accent']).toBe('#BBC2FF');
+  });
+
+  it('resolves reference chains iteratively', () => {
+    const theme = defineTheme({
+      name: 'chain',
+      tokens: {
+        '--color-accent': ['#112233', '#445566'],
+        '--color-icon-accent': 'var(--color-accent)',
+        '--color-text-accent': 'var(--color-icon-accent)',
+      },
+    });
+
+    const light = resolveThemeTokens(theme, {mode: 'light'});
+    expect(light['--color-icon-accent']).toBe('#112233');
+    expect(light['--color-text-accent']).toBe('#112233');
+  });
+
+  it('uses the var() fallback when the referenced token is unknown', () => {
+    const theme = defineTheme({
+      name: 'fallback',
+      tokens: {
+        '--color-text-accent': 'var(--not-a-token, #ABCDEF)',
+      },
+    });
+
+    const tokens = resolveThemeTokens(theme, {mode: 'light'});
+    expect(tokens['--color-text-accent']).toBe('#ABCDEF');
+  });
+
+  it('leaves an unresolvable reference as a literal var()', () => {
+    const theme = defineTheme({
+      name: 'unresolvable',
+      tokens: {
+        '--color-text-accent': 'var(--not-a-token)',
+      },
+    });
+
+    const tokens = resolveThemeTokens(theme, {mode: 'light'});
+    expect(tokens['--color-text-accent']).toBe('var(--not-a-token)');
+  });
+
+  it('does not loop forever on a reference cycle', () => {
+    const theme = defineTheme({
+      name: 'cycle',
+      tokens: {
+        '--color-text-accent': 'var(--color-icon-accent)',
+        '--color-icon-accent': 'var(--color-text-accent)',
+      },
+    });
+
+    const tokens = resolveThemeTokens(theme, {mode: 'light'});
+    // The cycle collapses to a literal reference rather than hanging.
+    expect(tokens['--color-text-accent']).toContain('var(');
+    expect(tokens['--color-icon-accent']).toContain('var(');
+  });
+});
+
+describe('resolveThemeTokens — CSS color functions', () => {
+  it('evaluates color-mix with transparent to an rgba() value', () => {
+    const theme = defineTheme({
+      name: 'mix',
+      tokens: {
+        '--color-accent': ['#0058D2', '#BBC2FF'],
+        '--color-accent-muted':
+          'color-mix(in srgb, var(--color-accent) 20%, transparent)',
+      },
+    });
+
+    const light = resolveThemeTokens(theme, {mode: 'light'});
+    const dark = resolveThemeTokens(theme, {mode: 'dark'});
+
+    expect(light['--color-accent-muted']).toBe('rgba(0, 88, 210, 0.2)');
+    expect(dark['--color-accent-muted']).toBe('rgba(187, 194, 255, 0.2)');
+  });
+
+  it('resolves the muted token inside a light-dark() tuple per mode', () => {
+    const theme = defineTheme({
+      name: 'ld-mix',
+      tokens: {
+        '--color-accent': ['#FF0000', '#00FF00'],
+        '--color-accent-muted': [
+          'color-mix(in srgb, var(--color-accent) 20%, transparent)',
+          'color-mix(in srgb, var(--color-accent) 25%, transparent)',
+        ],
+      },
+    });
+
+    const light = resolveThemeTokens(theme, {mode: 'light'});
+    const dark = resolveThemeTokens(theme, {mode: 'dark'});
+
+    expect(light['--color-accent-muted']).toBe('rgba(255, 0, 0, 0.2)');
+    expect(dark['--color-accent-muted']).toBe('rgba(0, 255, 0, 0.25)');
+  });
+
+  it('mixes two opaque colors by weight', () => {
+    const theme = defineTheme({
+      name: 'two-color',
+      tokens: {
+        '--color-neutral': 'color-mix(in srgb, #000000, #FFFFFF)',
+      },
+    });
+
+    const tokens = resolveThemeTokens(theme, {mode: 'light'});
+    expect(tokens['--color-neutral']).toBe('#808080');
+  });
+
+  it('mixes two opaque colors with an explicit percentage', () => {
+    const theme = defineTheme({
+      name: 'weighted',
+      tokens: {
+        '--color-neutral': 'color-mix(in srgb, #000000 25%, #FFFFFF)',
+      },
+    });
+
+    const tokens = resolveThemeTokens(theme, {mode: 'light'});
+    expect(tokens['--color-neutral']).toBe('#BFBFBF');
+  });
+
+  it('preserves an unsupported color space rather than guessing', () => {
+    const theme = defineTheme({
+      name: 'oklab',
+      tokens: {
+        '--color-accent': ['#0058D2', '#BBC2FF'],
+        '--color-neutral':
+          'color-mix(in oklab, var(--color-accent), black 15%)',
+      },
+    });
+
+    const tokens = resolveThemeTokens(theme, {mode: 'light'});
+    // var() still resolves; the unsupported mix stays as a color-mix() expression.
+    expect(tokens['--color-neutral']).toContain('color-mix(in oklab');
+    expect(tokens['--color-neutral']).toContain('#0058D2');
+  });
+});
+
+describe('resolveThemeTokens — generated themes end to end', () => {
+  it('resolves derived accent tokens from defineTheme({color}) to raw values', () => {
+    const theme = defineTheme({name: 'brand', color: {accent: '#0064E0'}});
+
+    const light = resolveThemeTokens(theme, {mode: 'light'});
+    const dark = resolveThemeTokens(theme, {mode: 'dark'});
+
+    const isConcreteColor = (value: string): boolean => /^(#|rgb)/.test(value);
+
+    for (const key of [
+      '--color-accent',
+      '--color-text-accent',
+      '--color-icon-accent',
+      '--color-accent-muted',
+    ]) {
+      expect(isConcreteColor(light[key])).toBe(true);
+      expect(isConcreteColor(dark[key])).toBe(true);
+      expect(light[key]).not.toContain('var(');
+      expect(light[key]).not.toContain('color-mix');
+    }
+
+    // The derived accent tokens resolve to the base accent.
+    expect(light['--color-text-accent']).toBe(light['--color-accent']);
+    expect(light['--color-icon-accent']).toBe(light['--color-accent']);
+  });
+});