@astryxdesign/core 0.2.0 → 0.3.0-canary.041a0ef

package/src/theme/expandTypeScale.test.ts

@@ -305,4 +305,47 @@ describe('generateTypeScaleComponents', () => {
       'var(--text-body-leading)',
     );
   });
+
+  it('generates rules for all 3 heading display types', () => {
+    const components = generateTypeScaleComponents({base: 14, ratio: 1.2});
+    for (const type of ['display-1', 'display-2', 'display-3']) {
+      expect(components.heading).toHaveProperty(`type:${type}`);
+    }
+  });
+
+  it('heading display-type rules reference the display semantic tokens', () => {
+    const components = generateTypeScaleComponents({base: 14, ratio: 1.2});
+    const display1 = components.heading['type:display-1'];
+    expect(display1.fontFamily).toBe('var(--font-family-heading)');
+    expect(display1.fontSize).toBe('var(--text-display-1-size)');
+    expect(display1.lineHeight).toBe('var(--text-display-1-leading)');
+    // fontWeight is intentionally omitted here, matching the `text` branch's
+    // type-keyed rules — see defaultWeightByTypeStyles for how weight is
+    // applied instead.
+    expect(display1.fontWeight).toBeUndefined();
+  });
+
+  it('emits heading type:display-N rules after level:N rules, so type wins at equal specificity', () => {
+    // Heading renders both a `level:N` and a `type:display-N` class on the
+    // same element simultaneously when `type` is set (see Heading.tsx).
+    // Both produce single-class-selector CSS rules of equal specificity, so
+    // CSS's own "last rule wins" tiebreak is what makes `type` take
+    // precedence over `level` -- which only holds if type rules are emitted
+    // strictly after all level rules in this object's (and therefore the
+    // generated stylesheet's) key order. This regression-tests #4829,
+    // where type-keyed heading rules didn't exist at all and level always
+    // won by default, silently discarding the `type` prop under any theme
+    // with a typography.scale.
+    const components = generateTypeScaleComponents({base: 14, ratio: 1.2});
+    const keys = Object.keys(components.heading);
+    const lastLevelIndex = Math.max(
+      ...[1, 2, 3, 4, 5, 6].map(level => keys.indexOf(`level:${level}`)),
+    );
+    const firstTypeIndex = Math.min(
+      ...['display-1', 'display-2', 'display-3'].map(type =>
+        keys.indexOf(`type:${type}`),
+      ),
+    );
+    expect(firstTypeIndex).toBeGreaterThan(lastLevelIndex);
+  });
 });

package/src/theme/expandTypeScale.ts

@@ -368,6 +368,23 @@ export function generateTypeScaleComponents(
       lineHeight: `var(--text-heading-${level}-leading)`,
     };
   }
+  // `Heading` renders both a `level:N` and, when set, a `type:display-N`
+  // visual-prop class simultaneously (type sizing takes precedence over
+  // level sizing — see Heading.tsx's own `type ? sizeByTypeStyles[type] :
+  // sizeByLevelStyles[level]`). Without a `type:display-N` rule here, the
+  // `level:N` rule is the only one that matches, so it silently wins
+  // regardless of `type` once a theme supplies a type scale. Emitting these
+  // after the level rules keeps them later in source order, so they take
+  // precedence at equal specificity, matching the component's own logic.
+  // fontWeight is intentionally omitted, mirroring the `text` branch below
+  // and preserving `defaultWeightByTypeStyles`.
+  for (const type of ['display-1', 'display-2', 'display-3']) {
+    headingRules[`type:${type}`] = {
+      fontFamily: 'var(--font-family-heading)',
+      fontSize: `var(--text-${type}-size)`,
+      lineHeight: `var(--text-${type}-leading)`,
+    };
+  }
   components.heading = headingRules;
 
   const textRules: Record<string, Record<string, string>> = {};

package/src/theme/generateThemeRules.test.ts

@@ -385,46 +385,46 @@ describe('derived var expansion', () => {
     expect(rule).toContain('--_button-radius: 8px');
   });
 
