@astryxdesign/core 0.6.0 → 0.6.1

package/src/theme/defineTheme.test.ts

@@ -80,40 +80,34 @@ describe('defineTheme', () => {
     warn.mockRestore();
   });
 
-  it('keeps explicitly enrolled local tokens separate and emits their exact names', () => {
-    const theme = defineTheme({
-      name: 'ocean-theme',
-      localTokens: {
-        '--astryx-theme-ocean-theme-color-status-fill-accent': [
-          '#0077b6',
-          '#48cae4',
-        ],
-      },
-      components: {
-        badge: {
-          'variant:info': {
-            backgroundColor:
-              'var(--astryx-theme-ocean-theme-color-status-fill-accent)',
+  it.each([
+    ['ocean-theme', '--ac-selection-ink'],
+    ['Theme.Owner', '--'],
+    ['ocean-theme', '--astryx-theme-ocean-theme-color-status-fill-accent'],
+  ])(
+    'accepts valid local token name %s / %s and preserves its exact bytes',
+    (themeName, token) => {
+      const theme = defineTheme({
+        name: themeName,
+        localTokens: {[token]: ['#0077b6', '#48cae4']},
+        components: {
+          badge: {
+            'variant:info': {backgroundColor: `var(${token})`},
           },
         },
-      },
-    });
-
-    expect(theme.tokens).not.toHaveProperty(
-      '--astryx-theme-ocean-theme-color-status-fill-accent',
-    );
-    expect(theme.localTokens).toEqual({
-      '--astryx-theme-ocean-theme-color-status-fill-accent':
-        'light-dark(#0077b6, #48cae4)',
-    });
-    expect(theme.__localTokenOwners).toEqual({
-      '--astryx-theme-ocean-theme-color-status-fill-accent': 'ocean-theme',
-    });
-    expect(theme.__localTokenLineage).toEqual(['ocean-theme']);
-    expect(generateThemeTestCSS(theme)).toContain(
-      '--astryx-theme-ocean-theme-color-status-fill-accent: light-dark(#0077b6, #48cae4);',
-    );
-  });
+      });
+
+      expect(theme.tokens).not.toHaveProperty(token);
+      expect(theme.localTokens).toEqual({
+        [token]: 'light-dark(#0077b6, #48cae4)',
+      });
+      expect(theme.__localTokenOwners).toEqual({[token]: themeName});
+      expect(theme.__localTokenLineage).toEqual([themeName]);
+      expect(generateThemeTestCSS(theme)).toContain(
+        `${token}: light-dark(#0077b6, #48cae4);`,
+      );
+    },
+  );
 
   it('rejects a name declared in both tokens and localTokens before CSS and token helpers can disagree', () => {
     const token = '--astryx-theme-ocean-theme-color-status-fill-accent';
@@ -142,9 +136,16 @@ describe('defineTheme', () => {
         },
       }),
     ).toThrow(/both tokens and localTokens/);
+
+    expect(() =>
+      defineTheme({
+        name: 'ocean-theme',
+        localTokens: {'--color-accent': '#48cae4'},
+      }),
+    ).toThrow(/both tokens and localTokens/);
   });
 
