@astryxdesign/core 0.4.1 → 0.4.2-canary.356d2f9

package/src/theme/defineTheme.ts

@@ -28,6 +28,12 @@
  *   <App />
  * </Theme>
  * ```
+ *
+ * SYNC: `DefineThemeInput` is the theme surface. Adding, removing, or renaming
+ * a field means updating:
+ * - /packages/cli/assets/theme.template.ts (documents every field; the
+ *   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';
@@ -42,6 +48,7 @@ import {
   colorDefaults,
   spacingDefaults,
   sizeDefaults,
+  borderDefaults,
   focusDefaults,
   radiusDefaults,
   shadowDefaults,
@@ -65,6 +72,7 @@ import type {DomainTokenName} from './domainTokens';
 import {domainTokenDefaults} from './domainTokens';
 import type {SyntaxThemeDefinition} from './syntax';
 import {registerTheme} from './themeRegistry';
+import {deepMergeComponents} from './mergeComponents';
 
 // =============================================================================
 // Types
@@ -75,6 +83,7 @@ export type CoreTokenName =
   | keyof typeof colorDefaults
   | keyof typeof spacingDefaults
   | keyof typeof sizeDefaults
+  | keyof typeof borderDefaults
   | keyof typeof focusDefaults
   | keyof typeof radiusDefaults
   | keyof typeof shadowDefaults
@@ -157,9 +166,14 @@ export interface DefineThemeInput {
   name: string;
 
   /**
-   * Base theme to extend. When provided, the new theme starts with the
-   * base theme's tokens, components, and fonts, then applies overrides
-   * from this input on top. The base theme's values have lowest precedence.
+   * Base theme to extend. When provided, the new theme starts with everything
+   * the base resolved to — tokens, component overrides, icons, indicators, and
+   * its `onDark`/`onLight` surfaces — then applies this input on top. The base
+   * theme's values have lowest precedence.
+   *
+   * The result is flat: an extended theme carries its inheritance in its own
+   * resolved output, so `astryx theme build` emits one self-contained
+   * stylesheet and the base's CSS does not need to be loaded alongside it.
    *
    * Use this to create variant themes that customize only a few aspects
    * (e.g. icons, accent color) without re-specifying the full theme.
@@ -379,6 +393,7 @@ export const tokenDefaults: Record<string, string> = {
   ...colorDefaults,
   ...spacingDefaults,
   ...sizeDefaults,
+  ...borderDefaults,
   ...focusDefaults,
   ...radiusDefaults,
   ...shadowDefaults,
@@ -407,49 +422,6 @@ function resolveTokenValue(value: TokenValue): string {
   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?: ComponentStyleMap,
-  overrides?: ComponentStyleMap,
-): ComponentStyleMap | undefined {
-  if (!base && !overrides) {
-    return undefined;
-  }
-  if (!base) {
-    return overrides;
-  }
-  if (!overrides) {
-    return base;
-  }
-
-  const result: ComponentStyleMap = {};
-
-  // 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.
@@ -482,6 +454,24 @@ function buildFontFamily(
   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: unknown): string {
+  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.
  *
@@ -495,7 +485,19 @@ function buildFontFamily(
 export function defineTheme(input: DefineThemeInput): DefinedTheme {
   const tokens: Record<string, string> = {};
 
-  // 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)) {
@@ -631,9 +633,10 @@ export function defineTheme(input: DefineThemeInput): DefinedTheme {
     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 =
@@ -654,7 +657,10 @@ export function defineTheme(input: DefineThemeInput): DefinedTheme {
     components,
     icons,
     indicators,
-    __inputTokens: input.tokens,
+    __inputTokens:
+      base?.__inputTokens || input.tokens
+        ? {...base?.__inputTokens, ...input.tokens}
+        : undefined,
     __onDark,
     __onLight,
   };

package/src/theme/derivedVarRegistry.test.ts

@@ -10,6 +10,21 @@
  * 2. Doc check: verifies each var is documented in the doc file's vars[]
  * 3. Registry check: verifies themeable vars have derived[] entries that
  *    match the registry
+ *
+ * Layers 1 and 3 each used to carry a hole that let real vars through:
+ *
+ * - The source scan skipped every `--_*` name outright, on the theory that a
+ *   private var is "internal, not themeable". It is internal, but it is still
+ *   documented — `theming.vars[]` takes `private: true` for exactly this
+ *   (`--_card-radius`, `--_dropdown-menu-padding`), and the derived-var
+ *   pipeline is what theme authors reach it through. Skipping the prefix meant
+ *   10 private vars across 12 (component, var) sites were declared in source
+ *   and documented nowhere.
+ * - Layer 3 narrowed its verdict to vars matching `/radius|padding/`, so any
+ *   var whose name did not happen to contain those two words was exempt from
+ *   ever needing a derived[] mapping. That is now an explicit allowlist
+ *   (VARS_WITHOUT_DERIVED_MAPPING) instead of a name heuristic: a new var must
+ *   be given a derived[] entry or be added to the list on purpose.
  */
 
 import {describe, it, expect} from 'vitest';
@@ -75,7 +90,13 @@ const STRUCTURAL_VARS = new Set([
 /**
  * Extract component-specific CSS custom property names from a source file.
  * Matches patterns like '--_card-radius': or '--_chat-composer-padding':
- * Excludes structural/runtime vars and standard token vars (--color-*, --spacing-*, etc.).
+ * Excludes structural/runtime vars and standard token vars (--color-*,
+ * --spacing-*, etc.).
+ *
+ * Private (`--_*`) vars are INCLUDED. They are internal in the sense that a
+ * theme author does not set them directly, but they are still part of the
+ * documented theming surface (`theming.vars[]` with `private: true`) and are
+ * how derived[] entries connect a standard CSS property to a component.
  */
 function extractComponentVars(filePath: string): string[] {
   const content = readFileSync(filePath, 'utf-8');
@@ -101,10 +122,6 @@ function extractComponentVars(filePath: string): string[] {
     if (/^--(container-|layout-|edge-|component-)/.test(varName)) {
       continue;
     }
-    // Skip private vars (--_ prefix = internal, not themeable)
-    if (varName.startsWith('--_')) {
-      continue;
-    }
     vars.add(varName);
   }
   return [...vars];
@@ -190,6 +207,7 @@ const DIR_TO_REGISTRY_KEY: Record<string, string> = {
   Button: 'button',
   Card: 'card',
   Chat: 'chat',
+  ContextMenu: 'context-menu',
   Dialog: 'dialog',
   DropdownMenu: 'dropdown-menu',
   Field: 'field',
@@ -213,8 +231,55 @@ const CROSS_COMPONENT_VARS: Record<string, string[]> = {
   Carousel: ['--_button-radius'],
   Thumbnail: ['--_button-radius'],
   Chat: ['--_button-radius'],
+  // AvatarGroupOverflow sets the overlap for the Avatars it lays out; Avatar
+  // owns and documents it (and sets it itself when it is the group root).
+  AvatarGroup: ['--_avatar-group-overlap'],
+  // BreadcrumbItem tunes the DropdownMenu it opens.
+  Breadcrumbs: ['--_dropdown-menu-radius', '--_dropdown-menu-padding'],
+  // SelectableCard draws its selection ring through the Card shadow slot.
+  SelectableCard: ['--_card-ring'],
+  // Toolbar offsets the TabList indicator it hosts.
+  Toolbar: ['--_tab-indicator-bottom'],
+  // The destructive item variant recolors the Item it renders; Item owns,
+  // documents and reads both slots.
+  DropdownMenu: ['--_item-label-color', '--_item-description-color'],
 };
 
+/**
+ * Documented vars that intentionally have NO derived[] entry — a theme author
+ * cannot reach them by writing a standard CSS property, only by targeting the
+ * component's own theming surface.
+ *
+ * This replaces a `/radius|padding/` name test that exempted every var whose
+ * name did not contain those words. Each entry is a deliberate classification,
+ * so a NEW var has to be argued into the list rather than slipping past on its
+ * name. The list should shrink over time, not grow.
+ */
+const VARS_WITHOUT_DERIVED_MAPPING = new Set([
+  // No standard CSS property maps onto these — they are component behaviors.
+  '--button-focus-offset',
+  '--button-icon-only-aspect',
+  '--_avatar-group-overlap',
+  '--_codeblock-gutter-width',
+  '--_tab-indicator-bottom',
+  // Hit-area outset on a ::after overlay — `inset` on a pseudo-element is not
+  // a property a theme author sets on the component.
+  '--_thumbnail-hit-inset',
+  // Indentation and row-spacing metrics: --tree-list-indent is the authorable
+  // step, --_tree-indent the per-row distance TreeListItem computes from it.
+  // --tree-list-row-gap is applied as half a padding-block on each row wrapper,
+  // not as gap on the list, so no standard property on the tree-list target
+  // maps onto it; a theme sets the var directly.
+  '--tree-list-indent',
+  '--_tree-indent',
+  '--tree-list-row-gap',
+  // Composed into a single box-shadow list on the card, so neither maps 1:1
+  // onto boxShadow — setting one through a derived entry would clobber the
+  // other.
+  '--_card-elevation',
+  '--_card-ring',
+]);
+
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
@@ -262,19 +327,20 @@ describe('component CSS vars are documented and themeable', () => {
         return true;
       });
 
-      // Filter to only vars that look like they map to CSS properties
-      // (radius → borderRadius, padding → padding). Vars like
-      // --button-press-scale or --button-disabled-opacity are
-      // component-specific behaviors, not standard CSS property mappings.
-      const themeableVars = missingDerived.filter(v =>
-        /radius|padding/.test(v),
+      // Everything that is not explicitly classified as unmappable must have
+      // a derived[] entry. (This was a `/radius|padding/` name test, which
+      // exempted any var whose name lacked those words.)
+      const themeableVars = missingDerived.filter(
+        v => !VARS_WITHOUT_DERIVED_MAPPING.has(v),
       );
 
       expect(
         themeableVars,
         `${dir} has vars that should be themeable via derived[]: ${themeableVars.join(', ')}. ` +
           `Add derived[] entries in ${dir}.doc.mjs mapping standard CSS ` +
-          `properties (borderRadius, padding) to these internal vars.`,
+          `properties (borderRadius, padding) to these internal vars — or, if ` +
+          `no standard property maps onto them, add them to ` +
+          `VARS_WITHOUT_DERIVED_MAPPING with the reason.`,
       ).toEqual([]);
     });
   }

package/src/theme/derivedVarRegistry.ts

@@ -57,6 +57,10 @@ export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
     {property: 'borderRadius', vars: ['--_dialog-radius']},
     {property: 'padding', expand: 'container'},
   ],
+  'context-menu': [
+    {property: 'borderRadius', vars: ['--_dropdown-menu-radius']},
+    {property: 'padding', vars: ['--_dropdown-menu-padding']},
+  ],
   'dropdown-menu': [
     {property: 'borderRadius', vars: ['--_dropdown-menu-radius']},
     {property: 'padding', vars: ['--_dropdown-menu-padding']},

package/src/theme/expandColorScale.ts

@@ -28,6 +28,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/theme/defineTheme.ts
+ * - /packages/cli/assets/theme.template.ts (the annotated field reference)
  */
 
 import {contrastRatio} from './contrast';

package/src/theme/expandMotionScale.ts

@@ -18,6 +18,7 @@
  * SYNC: When modified, update:
  * - /packages/core/src/theme/expandMotionScale.test.ts
  * - /packages/core/src/theme/defineTheme.ts
+ * - /packages/cli/assets/theme.template.ts (the annotated field reference)
  */
 
 // =============================================================================

package/src/theme/expandRadiusScale.ts

@@ -22,6 +22,7 @@
  * SYNC: When modified, update:
  * - /packages/core/src/theme/expandRadiusScale.test.ts
  * - /packages/core/src/theme/defineTheme.ts
+ * - /packages/cli/assets/theme.template.ts (the annotated field reference)
  */
 
 // =============================================================================

package/src/theme/expandTypeScale.ts

@@ -44,6 +44,7 @@
  * SYNC: When modified, update:
  * - /packages/core/src/theme/expandTypeScale.test.ts
  * - /packages/core/src/theme/defineTheme.ts
+ * - /packages/cli/assets/theme.template.ts (the annotated field reference)
  */
 
 // =============================================================================

package/src/theme/mergeComponents.ts

@@ -0,0 +1,59 @@
+// 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
+ */
+
+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 function deepMergeComponents(
+  base?: ComponentStyleMap,
+  overrides?: ComponentStyleMap,
+): ComponentStyleMap | undefined {
+  if (!base && !overrides) {
+    return undefined;
+  }
+  if (!base) {
+    return overrides;
+  }
+  if (!overrides) {
+    return base;
+  }
+
+  const result: ComponentStyleMap = {};
+
+  // 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/src/theme/onMediaTokens.ts

@@ -21,6 +21,7 @@
  */
 
 import type {TokenValue, ComponentStyleMap} from './defineTheme';
+import {deepMergeComponents} from './mergeComponents';
 
 /**
  * On-media theme overrides — same shape as the main theme but scoped
@@ -89,15 +90,21 @@ function resolveValue(value: TokenValue): 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 function resolveOnMedia(
   surface: 'dark' | 'light',
   input?: OnMediaOverrides,
+  base?: ResolvedOnMedia,
 ): ResolvedOnMedia {
   const defaults =
     surface === 'dark' ? defaultOnDarkTokens : defaultOnLightTokens;
 
-  const tokens = {...defaults};
+  const tokens = {...defaults, ...base?.tokens};
 
   if (input?.tokens) {
     for (const [key, value] of Object.entries(input.tokens)) {
@@ -109,6 +116,6 @@ export function resolveOnMedia(
 
   return {
     tokens,
-    components: input?.components,
+    components: deepMergeComponents(base?.components, input?.components),
   };
 }