-  it('emits internal vars for avatar fallback typography (base)', () => {
+  it('emits direct rules for avatar fallback background, color, and weight', () => {
     const theme = defineTheme({
-      name: 'test-derived-avatar',
+      name: 'test-avatar-fallback',
       components: {
-        avatar: {
+        'avatar-fallback': {
           base: {
-            fontWeight: 'var(--font-weight-normal)',
-            color: 'var(--color-text-secondary)',
             backgroundColor: 'var(--color-accent-muted)',
+            color: 'var(--color-text-secondary)',
+            fontWeight: 'var(--font-weight-normal)',
           },
         },
       },
     });
     const rules = generateThemeRules(theme);
-    const rule = rules.find(r => r.includes('.astryx-avatar'));
+    const rule = rules.find(r => r.includes('.astryx-avatar-fallback'));
     expect(rule).toBeDefined();
-    expect(rule).toContain(
-      '--_avatar-fallback-font-weight: var(--font-weight-normal)',
-    );
-    expect(rule).toContain(
-      '--_avatar-fallback-color: var(--color-text-secondary)',
-    );
-    expect(rule).toContain(
-      '--_avatar-fallback-background: var(--color-accent-muted)',
-    );
+    expect(rule).toContain('background-color: var(--color-accent-muted)');
+    expect(rule).toContain('color: var(--color-text-secondary)');
+    expect(rule).toContain('font-weight: var(--font-weight-normal)');
+    // These are direct class targets now, not internal derived vars.
+    expect(rule).not.toContain('--_avatar-fallback-background');
+    expect(rule).not.toContain('--_avatar-fallback-color');
+    expect(rule).not.toContain('--_avatar-fallback-font-weight');
   });
 
-  it('emits a per-size fallback font-size for avatar (size:sm)', () => {
+  it('emits a direct per-size font-size rule for the avatar fallback target', () => {
     const theme = defineTheme({
-      name: 'test-derived-avatar-size',
+      name: 'test-avatar-fallback-size',
       components: {
-        avatar: {
+        'avatar-fallback': {
           'size:sm': {fontSize: '9px'},
         },
       },
     });
     const rules = generateThemeRules(theme);
-    const rule = rules.find(r => r.includes('.astryx-avatar.sm'));
+    const rule = rules.find(r => r.includes('.astryx-avatar-fallback.sm'));
     expect(rule).toBeDefined();
-    expect(rule).toContain('--_avatar-fallback-font-size: 9px');
+    expect(rule).toContain('font-size: 9px');
+    // Direct class target now — no internal derived var.
+    expect(rule).not.toContain('--_avatar-fallback-font-size');
   });
 
   it('does not emit derived vars for components without registry entries', () => {
@@ -475,6 +475,27 @@ describe('derived var expansion', () => {
     expect(rule).toContain('border-radius: 16px');
     expect(rule).toContain('--_card-radius: 16px');
   });
+
+  it('replaces paddingInline with the var for textarea (no raw property)', () => {
+    const theme = defineTheme({
+      name: 'test-derived-textarea',
+      components: {
+        textarea: {
+          base: {paddingInline: 'var(--eps-input-padding-x)'},
+        },
+      },
+    });
+    const rules = generateThemeRules(theme);
+    const rule = rules.find(r => r.includes('.astryx-textarea'));
+    expect(rule).toBeDefined();
+    // Value flows to the inner <textarea> via the var…
+    expect(rule).toContain(
+      '--_textarea-inline-padding: var(--eps-input-padding-x)',
+    );
+    // …and must NOT land on the flush wrapper, which would re-inset the
+    // full-bleed textarea and push the native resize grip off the corner.
+    expect(rule).not.toContain('padding-inline: var(--eps-input-padding-x)');
+  });
 });
 
 describe('brutalist-style derived expansion', () => {

package/src/theme/generateThemeRules.ts

@@ -350,9 +350,11 @@ function generateComponentRules(
       // Entries are processed in order (priority).
       // - `vars`: emit internal CSS custom property declarations
       // - `expand: 'container'`: expand padding to container layout tokens
+      // - `replaces: true`: emit only the var, dropping the source property
       let finalProps = props;
       const derivedProps: [string, string][] = [];
       let containerExpanded = false;
+      const replacedProps = new Set<string>();
 
       for (const [prop, value] of props) {
         const derived = getDerivedVars(component, prop);
@@ -366,6 +368,9 @@ function generateComponentRules(
           if (entry.expand === 'container' && PADDING_PROPS.has(prop)) {
             containerExpanded = true;
           }
+          if (entry.replaces) {
+            replacedProps.add(prop);
+          }
           if (entry.vars) {
             for (const varName of entry.vars) {
               derivedProps.push([varName, value]);
@@ -384,6 +389,12 @@ function generateComponentRules(
         finalProps = [...nonPaddingProps, ...containerTokens];
       }
 
+      // Drop properties whose derived entry set `replaces` — their value is
+      // carried by the emitted var and must not land on the class element.
+      if (replacedProps.size > 0) {
+        finalProps = finalProps.filter(([p]) => !replacedProps.has(p));
+      }
+
       if (derivedProps.length > 0) {
         finalProps = [...finalProps, ...derivedProps];
       }
@@ -708,18 +719,3 @@ export function generateThemeCSS(theme: DefinedTheme): ThemeCSSOutput {
 
   return {prose: proseCss, component: componentCss};
 }
-
-/**
- * Generate the full CSS string for a theme as a single string.
- * @deprecated Use generateThemeCSS() which returns { prose, component } for proper layering.
- * This flat version is kept for backwards compatibility with tests and simple cases.
- */
-export function generateThemeCSSFlat(theme: DefinedTheme): string {
-  const rules = generateThemeRules(theme);
-  if (rules.length === 0) {
-    return '';
-  }
-  const scopeSelector = themeScopeStart(theme.name);
-  const inner = rules.join('\n\n');
-  return `@scope (${scopeSelector}) to (${THEME_SCOPE_TO}) {\n${inner}\n}`;
-}

package/src/theme/index.ts

@@ -21,7 +21,6 @@ export type {MediaThemeProps} from './MediaTheme';
 export {
   defineTheme,
   generateThemeCSS,
-  generateThemeCSSFlat,
   generateOnMediaCSS,
   generateThemeRules,
   generateThemeRulesSplit,
@@ -30,6 +29,12 @@ export {
   isDefinedTheme,
   tokenDefaults,
 } from './defineTheme';
+export {
+  registerTheme,
+  getRegisteredTheme,
+  getRegisteredThemes,
+  resetThemes,
+} from './themeRegistry';
 export type {
   DefineThemeInput,
   DefinedTheme,
@@ -71,19 +76,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 {
@@ -95,7 +94,6 @@ export {
   shadowDefaults,
   durationDefaults,
   easeDefaults,
-  transitionDefaults,
   typographyDefaults,
   textSizeDefaults,
   fontWeightDefaults,
@@ -108,7 +106,6 @@ export {
   shadowVars,
   durationVars,
   easeVars,
-  transitionVars,
   typographyVars,
   textSizeVars,
   fontWeightVars,
@@ -125,14 +122,13 @@ export type {
   ShadowVarName,
   DurationVarName,
   EaseVarName,
-  TransitionVarName,
   TypographyVarName,
   TextSizeVarName,
   FontWeightVarName,
   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 +142,7 @@ export type {
   ResolvedThemeMode,
 } from './tokens';
 
+export type {TextColorMap} from '../Text';
 export type {
   ThemeMode,
   HeadingTag,
@@ -155,6 +152,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/tokens.stylex.ts

@@ -272,23 +272,6 @@ export const easeDefaults = {
 export const easeVars = stylex.defineVars(easeDefaults);
 
 export type EaseVarName = keyof typeof easeDefaults;
-
-// =============================================================================
-// Motion Tokens — Deprecated (transition shorthand)
-// =============================================================================
-
-/** @deprecated Use durationVars + easeVars instead */
-export const transitionDefaults = {
-  '--transition-fast': '0.15s ease',
-  '--transition-normal': '0.2s ease',
-} as const;
-
-/** @deprecated Use durationVars + easeVars instead */
-export const transitionRaw = transitionDefaults;
-
-/** @deprecated Use durationVars + easeVars instead */
-export const transitionVars = stylex.defineVars(transitionDefaults);
-
 // =============================================================================
 // Typography Tokens - Font Families
 // =============================================================================
@@ -347,8 +330,6 @@ export type SpacingVarName = keyof typeof spacingDefaults;
 export type SizeVarName = keyof typeof sizeDefaults;
 export type RadiusVarName = keyof typeof radiusDefaults;
 export type ShadowVarName = keyof typeof shadowDefaults;
-/** @deprecated Use DurationVarName | EaseVarName instead */
-export type TransitionVarName = keyof typeof transitionDefaults;
 export type TypographyVarName = keyof typeof typographyDefaults;
 export type TextSizeVarName = keyof typeof textSizeDefaults;
 export type FontWeightVarName = keyof typeof fontWeightDefaults;

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