@astryxdesign/core 0.2.0-canary.85f5022 → 0.2.0-canary.8dfd7cf

package/src/theme/expandColorScale.test.ts

@@ -4,6 +4,19 @@ import {describe, it, expect} from 'vitest';
 import {expandColorScale} from './expandColorScale';
 import {defineTheme} from './defineTheme';
 import {generateThemeRules} from './generateThemeRules';
+import {resolveThemeTokens} from './tokens';
+import {colorDefaults} from './tokens.stylex';
+
+/** Light-mode half of colorDefaults['--color-accent'] — the hue an accent-less config seeds from. */
+const DEFAULT_ACCENT = '#0064E0';
+const DEFAULT_ACCENT_DARK = '#2694FE';
+
+/** The three tokens that only exist when a seed accent is supplied. */
+const ACCENT_TOKENS = [
+  '--color-accent',
+  '--color-accent-muted',
+  '--color-on-accent',
+] as const;
 
 describe('expandColorScale', () => {
   it('produces all expected token keys', () => {
@@ -86,6 +99,82 @@ describe('expandColorScale', () => {
   });
 });
 
+describe('expandColorScale — neutral-only themes (#2279)', () => {
+  it('accent is optional — a config without one expands', () => {
+    const tokens = expandColorScale({neutralStyle: 'warm'});
+    expect(tokens['--color-background-surface']).toMatch(/^light-dark\(#/);
+  });
+
+  it('expands an empty config', () => {
+    const tokens = expandColorScale({});
+    expect(tokens['--color-background-surface']).toMatch(/^light-dark\(#/);
+    expect(tokens).not.toHaveProperty('--color-accent');
+  });
+
+  it('omits the accent tokens so they fall through to colorDefaults', () => {
+    const tokens = expandColorScale({neutralStyle: 'warm'});
+    for (const key of ACCENT_TOKENS) {
+      expect(tokens).not.toHaveProperty(key);
+    }
+    // ...and the reference tokens still point at whatever --color-accent resolves to.
+    expect(tokens['--color-text-accent']).toBe('var(--color-accent)');
+    expect(tokens['--color-icon-accent']).toBe('var(--color-accent)');
+  });
+
+  it('seeds the neutral palettes from the light half of the default accent', () => {
+    // Drift guard: the module's DEFAULT_ACCENT_SEED is private, so pin the
+    // colorDefaults value it is copied from. Re-coloring the default accent
+    // without re-seeding would silently change every neutral-only theme.
+    expect(colorDefaults['--color-accent']).toBe(
+      `light-dark(${DEFAULT_ACCENT}, ${DEFAULT_ACCENT_DARK})`,
+    );
+
+    const neutralOnly = expandColorScale({neutralStyle: 'warm'});
+    const seeded = expandColorScale({
+      accent: DEFAULT_ACCENT,
+      neutralStyle: 'warm',
+    });
+    for (const [key, value] of Object.entries(seeded)) {
+      if ((ACCENT_TOKENS as ReadonlyArray<string>).includes(key)) {
+        continue;
+      }
+      expect(neutralOnly[key], key).toBe(value);
+    }
+  });
+
+  it('honours neutralStyle and contrast without an accent', () => {
+    const warm = expandColorScale({neutralStyle: 'warm'});
+    const cool = expandColorScale({neutralStyle: 'cool'});
+    expect(warm['--color-neutral']).not.toBe(cool['--color-neutral']);
+
+    const high = expandColorScale({contrast: 'high'});
+    const standard = expandColorScale({contrast: 'standard'});
+    expect(high['--color-text-primary']).not.toBe(
+      standard['--color-text-primary'],
+    );
+  });
+
+  it('does not re-color themes that do pass an accent', () => {
+    // Seeding from the default hex derives a DIFFERENT accent than the default
+    // token holds, so "just default the seed" is not behavior-preserving —
+    // omitting the tokens is the only way a neutral-only theme keeps the
+    // default accent.
+    const tokens = expandColorScale({accent: DEFAULT_ACCENT});
+    expect(tokens['--color-accent']).toMatch(/^light-dark\(#/);
+    expect(tokens['--color-accent']).not.toBe(colorDefaults['--color-accent']);
+  });
+
+  it('treats an empty accent as supplied, not absent', () => {
+    // '' is falsy but not nullish. Only an absent accent is neutral-only; a
+    // supplied-but-malformed one keeps its pre-#2279 behavior (the hex parser
+    // falls back to black) rather than silently dropping the accent tokens.
+    const tokens = expandColorScale({accent: ''});
+    for (const key of ACCENT_TOKENS) {
+      expect(tokens).toHaveProperty(key);
+    }
+  });
+});
+
 describe('expandColorScale + defineTheme integration', () => {
   it('explicit token overrides win over generated values', () => {
     const theme = defineTheme({
@@ -110,4 +199,59 @@ describe('expandColorScale + defineTheme integration', () => {
     // The base token itself stays a resolved color pair.
     expect(css).toMatch(/--color-accent: light-dark\(#/);
   });
+
+  it('a neutral-only theme leaves the accent tokens at their defaults (#2279)', () => {
+    const theme = defineTheme({
+      name: 'test-neutral-only',
+      color: {neutralStyle: 'warm'},
+    });
+    for (const key of ACCENT_TOKENS) {
+      expect(theme.tokens).not.toHaveProperty(key);
+    }
+    // Neutrals are still themed.
+    expect(theme.tokens['--color-background-surface']).toMatch(
+      /^light-dark\(#/,
+    );
+
+    const css = generateThemeRules(theme).join('\n');
+    expect(css).not.toContain('--color-accent:');
+    expect(css).not.toContain('--color-on-accent:');
+    expect(css).toContain('--color-background-surface:');
+  });
+
+  it('a neutral-only theme resolves accent tokens to the defaults at runtime (#2279)', () => {
+    // The CSS side falls through by simply not emitting the tokens. The JS side
+    // (useTheme/resolveThemeTokens) has to agree: the omitted tokens come back
+    // from tokenDefaults, and the var() references the theme DOES emit resolve
+    // against them instead of leaking a literal 'var(--color-accent)'.
+    const theme = defineTheme({
+      name: 'test-neutral-only-runtime',
+      color: {neutralStyle: 'warm'},
+    });
+
+    const light = resolveThemeTokens(theme, {mode: 'light'});
+    expect(light['--color-accent']).toBe(DEFAULT_ACCENT);
+    expect(light['--color-text-accent']).toBe(DEFAULT_ACCENT);
+    expect(light['--color-icon-accent']).toBe(DEFAULT_ACCENT);
+
+    const dark = resolveThemeTokens(theme, {mode: 'dark'});
+    expect(dark['--color-accent']).toBe(DEFAULT_ACCENT_DARK);
+    expect(dark['--color-text-accent']).toBe(DEFAULT_ACCENT_DARK);
+  });
+
+  it('an explicit accent token still wins on a neutral-only theme (#2279)', () => {
+    // Neutral scale from HCT + a hand-picked accent: the tokens map is the only
+    // source of --color-accent, so the reference tokens follow it.
+    const theme = defineTheme({
+      name: 'test-neutral-only-explicit-accent',
+      color: {neutralStyle: 'warm'},
+      tokens: {'--color-accent': ['#AA0000', '#FF5555']},
+    });
+    expect(
+      resolveThemeTokens(theme, {mode: 'light'})['--color-text-accent'],
+    ).toBe('#AA0000');
+
+    const css = generateThemeRules(theme).join('\n');
+    expect(css).toContain('--color-text-accent: var(--color-accent);');
+  });
 });

package/src/theme/expandColorScale.ts

@@ -2,7 +2,7 @@
 
 /**
  * @file expandColorScale.ts
- * @input Color scale configuration { accent, neutralStyle?, contrast? }
+ * @input Color scale configuration { accent?, neutralStyle?, contrast? }
  * @output Token overrides for derivable color tokens
  * @position Theme utility; consumed by defineTheme.ts
  *
@@ -11,6 +11,10 @@
  * derive from the accent — status colors, categorical hues, and fixed
  * tokens (on-dark/on-light) fall through to colorDefaults.
  *
+ * `accent` is optional: a neutral-only config still gets the full neutral
+ * ramp (seeded from the default accent's hue) while the accent tokens
+ * themselves fall through to colorDefaults, same as the tokens above.
+ *
  * SYNC: When modified, update:
  * - /packages/core/src/theme/defineTheme.ts
  */
@@ -31,11 +35,21 @@ import {hexToHct, tonalPalette, hexWithAlpha} from './hct';
  *
  * // With customization
  * { accent: '#B7410E', neutralStyle: 'warm', contrast: 'high' }
+ *
+ * // Neutral-only — keeps the default accent, themes the neutrals
+ * { neutralStyle: 'warm' }
  * ```
  */
 export interface ColorScaleConfig {
-  /** Seed accent color as hex (#RRGGBB). Everything derives from this. */
-  accent: string;
+  /**
+   * Seed accent color as hex (#RRGGBB). Everything derives from this.
+   *
+   * Optional. When omitted, the neutral palettes are seeded from the
+   * default accent's hue and the accent tokens (--color-accent,
+   * --color-accent-muted, --color-on-accent) are not generated — they
+   * fall through to colorDefaults.
+   */
+  accent?: string;
 
   /**
    * Neutral tone warmth. Controls how much of the seed's hue bleeds
@@ -69,6 +83,14 @@ const NEUTRAL_VARIANT_CHROMA: Record<string, number> = {
   neutral: 6,
 };
 
+/**
+ * Hue source for accent-less configs — the light half of
+ * colorDefaults['--color-accent'] (a test guards the two against drift).
+ * Only its hue reaches the output: the accent tokens stay ungenerated, so
+ * they keep their colorDefaults values rather than this seed's derivation.
+ */
+const DEFAULT_ACCENT_SEED = '#0064E0';
+
 // =============================================================================
 // Computation
 // =============================================================================
@@ -89,18 +111,23 @@ function accentWithAlpha(alpha: number): string {
  * --color-on-dark/on-light) are NOT generated — they fall through
  * to colorDefaults.
  *
+ * Without an `accent`, the accent tokens join that fall-through set: the
+ * neutrals are seeded from the default accent's hue, and --color-accent,
+ * --color-accent-muted and --color-on-accent keep their colorDefaults values.
+ *
  * @example
  * ```
  * const tokens = expandColorScale({ accent: '#0064E0' });
  * // tokens['--color-accent'] === 'light-dark(#..., #...)'
+ *
+ * const neutralOnly = expandColorScale({ neutralStyle: 'warm' });
+ * // neutralOnly['--color-accent'] === undefined
  * ```
  */
-export function expandColorScale(
-  config: ColorScaleConfig,
-): ColorScaleTokens {
+export function expandColorScale(config: ColorScaleConfig): ColorScaleTokens {
   const {accent, neutralStyle = 'cool', contrast = 'standard'} = config;
 
-  const seed = hexToHct(accent);
+  const seed = hexToHct(accent ?? DEFAULT_ACCENT_SEED);
   const seedHue = seed.hue;
 
   const primaryChroma = Math.max(seed.chroma, 48);
@@ -119,14 +146,25 @@ export function expandColorScale(
   const textSecondaryDarkTone = isHigh ? 80 : 70;
 
   return {
-    // Core semantic
-    '--color-accent': ld(P[40], P[80]),
-    // 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]),
+    // Core semantic — only with a seed accent. Without one these fall through
+    // to colorDefaults, whose --color-accent is NOT what the default seed
+    // derives: defaulting the seed instead of omitting the tokens would
+    // recolor every neutral-only theme. Nullish and not truthy, matching the
+    // seed above, so a supplied-but-malformed accent keeps its old behavior.
+    ...(accent != null
+      ? {
+          '--color-accent': ld(P[40], P[80]),
+          // 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]),
+        }
+      : null),
     '--color-neutral': ld(hexWithAlpha(N[10], 0.1), hexWithAlpha(N[90], 0.2)),
     '--color-background-surface': ld(N[99], N[10]),
     '--color-background-body': ld(N[95], N[5]),

package/src/theme/index.ts

@@ -30,6 +30,12 @@ export {
   isDefinedTheme,
   tokenDefaults,
 } from './defineTheme';
+export {
+  registerTheme,
+  getRegisteredTheme,
+  getRegisteredThemes,
+  resetThemes,
+} from './themeRegistry';
 export type {
   DefineThemeInput,
   DefinedTheme,
@@ -71,19 +77,13 @@ export {expandTypeScale, generateTypeScaleComponents} from './expandTypeScale';
 export type {TypeScaleConfig, TypeScaleTokens} from './expandTypeScale';
 
 export {expandRadiusScale} from './expandRadiusScale';
-export type {
-  RadiusScaleConfig,
-  RadiusScaleTokens,
-} from './expandRadiusScale';
+export type {RadiusScaleConfig, RadiusScaleTokens} from './expandRadiusScale';
 
 export {expandColorScale} from './expandColorScale';
 export type {ColorScaleConfig, ColorScaleTokens} from './expandColorScale';
 
 export {expandMotionScale} from './expandMotionScale';
-export type {
-  MotionScaleConfig,
-  MotionScaleTokens,
-} from './expandMotionScale';
+export type {MotionScaleConfig, MotionScaleTokens} from './expandMotionScale';
 
 // Export token defaults and vars for use in custom components and themes
 export {
@@ -132,7 +132,7 @@ export type {
   TypeScaleVarName,
 } from './tokens.stylex';
 
-export {useTheme, ThemeContext} from './useTheme';
+export {useTheme, useThemeName, ThemeContext} from './useTheme';
 export type {UseThemeReturn, ThemeContextValue} from './useTheme';
 export {
   resolveThemeToken,
@@ -146,6 +146,7 @@ export type {
   ResolvedThemeMode,
 } from './tokens';
 
+export type {TextColorMap} from '../Text';
 export type {
   ThemeMode,
   HeadingTag,
@@ -155,6 +156,7 @@ export type {
   TextSize,
   TextWeight,
   TextColor,
+  BuiltinTextColor,
   TypographyConfig,
   TypographyRole,
   FontWeight,

package/src/theme/themeRegistry.test.ts

@@ -0,0 +1,59 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, beforeEach} from 'vitest';
+import {defineTheme} from './defineTheme';
+import {
+  getRegisteredTheme,
+  getRegisteredThemes,
+  registerTheme,
+  resetThemes,
+} from './themeRegistry';
+
+describe('themeRegistry', () => {
+  beforeEach(() => {
+    resetThemes();
+  });
+
+  it('registers and resolves themes by name', () => {
+    const theme = defineTheme({
+      name: 'brand',
+      tokens: {'--color-accent': '#123456'},
+    });
+
+    expect(getRegisteredTheme('brand')).toBe(theme);
+  });
+
+  it('returns null for empty or unknown names', () => {
+    expect(getRegisteredTheme(null)).toBeNull();
+    expect(getRegisteredTheme('')).toBeNull();
+    expect(getRegisteredTheme('missing')).toBeNull();
+  });
+
+  it('replaces an existing theme with the same name', () => {
+    const first = defineTheme({name: 'brand'});
+    const second = defineTheme({
+      name: 'brand',
+      tokens: {'--color-accent': '#654321'},
+    });
+
+    expect(getRegisteredTheme('brand')).not.toBe(first);
+    expect(getRegisteredTheme('brand')).toBe(second);
+  });
+
+  it('returns a defensive snapshot of registered themes', () => {
+    const theme = defineTheme({name: 'brand'});
+    const snapshot = getRegisteredThemes();
+
+    expect(snapshot.get('brand')).toBe(theme);
+    expect(snapshot).not.toBe(getRegisteredThemes());
+  });
+
+  it('allows explicit registration of built theme objects', () => {
+    const theme = defineTheme({name: 'built'});
+    resetThemes();
+
+    registerTheme(theme);
+
+    expect(getRegisteredTheme('built')).toBe(theme);
+  });
+});

package/src/theme/themeRegistry.ts

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file themeRegistry.ts
+ * @input DefinedTheme objects from defineTheme() or built theme packages
+ * @output Exports registerTheme, getRegisteredTheme, getRegisteredThemes, resetThemes
+ * @position Server-safe theme registry for theme-name-based SSR resolution
+ *
+ * This module has NO 'use client' directive. It is importable from SSR/RSC and
+ * lets code resolve theme data by stable theme name without React context.
+ */
+
+import type {DefinedTheme} from './defineTheme';
+
+const themeRegistry = new Map<string, DefinedTheme>();
+
+/**
+ * Register a defined theme under its `name`.
+ *
+ * Registration is idempotent and replaces any previous theme with the same
+ * name. Call from app initialization, theme packages, or <Theme> to make the
+ * theme available to SSR-safe resolvers by name.
+ */
+export function registerTheme(theme: DefinedTheme): void {
+  themeRegistry.set(theme.name, theme);
+}
+
+/**
+ * Return a previously registered theme by name.
+ */
+export function getRegisteredTheme(
+  name: string | null | undefined,
+): DefinedTheme | null {
+  if (name == null || name === '') {
+    return null;
+  }
+  return themeRegistry.get(name) ?? null;
+}
+
+/**
+ * Return all registered themes keyed by theme name.
+ */
+export function getRegisteredThemes(): ReadonlyMap<string, DefinedTheme> {
+  return new Map(themeRegistry);
+}
+
+/**
+ * Reset the theme registry. For testing only.
+ * @internal
+ */
+export function resetThemes(): void {
+  themeRegistry.clear();
+}

package/src/theme/types.ts

@@ -15,11 +15,7 @@
  * Raw CSS values (e.g. '800') are accepted as an escape hatch.
  */
 export type FontWeight =
-  | 'normal'
-  | 'medium'
-  | 'semibold'
-  | 'bold'
-  | (string & {});
+  'normal' | 'medium' | 'semibold' | 'bold' | (string & {});
 
 /**
  * A typography role declaration (body, heading, or code).
@@ -152,18 +148,23 @@ export type TextSize =
 /**
  * Font weight variants for Text/Heading
  */
+import type {TextColorMap} from '../Text';
+
 export type TextWeight = 'normal' | 'medium' | 'semibold' | 'bold';
 
 /**
- * Text color variants for Text/Heading
+ * Built-in text color variants for Text/Heading. The concrete keys that ship
+ * with the design system, independent of theme augmentation — used where a
+ * value must be one of the real StyleX color styles (see `resolveStyleColor`).
  */
-export type TextColor =
-  | 'primary'
-  | 'secondary'
-  | 'disabled'
-  | 'placeholder'
-  | 'accent'
-  | 'inherit';
+export type BuiltinTextColor =
+  'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit';
+
+/**
+ * Text color variants for Text/Heading. Extensible via module augmentation of
+ * `TextColorMap`.
+ */
+export type TextColor = keyof TextColorMap;
 
 /**
  * Display mode for Text/Heading

package/src/theme/useTheme.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useTheme',
   displayName: 'useTheme',
@@ -87,7 +87,7 @@ export const docs = {
   importPath: '@astryxdesign/core/theme',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Programmatic access to theme tokens for SVG/canvas/charts needing JS values instead of CSS vars.',

package/src/theme/useTheme.test.tsx

@@ -5,6 +5,7 @@ import {render, renderHook, act, waitFor} from '@testing-library/react';
 import React from 'react';
 import {Theme} from './Theme';
 import {defineTheme} from './defineTheme';
+import {resetThemes} from './themeRegistry';
 import {useTheme} from './useTheme';
 import {resolveThemeTokens} from './tokens';
 
@@ -152,6 +153,8 @@ describe('useTheme', () => {
 // straight to OS preference (see Theme.tsx's useRootThemeSync).
 describe('useTheme mode resolution without a ThemeContext ancestor', () => {
   afterEach(async () => {
+    resetThemes();
+    document.documentElement.removeAttribute('data-astryx-theme');
     // The hook from each `it` below is still mounted and subscribed to the
     // shared MutationObserver when this runs (RTL's own cleanup — which
     // unmounts it — is registered after this file's afterEach), so removing
@@ -184,6 +187,46 @@ describe('useTheme mode resolution without a ThemeContext ancestor', () => {
 
     await waitFor(() => expect(result.current.mode).toBe('dark'));
   });
+
+  it('resolves registered theme tokens from <html data-astryx-theme> when set', () => {
+    defineTheme({
+      name: 'root-brand',
+      tokens: {'--color-accent': ['#010203', '#AABBCC']},
+    });
+    document.documentElement.setAttribute('data-astryx-theme', 'root-brand');
+    document.documentElement.setAttribute('data-theme', 'dark');
+
+    const {result} = renderHook(() => useTheme());
+
+    expect(result.current.name).toBe('root-brand');
+    expect(result.current.token('--color-accent')).toBe('#AABBCC');
+  });
+
+  it('stays live when <html data-astryx-theme> changes after mount', async () => {
+    defineTheme({
+      name: 'first-brand',
+      tokens: {'--color-accent': '#111111'},
+    });
+    defineTheme({
+      name: 'second-brand',
+      tokens: {'--color-accent': '#222222'},
+    });
+    document.documentElement.setAttribute('data-astryx-theme', 'first-brand');
+
+    const {result} = renderHook(() => useTheme());
+    expect(result.current.name).toBe('first-brand');
+    expect(result.current.token('--color-accent')).toBe('#111111');
+
+    act(() => {
+      document.documentElement.setAttribute(
+        'data-astryx-theme',
+        'second-brand',
+      );
+    });
+
+    await waitFor(() => expect(result.current.name).toBe('second-brand'));
+    expect(result.current.token('--color-accent')).toBe('#222222');
+  });
 });
 
 // Covers the singleton MutationObserver + no-op gating in useRootThemeModeAttr:
@@ -193,7 +236,9 @@ describe('useTheme mode resolution without a ThemeContext ancestor', () => {
 // zero as they unmount.
 describe('useTheme root-attribute observer lifecycle', () => {
   afterEach(() => {
+    resetThemes();
     document.documentElement.removeAttribute('data-theme');
+    document.documentElement.removeAttribute('data-astryx-theme');
     // vi.stubGlobal'd MutationObserver stubs below are torn down here even if
     // a test fails partway through, instead of relying on a manual restore
     // line at the end of each test that a mid-test throw would skip.
@@ -237,13 +282,13 @@ describe('useTheme root-attribute observer lifecycle', () => {
     const first = renderHook(() => useTheme());
     const second = renderHook(() => useTheme());
 
-    expect(ObserverSpy).toHaveBeenCalledTimes(1);
-    expect(observe).toHaveBeenCalledTimes(1);
+    expect(ObserverSpy).toHaveBeenCalledTimes(2);
+    expect(observe).toHaveBeenCalledTimes(2);
 
     first.unmount();
     expect(disconnect).not.toHaveBeenCalled();
 
     second.unmount();
-    expect(disconnect).toHaveBeenCalledTimes(1);
+    expect(disconnect).toHaveBeenCalledTimes(2);
   });
 });