@astryxdesign/core 0.4.2 → 0.4.3-canary.551a8de

package/dist/theme/defineTheme.js

@@ -44,6 +44,7 @@ import { expandRadiusScale } from "./expandRadiusScale.js";
 import { expandColorScale } from "./expandColorScale.js";
 import { domainTokenDefaults } from "./domainTokens/index.js";
 import { registerTheme } from "./themeRegistry.js";
+import { deepMergeComponents } from "./mergeComponents.js";
 
 // =============================================================================
 // Types
@@ -155,48 +156,6 @@ function resolveTokenValue(value) {
   return value;
 }
 
-/**
- * Deep-merge two component style maps.
- * Properties in `overrides` take precedence over `base`.
- * This allows typeScale-generated rules to be overridden by explicit components.
- */
-function deepMergeComponents(base, overrides) {
-  if (!base && !overrides) {
-    return undefined;
-  }
-  if (!base) {
-    return overrides;
-  }
-  if (!overrides) {
-    return base;
-  }
-  const result = {};
-
-  // Start with all base entries
-  for (const [component, rules] of Object.entries(base)) {
-    result[component] = {
-      ...rules
-    };
-  }
-
-  // Merge overrides on top
-  for (const [component, rules] of Object.entries(overrides)) {
-    if (!result[component]) {
-      result[component] = {
-        ...rules
-      };
-    } else {
-      for (const [key, styles] of Object.entries(rules)) {
-        result[component][key] = {
-          ...result[component][key],
-          ...styles
-        };
-      }
-    }
-  }
-  return result;
-}
-
 /**
  * Resolve a FontWeight name to a var() reference.
  * Named weights map to var(--font-weight-*); raw values pass through.
@@ -226,6 +185,24 @@ function buildFontFamily(family, fallbacks) {
   return quoted;
 }
 
+/**
+ * Describe a rejected `extends` value for the error message — enough to tell a
+ * missed import (`undefined`) from a module namespace or a plain object.
+ */
+function describeBadBase(value) {
+  if (value === undefined) {
+    return 'undefined';
+  }
+  if (value === null) {
+    return 'null';
+  }
+  if (typeof value !== 'object') {
+    return typeof value;
+  }
+  const keys = Object.keys(value);
+  return `an object with keys [${keys.slice(0, 4).join(', ')}${keys.length > 4 ? ', …' : ''}]`;
+}
+
 /**
  * Create an Astryx theme.
  *
@@ -239,7 +216,15 @@ function buildFontFamily(family, fallbacks) {
 export function defineTheme(input) {
   const tokens = {};
 
-  // 0. Pre-seed from base theme when `extends` is provided (lowest precedence)
+  // 0. Pre-seed from base theme when `extends` is provided (lowest precedence).
+  // A base that is not a theme is refused rather than ignored: `extends` used
+  // to inherit nothing when its value was undefined, which is what a named
+  // import silently resolving to the wrong module hands over, and the theme
+  // then built into a plausible-looking stylesheet missing everything it was
+  // supposed to inherit.
+  if ('extends' in input && !isDefinedTheme(input.extends)) {
+    throw new Error(`defineTheme("${input.name}"): \`extends\` must be a theme from defineTheme(), got ${describeBadBase(input.extends)}. ` + `Check that the import naming your base theme resolves to its source and exports that name — ` + `a generated \`<theme>.js\` artifact sitting next to the source exports \`<name>Theme\`, not the source's own export.`);
+  }
   const base = input.extends;
   if (base) {
     for (const [key, value] of Object.entries(base.tokens)) {
@@ -370,9 +355,10 @@ export function defineTheme(input) {
     components = deepMergeComponents(base.components, components);
   }
 
-  // 4. Resolve on-media token overrides (defaults + user overrides)
-  const __onDark = resolveOnMedia('dark', input.onDark);
-  const __onLight = resolveOnMedia('light', input.onLight);
+  // 4. Resolve on-media token overrides (base's resolved surface, then
+  // defaults, then this theme's own overrides)
+  const __onDark = resolveOnMedia('dark', input.onDark, base?.__onDark);
+  const __onLight = resolveOnMedia('light', input.onLight, base?.__onLight);
 
   // 5. Merge icons — input icons override base icons
   const icons = input.icons && base?.icons ? {
@@ -392,7 +378,10 @@ export function defineTheme(input) {
     components,
     icons,
     indicators,
-    __inputTokens: input.tokens,
+    __inputTokens: base?.__inputTokens || input.tokens ? {
+      ...base?.__inputTokens,
+      ...input.tokens
+    } : undefined,
     __onDark,
     __onLight
   };

package/dist/theme/expandColorScale.d.ts

@@ -6,6 +6,9 @@
  * // Minimal — just a seed color
  * { accent: '#0064E0' }
  *
+ * // Per-scheme seeds: light palettes from '#0064E0', dark from '#48CAE4'
+ * { accent: ['#0064E0', '#48CAE4'] }
+ *
  * // With customization
  * { accent: '#B7410E', neutralStyle: 'warm', contrast: 'high' }
  *
@@ -15,14 +18,18 @@
  */
 export interface ColorScaleConfig {
     /**
-     * Seed accent color as hex (#RRGGBB). Everything derives from this.
+     * Seed accent color. Everything derives from this.
+     *
+     * Either a single hex (#RRGGBB) used for both color schemes, or a
+     * `[light, dark]` hex tuple: the light scheme's palettes derive from
+     * the light seed and the dark scheme's palettes from the dark seed.
      *
      * 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;
+    accent?: string | [light: string, dark: string];
     /**
      * Neutral tone warmth. Controls how much of the seed's hue bleeds
      * into neutral/background colors.
@@ -56,6 +63,11 @@ export declare function ensureContrastTone(hue: number, chroma: number, startTon
  * --color-on-dark/on-light) are NOT generated — they fall through
  * to colorDefaults.
  *
+ * A `[light, dark]` tuple accent seeds each scheme separately: the light
+ * half of every generated `light-dark()` pair comes from the light seed's
+ * palettes, the dark half from the dark seed's. A string accent seeds both
+ * halves from the same palettes, exactly as before tuples were supported.
+ *
  * 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.
@@ -65,6 +77,9 @@ export declare function ensureContrastTone(hue: number, chroma: number, startTon
  * const tokens = expandColorScale({ accent: '#0064E0' });
  * // tokens['--color-accent'] === 'light-dark(#..., #...)'
  *
+ * const perScheme = expandColorScale({ accent: ['#0064E0', '#48CAE4'] });
+ * // light half derives from #0064E0, dark half from #48CAE4
+ *
  * const neutralOnly = expandColorScale({ neutralStyle: 'warm' });
  * // neutralOnly['--color-accent'] === undefined
  * ```

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

@@ -1 +1 @@
-{"version":3,"file":"expandColorScale.d.ts","sourceRoot":"","sources":["../../src/theme/expandColorScale.ts"],"names":[],"mappings":"AAwCA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAE3C;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CAChC;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAyCtD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,MAAM,CAYR;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAoI3E"}
+{"version":3,"file":"expandColorScale.d.ts","sourceRoot":"","sources":["../../src/theme/expandColorScale.ts"],"names":[],"mappings":"AAgDA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAEhD;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAE3C;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CAChC;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAyCtD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,MAAM,CAYR;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CA0J3E"}

package/dist/theme/expandColorScale.js

@@ -6,8 +6,8 @@
  * @output Token overrides for derivable color tokens
  * @position Theme utility; consumed by defineTheme.ts
  *
- * Generates color token overrides from a single accent color using the
- * HCT perceptual color model. Only produces tokens that meaningfully
+ * Generates color token overrides from an accent seed using the HCT
+ * perceptual color model. Only produces tokens that meaningfully
  * derive from the accent — status colors, categorical hues, and fixed
  * tokens (on-dark/on-light) fall through to colorDefaults.
  *
@@ -15,11 +15,19 @@
  * ramp (seeded from the default accent's hue) while the accent tokens
  * themselves fall through to colorDefaults, same as the tokens above.
  *
+ * `accent` also accepts a `[light, dark]` tuple (matching `TokenValue` in
+ * defineTheme). A tuple seeds each color scheme from its own half: the
+ * light side of every generated `light-dark()` pair derives from the light
+ * accent's palettes, the dark side from the dark accent's. A plain string
+ * seeds both sides identically, token for token the same output as before
+ * tuples existed.
+ *
  * WCAG contrast guarantees (asserted in expandColorScale.test.ts):
  * - Text tones are guaranteed >= 4.5:1 against their surfaces by tone
  *   spacing alone — HCT tone is CIE L*, which fixes relative luminance
  *   regardless of hue/chroma, so the fixed tone assignments hold for any
- *   accent/neutralStyle (WCAG 1.4.3).
+ *   accent/neutralStyle (WCAG 1.4.3), and each half of a tuple pairs with
+ *   surfaces derived from that same seed.
  * - --color-border-emphasized (form-control boundaries) is tone-bumped
  *   until it reaches >= 3:1 against the generated surface (WCAG 1.4.11).
  * - --color-border, --color-skeleton, and --color-track are intentionally
@@ -46,6 +54,9 @@ import { hexToHct, hctToHex, tonalPalette, hexWithAlpha } from "./hct.js";
  * // Minimal — just a seed color
  * { accent: '#0064E0' }
  *
+ * // Per-scheme seeds: light palettes from '#0064E0', dark from '#48CAE4'
+ * { accent: ['#0064E0', '#48CAE4'] }
+ *
  * // With customization
  * { accent: '#B7410E', neutralStyle: 'warm', contrast: 'high' }
  *
@@ -126,6 +137,11 @@ export function ensureContrastTone(hue, chroma, startTone, step, background, min
  * --color-on-dark/on-light) are NOT generated — they fall through
  * to colorDefaults.
  *
+ * A `[light, dark]` tuple accent seeds each scheme separately: the light
+ * half of every generated `light-dark()` pair comes from the light seed's
+ * palettes, the dark half from the dark seed's. A string accent seeds both
+ * halves from the same palettes, exactly as before tuples were supported.
+ *
  * 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.
@@ -135,6 +151,9 @@ export function ensureContrastTone(hue, chroma, startTone, step, background, min
  * const tokens = expandColorScale({ accent: '#0064E0' });
  * // tokens['--color-accent'] === 'light-dark(#..., #...)'
  *
+ * const perScheme = expandColorScale({ accent: ['#0064E0', '#48CAE4'] });
+ * // light half derives from #0064E0, dark half from #48CAE4
+ *
  * const neutralOnly = expandColorScale({ neutralStyle: 'warm' });
  * // neutralOnly['--color-accent'] === undefined
  * ```
@@ -145,14 +164,26 @@ export function expandColorScale(config) {
     neutralStyle = 'cool',
     contrast = 'standard'
   } = config;
-  const seed = hexToHct(accent ?? DEFAULT_ACCENT_SEED);
-  const seedHue = seed.hue;
-  const primaryChroma = Math.max(seed.chroma, 48);
+
+  // Normalize to per-scheme seeds. A string accent (or an absent one) uses
+  // the same seed for both halves, which keeps single-seed output identical
+  // to the pre-tuple implementation.
+  const [lightAccent, darkAccent] = Array.isArray(accent) ? accent : [accent, accent];
+  const lightSeed = hexToHct(lightAccent ?? DEFAULT_ACCENT_SEED);
+  const sameSeed = darkAccent === lightAccent;
+  const darkSeed = sameSeed ? lightSeed : hexToHct(darkAccent ?? DEFAULT_ACCENT_SEED);
   const neutralChroma = NEUTRAL_CHROMA[neutralStyle] ?? 5;
   const neutralVariantChroma = NEUTRAL_VARIANT_CHROMA[neutralStyle] ?? 8;
-  const P = tonalPalette(seedHue, primaryChroma);
-  const N = tonalPalette(seedHue, neutralChroma);
-  const NV = tonalPalette(seedHue, neutralVariantChroma);
+
+  // Palette naming: *L palettes feed the light (first) half of each ld()
+  // pair below, *D palettes the dark (second) half. With a single seed the
+  // D palettes alias the L ones.
+  const PL = tonalPalette(lightSeed.hue, Math.max(lightSeed.chroma, 48));
+  const NL = tonalPalette(lightSeed.hue, neutralChroma);
+  const NVL = tonalPalette(lightSeed.hue, neutralVariantChroma);
+  const PD = sameSeed ? PL : tonalPalette(darkSeed.hue, Math.max(darkSeed.chroma, 48));
+  const ND = sameSeed ? NL : tonalPalette(darkSeed.hue, neutralChroma);
+  const NVD = sameSeed ? NVL : tonalPalette(darkSeed.hue, neutralVariantChroma);
   const isHigh = contrast === 'high';
   const textPrimaryLightTone = isHigh ? 0 : 10;
   const textPrimaryDarkTone = isHigh ? 99 : 90;
@@ -173,7 +204,7 @@ export function expandColorScale(config) {
   // contrast starts at 70/30 and walks toward mid-scale only as far as needed.
   const borderEmphasizedStartLight = isHigh ? 50 : 70;
   const borderEmphasizedStartDark = isHigh ? 50 : 30;
-  const borderEmphasized = ld(ensureContrastTone(seedHue, neutralVariantChroma, borderEmphasizedStartLight, -1, N[99], NON_TEXT_MIN_CONTRAST), ensureContrastTone(seedHue, neutralVariantChroma, borderEmphasizedStartDark, 1, N[10], NON_TEXT_MIN_CONTRAST));
+  const borderEmphasized = ld(ensureContrastTone(lightSeed.hue, neutralVariantChroma, borderEmphasizedStartLight, -1, NL[99], NON_TEXT_MIN_CONTRAST), ensureContrastTone(darkSeed.hue, neutralVariantChroma, borderEmphasizedStartDark, 1, ND[10], NON_TEXT_MIN_CONTRAST));
   return {
     // Core semantic — only with a seed accent. Without one these fall through
     // to colorDefaults, whose --color-accent is NOT what the default seed
@@ -181,47 +212,46 @@ export function expandColorScale(config) {
     // 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]),
+      '--color-accent': ld(PL[40], PD[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])
+      '--color-on-accent': ld(PL[100], PD[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]),
-    '--color-overlay': ld(hexWithAlpha(N[10], 0.4), hexWithAlpha(N[10], 0.6)),
-    '--color-overlay-hover': ld(hexWithAlpha(N[10], 0.05), hexWithAlpha(N[100], 0.05)),
-    '--color-overlay-pressed': ld(hexWithAlpha(N[10], 0.1), hexWithAlpha(N[100], 0.1)),
-    '--color-background-muted': ld(hexWithAlpha(N[10], 0.05), hexWithAlpha(N[10], 0.5)),
+    '--color-neutral': ld(hexWithAlpha(NL[10], 0.1), hexWithAlpha(ND[90], 0.2)),
+    '--color-background-surface': ld(NL[99], ND[10]),
+    '--color-background-body': ld(NL[95], ND[5]),
+    '--color-overlay': ld(hexWithAlpha(NL[10], 0.4), hexWithAlpha(ND[10], 0.6)),
+    '--color-overlay-hover': ld(hexWithAlpha(NL[10], 0.05), hexWithAlpha(ND[100], 0.05)),
+    '--color-overlay-pressed': ld(hexWithAlpha(NL[10], 0.1), hexWithAlpha(ND[100], 0.1)),
+    '--color-background-muted': ld(hexWithAlpha(NL[10], 0.05), hexWithAlpha(ND[10], 0.5)),
     // Text
-    '--color-text-primary': ld(N[textPrimaryLightTone], N[textPrimaryDarkTone]),
-    '--color-text-secondary': ld(NV[textSecondaryLightTone], NV[textSecondaryDarkTone]),
-    '--color-text-disabled': ld(NV[60], NV[40]),
+    '--color-text-primary': ld(NL[textPrimaryLightTone], ND[textPrimaryDarkTone]),
+    '--color-text-secondary': ld(NVL[textSecondaryLightTone], NVD[textSecondaryDarkTone]),
+    '--color-text-disabled': ld(NVL[60], NVD[40]),
     '--color-text-accent': 'var(--color-accent)',
     // Icon
     '--color-icon-accent': 'var(--color-accent)',
-    '--color-icon-primary': ld(N[textPrimaryLightTone], N[textPrimaryDarkTone]),
-    '--color-icon-secondary': ld(NV[textSecondaryLightTone], NV[textSecondaryDarkTone]),
-    '--color-icon-disabled': ld(NV[60], NV[40]),
+    '--color-icon-primary': ld(NL[textPrimaryLightTone], ND[textPrimaryDarkTone]),
+    '--color-icon-secondary': ld(NVL[textSecondaryLightTone], NVD[textSecondaryDarkTone]),
+    '--color-icon-disabled': ld(NVL[60], NVD[40]),
     // Surface variants
-    '--color-background-card': ld(N[99], N[10]),
-    '--color-background-popover': ld(N[99], N[20]),
-    '--color-background-inverted': ld(N[10], N[99]),
-    // Border
+    '--color-background-card': ld(NL[99], ND[10]),
+    '--color-background-popover': ld(NL[99], ND[20]),
+    '--color-background-inverted': ld(NL[10], ND[99]),
     // Border
     // Decorative hairline — not a WCAG 1.4.11 boundary. High contrast
     // doubles the alpha so structural boundaries stay perceivable.
-    '--color-border': ld(hexWithAlpha(N[10], borderSubtleAlpha), hexWithAlpha(N[95], borderSubtleAlpha)),
+    '--color-border': ld(hexWithAlpha(NL[10], borderSubtleAlpha), hexWithAlpha(ND[95], borderSubtleAlpha)),
     '--color-border-emphasized': borderEmphasized,
     // Effects
-    '--color-skeleton': ld(NV[70], NV[30]),
+    '--color-skeleton': ld(NVL[70], NVD[30]),
     // Channel-on-body surface (ProgressBar/Slider tracks, Switch off-state).
     // Defaults to the same NV[70]/NV[30] ramp stop as --color-skeleton.
-    '--color-track': ld(NV[70], NV[30]),
-    '--color-shadow': ld(hexWithAlpha(N[0], 0.1), hexWithAlpha(N[0], 0.3)),
+    '--color-track': ld(NVL[70], NVD[30]),
+    '--color-shadow': ld(hexWithAlpha(NL[0], 0.1), hexWithAlpha(ND[0], 0.3)),
     '--color-tint-hover': ld('black', 'white')
   };
 }

package/dist/theme/mergeComponents.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file Component style-map merging
+ *
+ * One merge rule for component overrides, shared by every layer that composes
+ * them: `extends` inheritance, generated type-scale rules, and the on-media
+ * (`onDark`/`onLight`) surfaces. Merging is per style key, so a child that
+ * restates one property of `button.base` keeps the rest of the base's.
+ *
+ * @input two ComponentStyleMaps — the base and the overrides that win
+ * @output a merged ComponentStyleMap
+ * @position packages/core/src/theme/mergeComponents.ts
+ */
+import type { ComponentStyleMap } from './defineTheme';
+/**
+ * Deep-merge component style maps: `overrides` wins per style key, and every
+ * component and key the base declared that the overrides do not mention is
+ * carried through untouched.
+ */
+export declare function deepMergeComponents(base?: ComponentStyleMap, overrides?: ComponentStyleMap): ComponentStyleMap | undefined;
+//# sourceMappingURL=mergeComponents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mergeComponents.d.ts","sourceRoot":"","sources":["../../src/theme/mergeComponents.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAErD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,CAAC,EAAE,iBAAiB,EACxB,SAAS,CAAC,EAAE,iBAAiB,GAC5B,iBAAiB,GAAG,SAAS,CAiC/B"}

package/dist/theme/mergeComponents.js

@@ -0,0 +1,56 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Component style-map merging
+ *
+ * One merge rule for component overrides, shared by every layer that composes
+ * them: `extends` inheritance, generated type-scale rules, and the on-media
+ * (`onDark`/`onLight`) surfaces. Merging is per style key, so a child that
+ * restates one property of `button.base` keeps the rest of the base's.
+ *
+ * @input two ComponentStyleMaps — the base and the overrides that win
+ * @output a merged ComponentStyleMap
+ * @position packages/core/src/theme/mergeComponents.ts
+ */
+
+/**
+ * Deep-merge component style maps: `overrides` wins per style key, and every
+ * component and key the base declared that the overrides do not mention is
+ * carried through untouched.
+ */
+export function deepMergeComponents(base, overrides) {
+  if (!base && !overrides) {
+    return undefined;
+  }
+  if (!base) {
+    return overrides;
+  }
+  if (!overrides) {
+    return base;
+  }
+  const result = {};
+
+  // Start with all base entries
+  for (const [component, rules] of Object.entries(base)) {
+    result[component] = {
+      ...rules
+    };
+  }
+
+  // Merge overrides on top
+  for (const [component, rules] of Object.entries(overrides)) {
+    if (!result[component]) {
+      result[component] = {
+        ...rules
+      };
+    } else {
+      for (const [key, styles] of Object.entries(rules)) {
+        result[component][key] = {
+          ...result[component][key],
+          ...styles
+        };
+      }
+    }
+  }
+  return result;
+}

package/dist/theme/onMediaTokens.d.ts

@@ -53,6 +53,11 @@ export declare const defaultOnLightTokens: Record<string, string>;
 /**
  * Resolve on-media overrides: merge user tokens with defaults,
  * pass through component overrides.
+ *
+ * `base` is the already-resolved surface of a theme being extended. It sits
+ * between the defaults and this theme's own input, so a child theme inherits
+ * the surface customizations of the theme it extends instead of silently
+ * reverting them to the defaults.
  */
-export declare function resolveOnMedia(surface: 'dark' | 'light', input?: OnMediaOverrides): ResolvedOnMedia;
+export declare function resolveOnMedia(surface: 'dark' | 'light', input?: OnMediaOverrides, base?: ResolvedOnMedia): ResolvedOnMedia;
 //# sourceMappingURL=onMediaTokens.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"onMediaTokens.d.ts","sourceRoot":"","sources":["../../src/theme/onMediaTokens.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAE,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAC7C,yDAAyD;IACzD,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,yDAAyD;IACzD,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAStD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CASvD,CAAC;AAYF;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,GAAG,OAAO,EACzB,KAAK,CAAC,EAAE,gBAAgB,GACvB,eAAe,CAkBjB"}
+{"version":3,"file":"onMediaTokens.d.ts","sourceRoot":"","sources":["../../src/theme/onMediaTokens.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAE,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAGjE;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAC7C,yDAAyD;IACzD,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,yDAAyD;IACzD,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAStD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CASvD,CAAC;AAYF;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,GAAG,OAAO,EACzB,KAAK,CAAC,EAAE,gBAAgB,EACxB,IAAI,CAAC,EAAE,eAAe,GACrB,eAAe,CAkBjB"}

package/dist/theme/onMediaTokens.js

@@ -20,6 +20,8 @@
  * `onDark`/`onLight` fields in `defineTheme()`.
  */
 
+import { deepMergeComponents } from "./mergeComponents.js";
+
 /**
  * On-media theme overrides — same shape as the main theme but scoped
  * to a surface luminance context.
@@ -71,11 +73,17 @@ function resolveValue(value) {
 /**
  * Resolve on-media overrides: merge user tokens with defaults,
  * pass through component overrides.
+ *
+ * `base` is the already-resolved surface of a theme being extended. It sits
+ * between the defaults and this theme's own input, so a child theme inherits
+ * the surface customizations of the theme it extends instead of silently
+ * reverting them to the defaults.
  */
-export function resolveOnMedia(surface, input) {
+export function resolveOnMedia(surface, input, base) {
   const defaults = surface === 'dark' ? defaultOnDarkTokens : defaultOnLightTokens;
   const tokens = {
-    ...defaults
+    ...defaults,
+    ...base?.tokens
   };
   if (input?.tokens) {
     for (const [key, value] of Object.entries(input.tokens)) {
@@ -86,6 +94,6 @@ export function resolveOnMedia(surface, input) {
   }
   return {
     tokens,
-    components: input?.components
+    components: deepMergeComponents(base?.components, input?.components)
   };
 }

package/dist/utils/characters.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Number of characters in a string — the count a person would give, where one
+ * emoji, flag, or accented letter is one character. Replacement for `.length`
+ * on user-visible strings, which counts internal storage units instead.
+ */
+export declare function characterCount(str: string): number;
+/**
+ * The first character of a string, or '' when empty. Replacement for
+ * `.charAt(0)`, which can return half of an emoji. Reads only the first
+ * character, so cost does not scale with the length of the string.
+ */
+export declare function firstCharacter(str: string): string;
+/**
+ * Truncate to at most `max` characters, ellipsis included: strings within
+ * `max` characters pass through unchanged; longer strings are cut so the
+ * result — content plus `ellipsis` — is exactly `max` characters (or just the
+ * ellipsis, when `max` is smaller than the ellipsis itself). Replacement for
+ * `str.slice(0, n) + '…'`, which can cut an emoji in half.
+ *
+ * @example
+ * ```
+ * truncateCharacters('abcdefghij', 5) // 'abcd…'
+ * truncateCharacters('abcdefghij', 8, '...') // 'abcde...'
+ * ```
+ */
+export declare function truncateCharacters(str: string, max: number, ellipsis?: string): string;
+//# sourceMappingURL=characters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"characters.d.ts","sourceRoot":"","sources":["../../src/utils/characters.ts"],"names":[],"mappings":"AAqCA;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOlD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,QAAQ,SAAM,GACb,MAAM,CAOR"}

package/dist/utils/characters.js

@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file characters.ts
+ * @input Strings that may contain characters made of several code units
+ *        (emoji, flags, joined emoji sequences, accented letters)
+ * @output Exports characterCount, firstCharacter, truncateCharacters —
+ *         replacements for .length / .charAt(0) / .slice(0, n) that measure
+ *         and cut user-visible strings the way a person reads them
+ * @position Shared utility; consumed by Avatar, TextArea, PowerSearch, Table
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/utils/characters.test.ts
+ * - /packages/core/src/utils/index.ts
+ */
+
+/**
+ * Reuse a single segmenter when the runtime supports Intl.Segmenter.
+ * `grapheme` is the Intl granularity name for a user-perceived character.
+ */
+const characterSegmenter = typeof Intl.Segmenter === 'function' ? new Intl.Segmenter(undefined, {
+  granularity: 'grapheme'
+}) : null;
+
+/**
+ * Split a string into user-perceived characters. The code-point fallback
+ * keeps surrogate pairs intact but may split joined emoji sequences and flag
+ * pairs on runtimes without Intl.Segmenter.
+ */
+function splitCharacters(str) {
+  if (characterSegmenter) {
+    return [...characterSegmenter.segment(str)].map(s => s.segment);
+  }
+  return [...str];
+}
+
+/**
+ * Number of characters in a string — the count a person would give, where one
+ * emoji, flag, or accented letter is one character. Replacement for `.length`
+ * on user-visible strings, which counts internal storage units instead.
+ */
+export function characterCount(str) {
+  if (str === '') {
+    return 0;
+  }
+  return splitCharacters(str).length;
+}
+
+/**
+ * The first character of a string, or '' when empty. Replacement for
+ * `.charAt(0)`, which can return half of an emoji. Reads only the first
+ * character, so cost does not scale with the length of the string.
+ */
+export function firstCharacter(str) {
+  if (characterSegmenter) {
+    const first = characterSegmenter.segment(str)[Symbol.iterator]().next();
+    return first.done ? '' : first.value.segment;
+  }
+  const codePoint = str.codePointAt(0);
+  return codePoint == null ? '' : String.fromCodePoint(codePoint);
+}
+
+/**
+ * Truncate to at most `max` characters, ellipsis included: strings within
+ * `max` characters pass through unchanged; longer strings are cut so the
+ * result — content plus `ellipsis` — is exactly `max` characters (or just the
+ * ellipsis, when `max` is smaller than the ellipsis itself). Replacement for
+ * `str.slice(0, n) + '…'`, which can cut an emoji in half.
+ *
+ * @example
+ * ```
+ * truncateCharacters('abcdefghij', 5) // 'abcd…'
+ * truncateCharacters('abcdefghij', 8, '...') // 'abcde...'
+ * ```
+ */
+export function truncateCharacters(str, max, ellipsis = '…') {
+  const characters = splitCharacters(str);
+  if (characters.length <= max) {
+    return str;
+  }
+  const keep = Math.max(max - characterCount(ellipsis), 0);
+  return characters.slice(0, keep).join('') + ellipsis;
+}

package/dist/utils/index.d.ts

@@ -13,6 +13,7 @@ export { parseISOTime, formatISOTime, formatDisplayTime12h, formatDisplayTime24h
 export type { ISOTimeString, ParsedTime } from './timeParser';
 export { parseStyleKey } from './parseStyleKey';
 export { getKey, type Key, type KeyFallback } from './getKey';
+export { characterCount, firstCharacter, truncateCharacters } from './characters';
 export { mergeProps } from './mergeProps';
 export { mergeRefs } from './mergeRefs';
 export { isFocusDetached } from './focusReturn';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,YAAY,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAEvC,YAAY,EAAC,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAC,MAAM,aAAa,CAAC;AAEhF,OAAO,EACL,cAAc,EACd,SAAS,EACT,QAAQ,EACR,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,8BAA8B,EAC9B,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,wBAAwB,EACxB,8BAA8B,EAC9B,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAC,gBAAgB,EAAC,MAAM,aAAa,CAAC;AAElD,OAAO,EACL,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,WAAW,EACX,aAAa,EACb,SAAS,EACT,UAAU,EACV,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAC,aAAa,EAAE,UAAU,EAAC,MAAM,cAAc,CAAC;AAE5D,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAC,MAAM,EAAE,KAAK,GAAG,EAAE,KAAK,WAAW,EAAC,MAAM,UAAU,CAAC;AAE5D,OAAO,EAAC,UAAU,EAAC,MAAM,cAAc,CAAC;AACxC,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AACtC,OAAO,EAAC,eAAe,EAAC,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAC,UAAU,EAAE,mBAAmB,EAAC,MAAM,cAAc,CAAC;AAC7D,YAAY,EACV,UAAU,EACV,UAAU,EACV,mBAAmB,EACnB,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,OAAO,EAAC,UAAU,EAAE,YAAY,EAAC,MAAM,cAAc,CAAC;AACtD,YAAY,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAC,aAAa,EAAE,eAAe,EAAC,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAC,YAAY,EAAC,MAAM,aAAa,CAAC;AACzC,YAAY,EAAC,SAAS,EAAE,mBAAmB,EAAC,MAAM,aAAa,CAAC;AAEhE,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,SAAS,EACT,WAAW,EACX,UAAU,GACX,MAAM,SAAS,CAAC;AACjB,YAAY,EAAC,IAAI,EAAC,MAAM,SAAS,CAAC;AAElC,OAAO,EAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,gBAAgB,EAAC,MAAM,cAAc,CAAC;AAE3E,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AAItC,OAAO,EAAC,kBAAkB,EAAE,iBAAiB,EAAC,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,YAAY,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAEvC,YAAY,EAAC,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAC,MAAM,aAAa,CAAC;AAEhF,OAAO,EACL,cAAc,EACd,SAAS,EACT,QAAQ,EACR,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,8BAA8B,EAC9B,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,wBAAwB,EACxB,8BAA8B,EAC9B,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAC,gBAAgB,EAAC,MAAM,aAAa,CAAC;AAElD,OAAO,EACL,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,WAAW,EACX,aAAa,EACb,SAAS,EACT,UAAU,EACV,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAC,aAAa,EAAE,UAAU,EAAC,MAAM,cAAc,CAAC;AAE5D,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAC,MAAM,EAAE,KAAK,GAAG,EAAE,KAAK,WAAW,EAAC,MAAM,UAAU,CAAC;AAE5D,OAAO,EAAC,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAC,MAAM,cAAc,CAAC;AAEhF,OAAO,EAAC,UAAU,EAAC,MAAM,cAAc,CAAC;AACxC,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AACtC,OAAO,EAAC,eAAe,EAAC,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAC,UAAU,EAAE,mBAAmB,EAAC,MAAM,cAAc,CAAC;AAC7D,YAAY,EACV,UAAU,EACV,UAAU,EACV,mBAAmB,EACnB,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,OAAO,EAAC,UAAU,EAAE,YAAY,EAAC,MAAM,cAAc,CAAC;AACtD,YAAY,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAC,aAAa,EAAE,eAAe,EAAC,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAC,YAAY,EAAC,MAAM,aAAa,CAAC;AACzC,YAAY,EAAC,SAAS,EAAE,mBAAmB,EAAC,MAAM,aAAa,CAAC;AAEhE,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,SAAS,EACT,WAAW,EACX,UAAU,GACX,MAAM,SAAS,CAAC;AACjB,YAAY,EAAC,IAAI,EAAC,MAAM,SAAS,CAAC;AAElC,OAAO,EAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,gBAAgB,EAAC,MAAM,cAAc,CAAC;AAE3E,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AAItC,OAAO,EAAC,kBAAkB,EAAE,iBAAiB,EAAC,MAAM,uBAAuB,CAAC"}

package/dist/utils/index.js

@@ -12,6 +12,7 @@ export { plainDateCreate, plainDateFromISO, plainDateToISO, plainDateToDate, pla
 export { parseISOTime, formatISOTime, formatDisplayTime12h, formatDisplayTime24h, parseTimeInput, compareTime, isTimeInRange, clampTime, adjustTime, createISOTimeString } from "./timeParser.js";
 export { parseStyleKey } from "./parseStyleKey.js";
 export { getKey } from "./getKey.js";
+export { characterCount, firstCharacter, truncateCharacters } from "./characters.js";
 export { mergeProps } from "./mergeProps.js";
 export { mergeRefs } from "./mergeRefs.js";
 export { isFocusDetached } from "./focusReturn.js";