@astryxdesign/core 0.5.0 → 0.5.1-canary.046f6ea

package/dist/i18n/resolve.js

@@ -69,55 +69,54 @@ export function resolveLocaleChain(locale) {
   }
   return chain;
 }
-function lookup(key, locale, messages, overrides) {
+function getLookup(locale, messages, overrides) {
+  const lookup = {};
   const chain = resolveLocaleChain(locale);
-
   // 1 + 2. Overrides (most specific to least specific in the chain)
   if (overrides !== undefined) {
     for (const tag of chain) {
-      const value = overrides[tag]?.[key];
-      if (value !== undefined) {
-        return value;
+      if (overrides[tag]) {
+        for (const [key, value] of Object.entries(overrides[tag])) {
+          if (lookup[key] === undefined && value !== null) {
+            lookup[key] = value;
+          }
+        }
       }
     }
   }
-
-  // 3 + 4. Shipped catalogs (most specific to least specific)
   for (const tag of chain) {
-    const entry = messages[tag]?.[key];
-    if (entry !== undefined) {
-      return entry.defaultMessage;
+    if (messages[tag]) {
+      for (const [key, value] of Object.entries(messages[tag])) {
+        if (lookup[key] === undefined && value?.defaultMessage !== null) {
+          lookup[key] = value?.defaultMessage;
+        }
+      }
     }
   }
-
-  // 5. Shipped en catalog — always present
-  const enEntry = EN_CATALOG[key];
-  if (enEntry !== undefined) {
-    return enEntry.defaultMessage;
-  }
-
-  // 6. Nothing found
-  return null;
+  return lookup;
 }
-export function resolve(key, values, locale, messages, overrides) {
-  const result = lookup(key, locale, messages, overrides);
-  if (result === null) {
-    // Fires ONLY when a key is missing from every source including the
-    // shipped `en` catalog — a real bug (typo, stale catalog, deleted key).
-    // Fallback to `en` from a non-en locale is expected and stays silent,
-    // matching the FormatJS / i18next default.
-    warnOnce(`astryx-i18n:${locale}::${key}`, 'astryx-i18n', `missing key: ${key} (locale: ${locale})`);
-    return key;
-  }
-  if (values === undefined) {
-    // Static string — skip the parser entirely for the common case
-    return result;
-  }
-  const formatted = getFormatter(result, locale).format(values);
-  // IntlMessageFormat.format returns string | (string | React elements) — we
-  // only ever pass string values so it will be a string; assert for the type
-  // system.
-  return formatted;
+export function getResolve(locale, messages, overrides) {
+  const lookup = getLookup(locale, messages, overrides);
+  return (key, values) => {
+    const result = lookup[key] ?? EN_CATALOG[key]?.defaultMessage;
+    if (result === undefined) {
+      // Fires ONLY when a key is missing from every source including the
+      // shipped `en` catalog — a real bug (typo, stale catalog, deleted key).
+      // Fallback to `en` from a non-en locale is expected and stays silent,
+      // matching the FormatJS / i18next default.
+      warnOnce(`astryx-i18n:${locale}::${key}`, 'astryx-i18n', `missing key: ${key} (locale: ${locale})`);
+      return key;
+    }
+    if (values === undefined) {
+      // Static string — skip the parser entirely for the common case
+      return result;
+    }
+    const formatted = getFormatter(result, locale).format(values);
+    // IntlMessageFormat.format returns string | (string | React elements) — we
+    // only ever pass string values so it will be a string; assert for the type
+    // system.
+    return formatted;
+  };
 }
 
 /**

package/dist/i18n/useTranslator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTranslator.d.ts","sourceRoot":"","sources":["../../src/i18n/useTranslator.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,YAAY,GAAG,CACzB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,MAAM,CAAC;AAEZ;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,IAAI,YAAY,CAO5C"}
+{"version":3,"file":"useTranslator.d.ts","sourceRoot":"","sources":["../../src/i18n/useTranslator.ts"],"names":[],"mappings":"AAwBA,MAAM,MAAM,YAAY,GAAG,CACzB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,MAAM,CAAC;AAEZ;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,IAAI,YAAY,CAG5C"}

package/dist/i18n/useTranslator.js

@@ -18,9 +18,8 @@
  * - /packages/core/src/i18n/index.ts
  * - /packages/core/src/i18n/t.client.ts
  */
-import { use, useCallback } from 'react';
+import { use } from 'react';
 import { InternationalizationContext } from "./InternationalizationContext.js";
-import { resolve } from "./resolve.js";
 /**
  * Returns a translator function bound to the current provider's locale.
  * Safe to call from event handlers and effects.
@@ -35,5 +34,5 @@ import { resolve } from "./resolve.js";
  */
 export function useTranslator() {
   const ctx = use(InternationalizationContext);
-  return useCallback((key, values) => resolve(key, values, ctx.locale, ctx.messages, ctx.overrides), [ctx.locale, ctx.messages, ctx.overrides]);
+  return ctx.translate;
 }

package/dist/index.d.ts

@@ -98,7 +98,7 @@ export type { LayerAlignment, LayerPlacement, ContextRenderProps, FixedRenderPro
 export { LayerProvider } from './Layer';
 export type { LayerProviderProps, LayerToastConfig } from './Layer';
 export { Toast, useToast } from './Toast';
-export type { ToastProps, ToastType, ToastPosition, ToastCollisionBehavior, ToastDismissReason, ToastOptions, ToastDismissFn, ShowToastFn, } from './Toast';
+export type { ToastProps, ToastType, ToastPosition, ToastCollisionBehavior, ToastDismissReason, ToastOptions, ToastDismissFn, ShowToastFn, ToastContentRenderProps, ToastContentRenderFn, } from './Toast';
 export * from './Popover';
 export * from './HoverCard';
 export * from './Tooltip';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/theme/Theme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Theme.d.ts","sourceRoot":"","sources":["../../src/theme/Theme.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAgD,MAAM,OAAO,CAAC;AAGrE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAmB,KAAK,YAAY,EAAC,MAAM,eAAe,CAAC;AAMlE;;GAEG;AACH,UAAU,UAAU;IAClB,+BAA+B;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,kDAAkD;IAClD,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,yBAAyB;IACzB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAsKD;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,EACpB,KAAK,EACL,IAAe,EACf,QAAQ,GACT,EAAE,UAAU,GAAG,KAAK,CAAC,YAAY,CA+BjC;yBAnCe,KAAK"}
+{"version":3,"file":"Theme.d.ts","sourceRoot":"","sources":["../../src/theme/Theme.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAgD,MAAM,OAAO,CAAC;AAGrE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAmB,KAAK,YAAY,EAAC,MAAM,eAAe,CAAC;AAOlE;;GAEG;AACH,UAAU,UAAU;IAClB,+BAA+B;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,kDAAkD;IAClD,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,yBAAyB;IACzB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAwMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,EACpB,KAAK,EACL,IAAe,EACf,QAAQ,GACT,EAAE,UAAU,GAAG,KAAK,CAAC,YAAY,CA+BjC;yBAnCe,KAAK"}

package/dist/theme/Theme.js

@@ -41,6 +41,7 @@ import * as stylex from '@stylexjs/stylex';
 import "./tokens.stylex.js";
 import { colorVars, typographyVars } from "./tokens.stylex.js";
 import { generateThemeCSS } from "./defineTheme.js";
+import { generateDataTokenDefaultsCSS } from "./generateThemeRules.js";
 import { registerTheme } from "./themeRegistry.js";
 import { dataAttr } from "../naming.js";
 import { ThemeContext } from "./useTheme.js";
@@ -93,6 +94,16 @@ ThemeNestingContext.displayName = 'ThemeNestingContext';
 /** Track which themes have already been injected */
 const injectedThemes = new Set();
 
+/**
+ * How many mounted `Theme`s are relying on the injected data-token defaults.
+ *
+ * The defaults are one document-wide `:root` block, shared by every theme, so
+ * they are injected once and removed only when the last theme that took a
+ * reference unmounts — tearing them down with whichever provider happened to
+ * inject them would strip the palette from the providers still mounted.
+ */
+let dataTokenDefaultsRefCount = 0;
+
 /**
  * Hook to inject theme CSS into the document.
  * Built themes (from `astryx theme build`) skip injection — their CSS
@@ -105,6 +116,9 @@ function useThemeStyleInjection(theme) {
     if (theme.__built) {
       return;
     }
+
+    // Second and later `Theme`s using this theme do no work at all —
+    // generation included. Its CSS is document-wide and identical for each.
     const themeKey = `astryx-theme-${theme.name}`;
     if (injectedThemes.has(themeKey)) {
       return;
@@ -116,8 +130,26 @@ function useThemeStyleInjection(theme) {
       prose,
       component
     } = generateThemeCSS(theme);
-    if (!prose && !component) {
-      return;
+    const base = generateDataTokenDefaultsCSS();
+    injectedThemes.add(themeKey);
+    const cleanups = [() => injectedThemes.delete(themeKey)];
+
+    // Data token defaults go into @layer astryx-base, where StyleX puts the
+    // core token defaults, so a theme's own `--color-data-*` outranks them by
+    // layer. Appended (never prepended) so it cannot register `astryx-base`
+    // ahead of `reset` and invert the layer order.
+    if (base) {
+      if (dataTokenDefaultsRefCount++ === 0) {
+        const baseStyle = document.createElement('style');
+        baseStyle.setAttribute(dataAttr('theme-base'), '');
+        baseStyle.textContent = `@layer astryx-base {\n${base}\n}`;
+        document.head.appendChild(baseStyle);
+      }
+      cleanups.push(() => {
+        if (--dataTokenDefaultsRefCount === 0) {
+          document.querySelector(`style[${dataAttr('theme-base')}]`)?.remove();
+        }
+      });
     }
 
     // Prose defaults go into @layer reset — lowest priority, scoped to
@@ -139,15 +171,19 @@ function useThemeStyleInjection(theme) {
       compStyle.textContent = `@layer astryx-theme {\n${component}\n}`;
       document.head.appendChild(compStyle);
     }
-    injectedThemes.add(themeKey);
+    if (prose || component) {
+      cleanups.push(() => {
+        // Matched by the astryx id marker, which is always written above.
+        const proseEl = document.querySelector(`style[${dataAttr('theme-prose')}="${theme.name}"][${dataAttr('id')}="${id}"]`);
+        const compEl = document.querySelector(`style[${dataAttr('theme')}="${theme.name}"][${dataAttr('id')}="${id}"]`);
+        proseEl?.remove();
+        compEl?.remove();
+      });
+    }
     return () => {
-      // Remove both prose and component style tags (matched by the new
-      // astryx id marker, which is always written above).
-      const proseEl = document.querySelector(`style[${dataAttr('theme-prose')}="${theme.name}"][${dataAttr('id')}="${id}"]`);
-      const compEl = document.querySelector(`style[${dataAttr('theme')}="${theme.name}"][${dataAttr('id')}="${id}"]`);
-      proseEl?.remove();
-      compEl?.remove();
-      injectedThemes.delete(themeKey);
+      for (const cleanup of cleanups) {
+        cleanup();
+      }
     };
   }, [theme, id]);
 }

package/dist/theme/defineTheme.d.ts

@@ -33,7 +33,13 @@
  *   drift guard is scripts/check-theme-template.test.mjs)
  * - /packages/cli/assets/docs/theme.doc.mjs (`astryx docs theme`)
  */
-import type { IconRegistry } from '../Icon/globalIconRegistry';
+import type { ReactNode } from 'react';
+import type { IconName, NamespacedIconName } from '../Icon/globalIconRegistry';
+/**
+ * Icon overrides a theme may declare: any built-in semantic name, plus the
+ * namespaced keys components and libraries own (`'richtext:bold'`).
+ */
+type ThemeIconOverrides = Partial<Record<IconName | NamespacedIconName, ReactNode>>;
 import type { IndicatorRegistry } from '../Indicator/types';
 import type { TypographyConfig } from './types';
 import { type OnMediaOverrides, type ResolvedOnMedia } from './onMediaTokens';
@@ -265,7 +271,7 @@ export interface DefineThemeInput {
      */
     components?: ComponentStyleMap;
     /** Icon registry — maps semantic icon names to React nodes */
-    icons?: Partial<IconRegistry>;
+    icons?: ThemeIconOverrides;
     /**
      * Indicator overrides — replaces the components that draw stateful control
      * visuals with the theme's own, by name.
@@ -326,7 +332,7 @@ export interface DefinedTheme {
     /** Component style overrides */
     components?: ComponentStyleMap;
     /** Icon registry */
-    icons?: Partial<IconRegistry>;
+    icons?: ThemeIconOverrides;
     /** Indicator overrides for stateful control visuals, keyed by name */
     indicators?: IndicatorRegistry;
     /** Whether this theme has been pre-compiled by theme build CLI */

package/dist/theme/defineTheme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defineTheme.d.ts","sourceRoot":"","sources":["../../src/theme/defineTheme.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"defineTheme.d.ts","sourceRoot":"","sources":["../../src/theme/defineTheme.ts"],"names":[],"mappings":"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"}

package/dist/theme/defineTheme.js

@@ -36,6 +36,11 @@
  * - /packages/cli/assets/docs/theme.doc.mjs (`astryx docs theme`)
  */
 
+/**
+ * Icon overrides a theme may declare: any built-in semantic name, plus the
+ * namespaced keys components and libraries own (`'richtext:bold'`).
+ */
+
 import { resolveOnMedia } from "./onMediaTokens.js";
 import { colorDefaults, spacingDefaults, sizeDefaults, borderDefaults, focusDefaults, radiusDefaults, shadowDefaults, durationDefaults, easeDefaults, typographyDefaults, textSizeDefaults, fontWeightDefaults, typeScaleDefaults } from "./tokens.stylex.js";
 import { expandTypeScale, generateTypeScaleComponents } from "./expandTypeScale.js";

package/dist/theme/derivedVarRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derivedVarRegistry.d.ts","sourceRoot":"","sources":["../../src/theme/derivedVarRegistry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,iFAAiF;IACjF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,CA8ChE,CAAC;AAEF;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,eAAe,EAAE,CAMnB"}
+{"version":3,"file":"derivedVarRegistry.d.ts","sourceRoot":"","sources":["../../src/theme/derivedVarRegistry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,iFAAiF;IACjF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,CA+ChE,CAAC;AAiBF;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,eAAe,EAAE,CASnB"}

package/dist/theme/derivedVarRegistry.js

@@ -26,6 +26,10 @@
  * entries share the same property.
  */
 export const derivedVarRegistry = {
+  avatar: [{
+    property: 'borderRadius',
+    vars: ['--_avatar-radius']
+  }],
   banner: [{
     property: 'borderRadius',
     vars: ['--_banner-radius']
@@ -73,7 +77,7 @@ export const derivedVarRegistry = {
     property: 'borderRadius',
     vars: ['--_field-radius']
   }],
-  hovercard: [{
+  'hover-card': [{
     property: 'borderRadius',
     vars: ['--_hovercard-radius']
   }],
@@ -88,7 +92,7 @@ export const derivedVarRegistry = {
     property: 'borderRadius',
     vars: ['--_popover-radius']
   }],
-  'progressbar-mark': [{
+  'progress-bar-mark': [{
     property: 'width',
     vars: ['--_progressbar-mark-width'],
     replaces: true
@@ -108,19 +112,35 @@ export const derivedVarRegistry = {
     property: 'padding',
     vars: ['--_segmented-control-padding']
   }],
-  textarea: [{
+  'text-area': [{
     property: 'paddingInline',
     vars: ['--_textarea-inline-padding'],
     replaces: true
   }]
 };
 
+/**
+ * Deprecated component keys → the key that superseded them.
+ *
+ * A renamed target keeps emitting its old class, so a theme written against
+ * the old key still selects the element. Without this the rule would land but
+ * its derived vars would not expand, and the half that travels through a var
+ * (a hover card's radius, a text area's inline padding) would silently do
+ * nothing. Drop these with the classes, in the next major.
+ */
+const DEPRECATED_REGISTRY_KEYS = {
+  hovercard: 'hover-card',
+  'progressbar-mark': 'progress-bar-mark',
+  textarea: 'text-area'
+};
+
 /**
  * Look up derived var entries for a component + CSS property.
  * Returns matching entries in priority order, or empty array if none.
  */
 export function getDerivedVars(component, property) {
-  const entries = derivedVarRegistry[component];
+  const renamedTo = DEPRECATED_REGISTRY_KEYS[component];
+  const entries = derivedVarRegistry[component] ?? (renamedTo ? derivedVarRegistry[renamedTo] : undefined);
   if (!entries) {
     return [];
   }

package/dist/theme/generateThemeRules.d.ts

@@ -68,6 +68,24 @@ export declare function generateThemeRulesSplit(theme: DefinedTheme): ThemeRules
  * via onDark.components / onLight.components.
  */
 export declare function generateOnMediaCSS(theme: DefinedTheme): string;
+/**
+ * The `--color-data-*` defaults as one unscoped `:root` block.
+ *
+ * Core tokens reach CSS once, at `:root`, from StyleX's `defineVars` output in
+ * `@layer astryx-base`; a theme's own scope block then carries only the tokens
+ * that theme overrides, which is why a nested theme inherits its parent's
+ * override instead of shadowing it. Data tokens are not StyleX vars, so nothing
+ * declares them — this is their equivalent, and callers put it in
+ * `@layer astryx-base` so a theme's override wins by layer rather than by
+ * specificity. Seeding it per theme scope instead re-declares the default
+ * inside every nested theme, which is the shadowing this shape avoids.
+ *
+ * @internal Not exported from `@astryxdesign/core/theme`: the `<Theme>`
+ * runtime is the only caller. `astryx theme build` formats the same block from
+ * the public `dataTokenDefaults` export, and a CLI test asserts the two are
+ * byte-identical.
+ */
+export declare function generateDataTokenDefaultsCSS(): string;
 /**
  * Generate layered CSS for a theme — runtime path.
  *
@@ -78,6 +96,9 @@ export declare function generateOnMediaCSS(theme: DefinedTheme): string;
  * This separation ensures prose defaults (what bare HTML looks like in a theme)
  * sit at reset-layer priority where any class-based style wins, while component
  * overrides sit above StyleX so themes can restyle components intentionally.
+ *
+ * The theme-independent `--color-data-*` defaults are not part of this output:
+ * see `generateDataTokenDefaultsCSS`.
  */
 export declare function generateThemeCSS(theme: DefinedTheme): ThemeCSSOutput;
 //# sourceMappingURL=generateThemeRules.d.ts.map

package/dist/theme/generateThemeRules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateThemeRules.d.ts","sourceRoot":"","sources":["../../src/theme/generateThemeRules.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,eAAe,CAAC;AAgGhD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AA8LD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE,CAoChE;AAkRD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,YAAY,GAAG,eAAe,CAe5E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CA4E9D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,cAAc,CA2BpE"}
+{"version":3,"file":"generateThemeRules.d.ts","sourceRoot":"","sources":["../../src/theme/generateThemeRules.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,eAAe,CAAC;AAiGhD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AA8LD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE,CAoChE;AAkRD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,YAAY,GAAG,eAAe,CAe5E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CA4E9D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,4BAA4B,IAAI,MAAM,CAKrD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,cAAc,CA2BpE"}

package/dist/theme/generateThemeRules.js

@@ -17,6 +17,7 @@
 
 import { parseStyleKey } from "../utils/parseStyleKey.js";
 import { getDerivedVars } from "./derivedVarRegistry.js";
+import { dataTokenDefaults } from "./domainTokens/dataTokens.js";
 import { cssVar, classPrefix, dataAttrNamespace } from "../naming.js";
 
 /**
@@ -623,6 +624,28 @@ export function generateOnMediaCSS(theme) {
   return `@scope (${scopeSelector}) to (${THEME_SCOPE_TO}) {\n${inner}\n}`;
 }
 
+/**
+ * The `--color-data-*` defaults as one unscoped `:root` block.
+ *
+ * Core tokens reach CSS once, at `:root`, from StyleX's `defineVars` output in
+ * `@layer astryx-base`; a theme's own scope block then carries only the tokens
+ * that theme overrides, which is why a nested theme inherits its parent's
+ * override instead of shadowing it. Data tokens are not StyleX vars, so nothing
+ * declares them — this is their equivalent, and callers put it in
+ * `@layer astryx-base` so a theme's override wins by layer rather than by
+ * specificity. Seeding it per theme scope instead re-declares the default
+ * inside every nested theme, which is the shadowing this shape avoids.
+ *
+ * @internal Not exported from `@astryxdesign/core/theme`: the `<Theme>`
+ * runtime is the only caller. `astryx theme build` formats the same block from
+ * the public `dataTokenDefaults` export, and a CLI test asserts the two are
+ * byte-identical.
+ */
+export function generateDataTokenDefaultsCSS() {
+  const declarations = Object.entries(dataTokenDefaults).map(([prop, value]) => `  ${prop}: ${value};`).join('\n');
+  return `:root {\n${declarations}\n}`;
+}
+
 /**
  * Generate layered CSS for a theme — runtime path.
  *
@@ -633,6 +656,9 @@ export function generateOnMediaCSS(theme) {
  * This separation ensures prose defaults (what bare HTML looks like in a theme)
  * sit at reset-layer priority where any class-based style wins, while component
  * overrides sit above StyleX so themes can restyle components intentionally.
+ *
+ * The theme-independent `--color-data-*` defaults are not part of this output:
+ * see `generateDataTokenDefaultsCSS`.
  */
 export function generateThemeCSS(theme) {
   const {

package/dist/theme/syntax/tokens.d.ts

@@ -29,7 +29,7 @@ export declare const syntaxTokenDefaults: {
     readonly '--color-syntax-tag': "var(--color-text-red)";
     readonly '--color-syntax-attribute': "var(--color-text-teal)";
     readonly '--color-syntax-property': "var(--color-text-cyan)";
-    readonly '--color-syntax-punctuation': "var(--color-text-disabled)";
+    readonly '--color-syntax-punctuation': "var(--color-text-secondary)";
     readonly '--color-syntax-background': "var(--color-background-muted)";
 };
 export type SyntaxTokenName = keyof typeof syntaxTokenDefaults;

package/dist/theme/syntax/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../../src/theme/syntax/tokens.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;CA6BtB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,mBAAmB,CAAC"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../../src/theme/syntax/tokens.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;CAgCtB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,mBAAmB,CAAC"}

package/dist/theme/syntax/tokens.js

@@ -44,8 +44,11 @@ export const syntaxTokenDefaults = {
   '--color-syntax-attribute': 'var(--color-text-teal)',
   // property -> cyan text (object properties)
   '--color-syntax-property': 'var(--color-text-cyan)',
-  // punctuation -> disabled text (brackets, semicolons)
-  '--color-syntax-punctuation': 'var(--color-text-disabled)',
+  // punctuation -> secondary text (brackets, semicolons). Not disabled text:
+  // disabled grey is calibrated to fail AA on purpose (WCAG exempts inactive
+  // controls), and punctuation in a code sample is normal, always-active
+  // text — see #5386.
+  '--color-syntax-punctuation': 'var(--color-text-secondary)',
   // background -> muted surface
   '--color-syntax-background': 'var(--color-background-muted)'
 };

package/dist/theme/useTheme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTheme.d.ts","sourceRoot":"","sources":["../../src/theme/useTheme.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,eAAe,CAAC;AAUhD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,0CAA0C;IAC1C,IAAI,EAAE,SAAS,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,mDAAgD,CAAC;AAO1E;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB;;;;;;;;;;;;;OAaG;IACH,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAChC;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AA+HD;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAM5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,QAAQ,IAAI,cAAc,CAmCzC"}
+{"version":3,"file":"useTheme.d.ts","sourceRoot":"","sources":["../../src/theme/useTheme.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,eAAe,CAAC;AAUhD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,0CAA0C;IAC1C,IAAI,EAAE,SAAS,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,mDAAgD,CAAC;AAO1E;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB;;;;;;;;;;;;;OAaG;IACH,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAChC;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AA+HD;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAM5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,QAAQ,IAAI,cAAc,CAmCzC"}

package/dist/theme/useTheme.js

@@ -20,7 +20,7 @@
  * SYNC: When modified, update:
  * - /packages/core/src/theme/index.ts
  */
-import { createContext, use, useMemo, useSyncExternalStore } from 'react';
+import { createContext, use, useCallback, useMemo, useSyncExternalStore } from 'react';
 import { resolveThemeTokens } from "./tokens.js";
 import { getRegisteredTheme } from "./themeRegistry.js";
 import { dataAttr } from "../naming.js";
@@ -207,13 +207,12 @@ export function useTheme() {
   const tokens = useMemo(() => resolveThemeTokens(theme, {
     mode: effectiveMode
   }), [theme, effectiveMode]);
-  const token = name => {
-    return tokens[name] ?? '';
-  };
-  return {
-    name: theme?.name ?? 'default',
+  const token = useCallback(name => tokens[name] ?? '', [tokens]);
+  const name = theme?.name ?? 'default';
+  return useMemo(() => ({
+    name,
     mode: effectiveMode,
     token,
     tokens
-  };
+  }), [name, effectiveMode, token, tokens]);
 }

package/dist/utils/dateParser.d.ts

@@ -19,14 +19,11 @@ export declare function isLocaleDayFirst(locale?: Locale): boolean;
 /**
  * Parses user input into a PlainDate.
  *
- * Supports:
- * - ISO format: "2026-01-25"
- * - Full month names: "January 25, 2026", "25 January 2026"
- * - Full month names without year: "January 25", "25 January" (defaults to current year)
- * - Numeric formats: "1/25/2026", "25/1/2026" (locale-aware with heuristics)
- * - Numeric formats without year: "1/25", "25/1" (defaults to current year)
- *
- * For ambiguous numeric formats (both numbers ≤ 12), uses locale preference.
+ * Supports ISO dates, English month names, and ASCII numeric dates with or
+ * without a year. For ambiguous ASCII numeric input where both fields are at
+ * most 12, `locale` selects month-first versus day-first order. It does not
+ * localize month-name parsing, accept non-ASCII digits, or provide a general
+ * locale-aware parser.
  *
  * @returns PlainDate if valid, null if unparseable
  */

package/dist/utils/dateParser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dateParser.d.ts","sourceRoot":"","sources":["../../src/utils/dateParser.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,OAAO,EAAC,KAAK,SAAS,EAAqC,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,eAAe,CAAC;AAE1C,OAAO,EACL,gBAAgB,IAAI,QAAQ,EAC5B,cAAc,IAAI,SAAS,GAC5B,MAAM,aAAa,CAAC;AAErB;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAOzD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,GACd,SAAS,GAAG,IAAI,CAsGlB"}
+{"version":3,"file":"dateParser.d.ts","sourceRoot":"","sources":["../../src/utils/dateParser.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,OAAO,EAAC,KAAK,SAAS,EAAqC,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,eAAe,CAAC;AAE1C,OAAO,EACL,gBAAgB,IAAI,QAAQ,EAC5B,cAAc,IAAI,SAAS,GAC5B,MAAM,aAAa,CAAC;AAErB;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,MAAa,GAAG,OAAO,CAO/D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,MAAa,GACpB,SAAS,GAAG,IAAI,CAsGlB"}

package/dist/utils/dateParser.js

@@ -18,8 +18,10 @@ export { plainDateFromISO as parseISO, plainDateToISO as dateToISO } from "./pla
  * Detects if the locale uses day-first date format (DD/MM/YYYY).
  * US and a few others use month-first (MM/DD/YYYY).
  */
-export function isLocaleDayFirst(locale) {
-  const parts = new Intl.DateTimeFormat(locale).formatToParts(new Date(2000, 0, 15));
+export function isLocaleDayFirst(locale = 'en') {
+  const parts = new Intl.DateTimeFormat(locale, {
+    calendar: 'gregory'
+  }).formatToParts(new Date(2000, 0, 15));
   const dayIndex = parts.findIndex(p => p.type === 'day');
   const monthIndex = parts.findIndex(p => p.type === 'month');
   return dayIndex < monthIndex;
@@ -28,18 +30,15 @@ export function isLocaleDayFirst(locale) {
 /**
  * Parses user input into a PlainDate.
  *
- * Supports:
- * - ISO format: "2026-01-25"
- * - Full month names: "January 25, 2026", "25 January 2026"
- * - Full month names without year: "January 25", "25 January" (defaults to current year)
- * - Numeric formats: "1/25/2026", "25/1/2026" (locale-aware with heuristics)
- * - Numeric formats without year: "1/25", "25/1" (defaults to current year)
- *
- * For ambiguous numeric formats (both numbers ≤ 12), uses locale preference.
+ * Supports ISO dates, English month names, and ASCII numeric dates with or
+ * without a year. For ambiguous ASCII numeric input where both fields are at
+ * most 12, `locale` selects month-first versus day-first order. It does not
+ * localize month-name parsing, accept non-ASCII digits, or provide a general
+ * locale-aware parser.
  *
  * @returns PlainDate if valid, null if unparseable
  */
-export function parseDateInput(input, locale) {
+export function parseDateInput(input, locale = 'en') {
   const trimmed = input.trim();
   if (!trimmed) {
     return null;