-  it('does not reinterpret legacy reserved-prefix references without enrollment', () => {
+  it('does not reinterpret unenrolled custom-property references', () => {
     const theme = defineTheme({
       name: 'legacy',
       tokens: {
@@ -164,65 +165,43 @@ describe('defineTheme', () => {
     expect(theme).not.toHaveProperty('__localTokenLineage');
   });
 
-  it.each([
-    ['Uppercase', '--astryx-theme-Uppercase-color-accent'],
-    ['wrong-space', '--astryx-theme-other-color-accent'],
-    ['wrong-space', '--astryx-theme-wrong-space-Color-accent'],
-  ])('rejects malformed local token enrollment for %s', (name, token) => {
+  it('rejects an invalid CSS custom-property name', () => {
     expect(() =>
       defineTheme({
-        name,
-        localTokens: {[token]: '#123456'},
+        name: 'ocean',
+        localTokens: {'selection-ink': '#123456'},
       }),
-    ).toThrow(/localTokens|local token/);
+    ).toThrow(/valid CSS custom-property name/);
   });
 
-  it.each(['VAR', 'vAr'])(
-    'rejects undeclared local references using %s() in nested and media component rules',
-    functionName => {
-      expect(() =>
-        defineTheme({
-          name: 'ocean',
-          localTokens: {},
-          components: {
-            button: {
-              base: {
-                ':hover': {
-                  color: `${functionName}(--astryx-theme-ocean-color-missing)`,
-                },
-              },
-            },
-          },
-        }),
-      ).toThrow(/has no declaration/);
-
-      expect(() =>
-        defineTheme({
-          name: 'ocean',
-          localTokens: {},
-          onDark: {
-            components: {
-              badge: {
-                base: {
-                  color: `${functionName}(--astryx-theme-ocean-color-missing)`,
-                },
-              },
+  it('treats case-only and unrelated custom-property references as external', () => {
+    expect(() =>
+      defineTheme({
+        name: 'ocean',
+        localTokens: {'--Selection-Ink': '#123456'},
+        components: {
+          button: {
+            base: {
+              color: 'var(--selection-ink)',
+              backgroundColor: 'var(--product-surface)',
             },
           },
-        }),
-      ).toThrow(/has no declaration/);
-    },
-  );
+        },
+      }),
+    ).not.toThrow();
+  });
 
   it.each(['VAR', 'vAr'])(
     'rejects cycles between local tokens using %s()',
     functionName => {
+      const escaped = '--\\66 oo';
+      const other = '--astryx-theme-cycle-color-b';
       expect(() =>
         defineTheme({
           name: 'cycle',
           localTokens: {
-            '--astryx-theme-cycle-color-a': `${functionName}(--astryx-theme-cycle-color-b)`,
-            '--astryx-theme-cycle-color-b': `${functionName}(--astryx-theme-cycle-color-a)`,
+            [escaped]: `${functionName}(${other})`,
+            [other]: `${functionName}(${escaped})`,
           },
         }),
       ).toThrow(/cycle detected/);
@@ -1178,28 +1157,28 @@ describe('container padding mapping', () => {
 
 describe('defineTheme extends', () => {
   it('inherits enrollment, allows exact replacement, and owns new child names', () => {
+    const inherited = '--astryx-theme-base-theme-color-status-fill';
+    const childOwned = '--child-surface-raised';
     const base = defineTheme({
       name: 'base-theme',
-      localTokens: {
-        '--astryx-theme-base-theme-color-status-fill': '#123456',
-      },
+      localTokens: {[inherited]: '#123456'},
     });
     const child = defineTheme({
       name: 'child-theme',
       extends: base,
       localTokens: {
-        '--astryx-theme-base-theme-color-status-fill': '#654321',
-        '--astryx-theme-child-theme-color-surface-raised': '#abcdef',
+        [inherited]: '#654321',
+        [childOwned]: '#abcdef',
       },
     });
 
     expect(child.localTokens).toEqual({
-      '--astryx-theme-base-theme-color-status-fill': '#654321',
-      '--astryx-theme-child-theme-color-surface-raised': '#abcdef',
+      [inherited]: '#654321',
+      [childOwned]: '#abcdef',
     });
     expect(child.__localTokenOwners).toEqual({
-      '--astryx-theme-base-theme-color-status-fill': 'base-theme',
-      '--astryx-theme-child-theme-color-surface-raised': 'child-theme',
+      [inherited]: 'base-theme',
+      [childOwned]: 'child-theme',
     });
     expect(child.__localTokenLineage).toEqual(['base-theme', 'child-theme']);
   });
@@ -1235,25 +1214,6 @@ describe('defineTheme extends', () => {
     ]);
   });
 
-  it('rejects a new declaration in another theme namespace', () => {
-    const base = defineTheme({
-      name: 'base-theme',
-      localTokens: {
-        '--astryx-theme-base-theme-color-status-fill': '#123456',
-      },
-    });
-
-    expect(() =>
-      defineTheme({
-        name: 'child-theme',
-        extends: base,
-        localTokens: {
-          '--astryx-theme-base-theme-color-new-role': '#abcdef',
-        },
-      }),
-    ).toThrow(/exact namespace/);
-  });
-
   it('inherits tokens from base theme', () => {
     const base = defineTheme({
       name: 'base',

package/src/theme/defineTheme.ts

@@ -308,12 +308,8 @@ export interface DefineThemeInput {
    *  Values can be a string or [light, dark] tuple.
    *  Only include tokens you want to override; defaults fill the rest. */
   tokens?: Partial<Record<TokenName, TokenValue>>;
-  /**
-   * Theme-family-local CSS custom properties. Keys use the complete
-   * `--astryx-theme-${name}-...` spelling and values follow `TokenValue`.
-   * These names are available only to this enrolled theme lineage and do not
-   * become portable `TokenName` values.
-   */
+  /** Theme-family-local values keyed by any valid CSS custom-property name;
+   *  prefixes do not establish ownership. */
   localTokens?: Record<string, TokenValue>;
   /**
    * Component style overrides — keyed by component name (lowercase).
@@ -581,9 +577,7 @@ export function defineTheme(input: DefineThemeInput): ResolvedDefinedTheme {
     input,
     base,
     tokens,
-    components,
-    __onDark,
-    __onLight,
+    tokenDefaults,
   );
 
   // Adaptations inherit their breakpoint map and ordered rules. Every rule is

package/src/theme/derivedVarRegistry.ts

@@ -98,7 +98,7 @@ export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
  * 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.
+ * nothing. Keep these aliases aligned with the emitted compatibility classes.
  */
 const DEPRECATED_REGISTRY_KEYS: Record<string, string> = {
   hovercard: 'hover-card',

package/src/theme/localTokens.ts

@@ -3,23 +3,22 @@
 /**
  * @file localTokens.ts
  * @input Root and adaptation theme-local token declarations and references
- * @output Validated enrollment metadata plus normalized conditional writes
- * @position Theme-local namespace owner; final adaptation-cycle validation is
+ * @output Validated exact-name ownership metadata plus normalized conditional writes
+ * @position Theme-local ownership boundary; final adaptation-cycle validation is
  *   performed after the reachable ordered cascade is assembled.
  */
 
-import type {ComponentStyleMap, DefinedTheme, TokenValue} from './defineTheme';
-import type {ResolvedOnMedia} from './onMediaTokens';
+import type {DefinedTheme, TokenValue} from './defineTheme';
 
-const LOCAL_TOKEN_PREFIX = '--astryx-theme-';
-const THEME_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
-const LOCAL_TOKEN_SUFFIX_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-const CSS_VAR_PATTERN = /var\(\s*(--[^,\s)]+)/gi;
-
-/** Whether a custom-property name belongs to Astryx's reserved local namespace. */
-export function isReservedThemeLocalTokenName(name: string): boolean {
-  return name.startsWith(LOCAL_TOKEN_PREFIX);
-}
+const CSS_NAME_CHARACTER = String.raw`(?:[-_a-zA-Z0-9]|\P{ASCII}|\\(?:[0-9a-fA-F]{1,6}[ \t\r\n\f]?|[^\r\n\f]))`;
+const CSS_CUSTOM_PROPERTY_NAME_PATTERN = new RegExp(
+  `^--${CSS_NAME_CHARACTER}*$`,
+  'u',
+);
+const CSS_VAR_PATTERN = new RegExp(
+  `var\\(\\s*(--${CSS_NAME_CHARACTER}*)(?=\\s*(?:,|\\)))`,
+  'giu',
+);
 
 export interface ResolvedLocalTokenContract {
   localTokens: Record<string, string>;
@@ -31,12 +30,8 @@ function hasOwn(object: object, key: PropertyKey): boolean {
   return Object.prototype.hasOwnProperty.call(object, key);
 }
 
-function isExactLocalTokenName(name: string, owner: string): boolean {
-  const prefix = `${LOCAL_TOKEN_PREFIX}${owner}-`;
-  return (
-    name.startsWith(prefix) &&
-    LOCAL_TOKEN_SUFFIX_PATTERN.test(name.slice(prefix.length))
-  );
+function isValidCSSCustomPropertyName(name: string): boolean {
+  return !name.includes('\0') && CSS_CUSTOM_PROPERTY_NAME_PATTERN.test(name);
 }
 
 function resolveTokenValue(value: TokenValue, path: string): string {
@@ -84,16 +79,6 @@ function collectCustomPropertyReferences(
   }
 }
 
-function collectLocalReferences(value: unknown, refs: Set<string>): void {
-  const customProperties = new Set<string>();
-  collectCustomPropertyReferences(value, customProperties);
-  for (const name of customProperties) {
-    if (isReservedThemeLocalTokenName(name)) {
-      refs.add(name);
-    }
-  }
-}
-
 export function assertNoTokenCycles(
   tokenValues: Record<string, string>,
   context?: string,
@@ -208,27 +193,6 @@ export function assertNoTokenCycles(
   }
 }
 
-function assertDeclaredReferences(
-  localTokens: Record<string, string>,
-  components: ComponentStyleMap | undefined,
-  onDark: ResolvedOnMedia | undefined,
-  onLight: ResolvedOnMedia | undefined,
-): void {
-  const refs = new Set<string>();
-  collectLocalReferences(localTokens, refs);
-  collectLocalReferences(components, refs);
-  collectLocalReferences(onDark?.components, refs);
-  collectLocalReferences(onLight?.components, refs);
-
-  for (const reference of refs) {
-    if (!hasOwn(localTokens, reference)) {
-      throw new Error(
-        `Theme-local token reference "${reference}" has no declaration in the enrolled theme lineage.`,
-      );
-    }
-  }
-}
-
 function assertInheritedContract(
   themeName: string,
   base: DefinedTheme,
@@ -267,7 +231,7 @@ function assertInheritedContract(
       typeof value !== 'string' ||
       !owner ||
       !lineage.includes(owner) ||
-      !isExactLocalTokenName(name, owner)
+      !isValidCSSCustomPropertyName(name)
     ) {
       throw new Error(
         `defineTheme("${themeName}"): inherited local token "${name}" does not match its exact lineage metadata.`,
@@ -287,7 +251,7 @@ function assertInheritedContract(
  * Resolve and validate the opt-in theme-local token contract.
  *
  * Themes that omit `localTokens` and do not extend an enrolled base bypass this
- * function's reserved-namespace checks so legacy token behavior stays intact.
+ * function's exact owner and lineage checks so legacy token behavior stays intact.
  */
 export function resolveLocalTokenContract(
   input: {
@@ -296,9 +260,7 @@ export function resolveLocalTokenContract(
   },
   base: DefinedTheme | undefined,
   tokens: Record<string, string>,
-  components: ComponentStyleMap | undefined,
-  onDark: ResolvedOnMedia | undefined,
-  onLight: ResolvedOnMedia | undefined,
+  portableTokens: Readonly<Record<string, string>>,
 ): ResolvedLocalTokenContract | undefined {
   const directlyEnrolled = hasOwn(input, 'localTokens');
   const inherited = base?.__localTokenLineage !== undefined;
@@ -307,12 +269,6 @@ export function resolveLocalTokenContract(
     return undefined;
   }
 
-  if (directlyEnrolled && !THEME_NAME_PATTERN.test(input.name)) {
-    throw new Error(
-      `defineTheme("${input.name}"): themes using localTokens require a stable lower-kebab name.`,
-    );
-  }
-
   if (inherited && base) {
     assertInheritedContract(input.name, base);
   }
@@ -335,13 +291,12 @@ export function resolveLocalTokenContract(
 
   for (const [name, value] of Object.entries(declarations ?? {})) {
     const inheritedOwner = owners[name];
+    if (!isValidCSSCustomPropertyName(name)) {
+      throw new Error(
+        `defineTheme("${input.name}"): local token "${name}" must be a valid CSS custom-property name.`,
+      );
+    }
     if (!inheritedOwner) {
-      const expectedPrefix = `${LOCAL_TOKEN_PREFIX}${input.name}-`;
-      if (!isExactLocalTokenName(name, input.name)) {
-        throw new Error(
-          `defineTheme("${input.name}"): local token "${name}" must use the exact namespace "${expectedPrefix}" followed by a lowercase kebab-case purpose.`,
-        );
-      }
       owners[name] = input.name;
     }
     localTokens[name] = resolveTokenValue(
@@ -356,14 +311,13 @@ export function resolveLocalTokenContract(
         `defineTheme("${input.name}"): inherited local token "${name}" has no owner metadata.`,
       );
     }
-    if (hasOwn(tokens, name)) {
+    if (hasOwn(tokens, name) || hasOwn(portableTokens, name)) {
       throw new Error(
         `defineTheme("${input.name}"): token "${name}" cannot be declared in both tokens and localTokens.`,
       );
     }
   }
 
-  assertDeclaredReferences(localTokens, components, onDark, onLight);
   assertNoTokenCycles(localTokens, `defineTheme("${input.name}").localTokens`);
 
   return {
@@ -377,29 +331,17 @@ export function resolveLocalTokenContract(
  * Resolve theme-local values written by one adaptation rule.
  *
  * Adaptations may replace names already enrolled by the root theme lineage, but
- * they never enroll names of their own. This validates one rule's references;
- * cycle validation waits until all co-matching writes have cascaded in order.
+ * they never enroll names of their own. Cycle validation waits until all
+ * co-matching writes have cascaded in order.
  */
 export function resolveAdaptationLocalTokens(
   themeName: string,
   ruleIndex: number,
   declarations: Record<string, TokenValue> | undefined,
   rootLocalTokens: Record<string, string> | undefined,
-  tokens: Record<string, string>,
-  components: ComponentStyleMap | undefined,
 ): Record<string, string> | undefined {
   const path = `defineTheme("${themeName}").adaptations.rules[${ruleIndex}].value.localTokens`;
   if (declarations === undefined) {
-    const refs = new Set<string>();
-    collectLocalReferences(tokens, refs);
-    collectLocalReferences(components, refs);
-    for (const reference of refs) {
-      if (!rootLocalTokens || !hasOwn(rootLocalTokens, reference)) {
-        throw new Error(
-          `${path}: theme-local token reference "${reference}" has no declaration in the enrolled root theme lineage.`,
-        );
-      }
-    }
     return undefined;
   }
   if (
@@ -420,18 +362,5 @@ export function resolveAdaptationLocalTokens(
     resolved[name] = resolveTokenValue(value, `${path}["${name}"]`);
   }
 
-  const effective = {...rootLocalTokens, ...resolved};
-  const refs = new Set<string>();
-  collectLocalReferences(resolved, refs);
-  collectLocalReferences(tokens, refs);
-  collectLocalReferences(components, refs);
-  for (const reference of refs) {
-    if (!hasOwn(effective, reference)) {
-      throw new Error(
-        `${path}: theme-local token reference "${reference}" has no declaration in the enrolled root theme lineage.`,
-      );
-    }
-  }
-
   return Object.keys(resolved).length > 0 ? resolved : undefined;
 }

package/src/theme/publicThemeHelperContract.test.ts

@@ -29,9 +29,9 @@ const theme = defineTheme({
 const selector = '.astryx-button[data-variant="primary"]';
 
 describe('public theme helper selector contract', () => {
-  it('keeps themeProps shape while removing bare value classes', () => {
+  it('keeps canonical data attributes alongside bare compatibility classes', () => {
     expect(themeProps('button', {variant: 'primary', size: 'sm'})).toEqual({
-      className: 'astryx-button',
+      className: 'astryx-button primary sm',
       'data-variant': 'primary',
       'data-size': 'sm',
     });

package/src/theme/themeAdaptations.test.ts

@@ -443,50 +443,24 @@ describe('theme-local adaptation values', () => {
     ).toThrow(/write it through value.localTokens/);
   });
 
-  it('rejects reserved local-token names through value.tokens even when unenrolled', () => {
-    expect(() =>
-      defineTheme({
-        name: 'reserved-rule-token',
-        adaptations: {
-          rules: [
-            {
-              when: {pointer: 'coarse'},
-              value: {
-                tokens: {
-                  '--astryx-theme-unrelated-owner-control-height': '44px',
-                },
-              },
-            },
-          ],
-        },
-      } as unknown as DefineThemeInput),
-    ).toThrow(/reserved.*value\.localTokens/i);
-  });
+  it('treats an unenrolled prefix-like adaptation token as portable', () => {
+    const name = '--astryx-theme-unrelated-owner-control-height';
+    const theme = defineTheme({
+      name: 'external-rule-token',
+      adaptations: {
+        rules: [
+          {
+            when: {pointer: 'coarse'},
+            value: {tokens: {[name]: '44px'}},
+          },
+        ],
+      },
+    } as unknown as DefineThemeInput);
 
-  it('rejects undeclared references and conditional cycles', () => {
-    expect(() =>
-      defineTheme({
-        name: 'local-root',
-        localTokens: {[localName]: '32px'},
-        adaptations: {
-          rules: [
-            {
-              when: {pointer: 'coarse'},
-              value: {
-                components: {
-                  button: {
-                    base: {
-                      minHeight: 'var(--astryx-theme-local-root-missing-name)',
-                    },
-                  },
-                },
-              },
-            },
-          ],
-        },
-      }),
-    ).toThrow(/has no declaration/);
+    expect(theme.__adaptationRules?.[0].tokens[name]).toBe('44px');
+  });
 
+  it('rejects conditional local-token cycles', () => {
     const a = '--astryx-theme-cycle-local-a';
     const b = '--astryx-theme-cycle-local-b';
     expect(() =>

package/src/theme/themeAdaptations.ts

@@ -27,11 +27,7 @@ import type {MotionScaleConfig} from './expandMotionScale';
 import type {RadiusScaleConfig} from './expandRadiusScale';
 import type {ColorScaleConfig} from './expandColorScale';
 import {resolveThemeValues, type ThemeValuesInput} from './resolveThemeValues';
-import {
-  assertNoTokenCycles,
-  isReservedThemeLocalTokenName,
-  resolveAdaptationLocalTokens,
-} from './localTokens';
+import {assertNoTokenCycles, resolveAdaptationLocalTokens} from './localTokens';
 
 // =============================================================================
 // Public authoring vocabulary
@@ -928,9 +924,12 @@ export function resolveThemeAdaptationRules(
     }
 
     for (const name of Object.keys(rule.value.tokens ?? {})) {
-      if (isReservedThemeLocalTokenName(name)) {
+      if (
+        rootLocalTokens &&
+        Object.prototype.hasOwnProperty.call(rootLocalTokens, name)
+      ) {
         throw new Error(
-          `defineTheme("${themeName}").adaptations.rules[${index}].value.tokens["${name}"] uses the reserved --astryx-theme-* namespace; write it through value.localTokens instead.`,
+          `defineTheme("${themeName}").adaptations.rules[${index}].value.tokens["${name}"] matches an enrolled theme-local declaration; write it through value.localTokens instead.`,
         );
       }
     }
@@ -940,8 +939,6 @@ export function resolveThemeAdaptationRules(
       index,
       rule.value.localTokens,
       rootLocalTokens,
-      resolved.tokens,
-      resolved.components,
     );
 
     return {