zyzz 0.0.2 → 0.0.5

package/src/compiler/internal/Contract.ts

@@ -3,14 +3,16 @@
  * @module
  */
 import type * as Binding from '../../internal/Binding.js'
-import * as Config from '../../Config.js'
+import * as Config from '../../internal/Configuration.js'
 import * as Configurations from './Configurations.js'
 import * as FunctionSyntax from '../../internal/FunctionSyntax.js'
 import * as Identifiers from './Identifiers.js'
 import * as PackedStyles from './PackedStyles.js'
 import * as Shorthands from '../../internal/Shorthands.js'
 import * as Stylesheets from './Stylesheets.js'
-import * as Theme from '../../Theme.js'
+import * as Theme from '../../internal/Theme.js'
+import * as VariableSets from '../../internal/VariableSets.js'
+import * as Vars from '../../Vars.js'
 import type * as Themes from './Themes.js'
 import * as Token from '../../internal/Token.js'
 
@@ -24,7 +26,7 @@ export function read(
   if (
     ![
       1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21,
-      22, 23,
+      22, 23, 24, 25, 26, 27,
     ].includes(data.version as number)
   )
     throw new Error('Unsupported Zyzz contract version.')
@@ -56,12 +58,53 @@ export function read(
     for (const entry of Object.values(record(data.exports))) collect(entry)
   }
 
+  function decode(value: unknown): unknown {
+    if (!value || typeof value !== 'object') return value
+    if (Array.isArray(value)) return value.map(decode)
+    const fields = record(value)
+    if (Object.hasOwn(fields, '$object'))
+      return Object.fromEntries(
+        Object.entries(record(fields.$object)).map(([key, value]) => [
+          key,
+          decode(value),
+        ]),
+      )
+    if (Object.hasOwn(fields, '$variable')) {
+      const reference = record(fields.$variable)
+      const identity = string(reference.identity)
+      let contract = identities.get(identity)
+      if (contract && !contract.variableSet)
+        throw new Error(
+          'Conflicting packed variable-set modes for one identity.',
+        )
+      if (!contract) {
+        contract = Object.freeze({
+          variableSet: true,
+          [Token.identity]: identity,
+        })
+        identities.set(identity, contract)
+      }
+      const resolved = decode(reference.value) as Token.Value
+      return Token.create({
+        contract,
+        group: VariableSets.domain(resolved),
+        path: string(reference.path),
+        value: resolved,
+      })
+    }
+    return Object.fromEntries(
+      Object.entries(fields).map(([key, value]) => [key, decode(value)]),
+    )
+  }
   const themes: Record<string, Theme.Definition> = Object.create(null)
   const types: Record<string, string> = Object.create(null)
 
   for (const [name, value] of Object.entries(record(data.themes))) {
     const entry = record(value)
     const identity = string(entry.identity)
+    if (entry.variableSet === true && (data.version as number) < 26)
+      throw new Error('Vars contracts require contract version 26 or later.')
+    const mappings = VariableSets.mappings(entry.mappings)
     if (
       entry.cssOutput !== undefined &&
       entry.cssOutput !== 'atomic' &&
@@ -73,11 +116,28 @@ export function read(
       | 'grouped'
       | undefined
 
+    if (entry.defaultLayer !== undefined) {
+      if ((data.version as number) < 27)
+        throw new Error('Default layers require contract version 27 or later.')
+      Config.create({ defaultLayer: entry.defaultLayer as string })
+    }
+    const defaultLayer = entry.defaultLayer as string | undefined
+
     const shorthands =
       entry.shorthands !== undefined
         ? Shorthands.read(entry.shorthands)
         : undefined
     let contract = identities.get(identity)
+    if (
+      contract &&
+      Boolean(contract.variableSet) !== (entry.variableSet === true)
+    )
+      throw new Error('Conflicting packed variable-set modes for one identity.')
+    if (
+      contract &&
+      JSON.stringify(contract.mappings ?? {}) !== JSON.stringify(mappings ?? {})
+    )
+      throw new Error('Conflicting packed variable mappings for one identity.')
     if (
       contract &&
       Shorthands.signature(contract.shorthands) !==
@@ -95,19 +155,53 @@ export function read(
         'Conflicting packed CSS output modes for one theme identity.',
       )
 
+    if (contract && contract.defaultLayer !== defaultLayer)
+      throw new Error(
+        'Conflicting packed default layers for one theme identity.',
+      )
+
     if (!contract) {
       contract = Object.freeze({
+        ...(entry.variableSet === true
+          ? {
+              variableSet: true,
+              mappings,
+            }
+          : {}),
         ...(entry.shorthands !== undefined
           ? { shorthands: Shorthands.read(entry.shorthands) }
           : {}),
         ...(cssOutput ? { cssOutput } : {}),
+        ...(defaultLayer !== undefined ? { defaultLayer } : {}),
         [Token.complete]: true,
         [Token.identity]: identity,
       })
       identities.set(identity, contract)
     }
 
-    const definition = Theme.define(record(entry.tokens) as Theme.Tokens)
+    const definition =
+      entry.variableSet === true
+        ? VariableSets.theme(
+            Vars.define(decode(entry.tokens) as Vars.Values),
+            mappings,
+          )
+        : Theme.define(record(entry.tokens) as Theme.Tokens)
+    if (
+      (data.version as number) < 24 &&
+      Object.hasOwn(definition.tokens, 'typography')
+    )
+      throw new Error(
+        'Packed typography sets require contract version 24 or later.',
+      )
+
+    if (
+      (data.version as number) < 25 &&
+      (definition[Token.definition].paths ||
+        Object.hasOwn(definition.tokens, 'borderWidth'))
+    )
+      throw new Error(
+        'Packed responsive typography and border widths require contract version 25 or later.',
+      )
 
     themes[name] = Token.bind(definition, contract)
     types[name] = type(input(definition))
@@ -198,9 +292,10 @@ export function read(
       const name = string(entry.name)
       const reference = string(entry.reference)
       if (
-        ![9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23].includes(
-          data.version as number,
-        ) ||
+        ![
+          9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
+          27,
+        ].includes(data.version as number) ||
         ![
           'cssFunction',
           'customMedia',
@@ -247,10 +342,7 @@ export function read(
     }
 
     if (entry.kind === 'style-reference') {
-      if (
-        entry.style !== undefined &&
-        ![16, 17, 18, 19, 20, 21, 22, 23].includes(data.version as number)
-      )
+      if (entry.style !== undefined && (data.version as number) < 16)
         throw new Error(
           'Packed callable styles require contract version 16 or later.',
         )
@@ -324,10 +416,17 @@ export function read(
         : undefined
 
     const options =
-      entry.options === undefined ? undefined : record(entry.options)
+      entry.options === undefined ? undefined : record(decode(entry.options))
 
     if (options) {
-      Config.create(options as Config.create.Options)
+      if (entry.variableConfig === true)
+        Config.create(
+          variableOptions(
+            options,
+            entry.variableMappings as Vars.Mappings | false | undefined,
+          ),
+        )
+      else Config.create(options as Config.create.Options)
       if (
         (data.version as number) >= 17 &&
         (options.cssOutput ?? 'atomic') !==
@@ -337,6 +436,14 @@ export function read(
           'Configuration CSS output disagrees with linked theme metadata.',
         )
 
+      if (
+        options.defaultLayer !==
+        definition[Token.definition].contract.defaultLayer
+      )
+        throw new Error(
+          'Configuration default layer disagrees with linked theme metadata.',
+        )
+
       if (
         Shorthands.signature(options.shorthands) !==
         Shorthands.signature(definition[Token.definition].contract.shorthands)
@@ -350,7 +457,9 @@ export function read(
       !!options?.themes &&
       ((data.version as number) < 4 || entry.catalogOnly === true)
     const fullConfigType = options
-      ? `import('zyzz').Config.create.ReturnType<${Configurations.type(options)}>`
+      ? entry.variableConfig === true
+        ? `import('zyzz').Config.VariableConfig<${Configurations.type(variableOptions(options, entry.variableMappings as Vars.Mappings | false | undefined))}>`
+        : `import('zyzz').Config.create.ReturnType<${Configurations.type(options)}>`
       : ''
     // Helpers a legacy library did not compile are hidden from its consumers' types.
     const hidden = [
@@ -369,6 +478,27 @@ export function read(
     return {
       binding: string(entry.binding),
       call: {
+        ...(entry.variableSet === true
+          ? {
+              variableSet: true,
+              type: `import('zyzz').Vars.Definition<${types[theme]!}>`,
+            }
+          : {}),
+        ...(entry.directVariables === true
+          ? {
+              directVariables: true,
+              type: `import('zyzz').Vars.${entry.variableSet === true ? 'Definition' : 'References'}<${types[theme]!}>`,
+            }
+          : {}),
+        ...(entry.variableConfig === true
+          ? {
+              variableConfig: true,
+              variableMappings: entry.variableMappings as
+                | Vars.Mappings
+                | false
+                | undefined,
+            }
+          : {}),
         ...(entry.recipe === true ? { recipe: true } : {}),
         ...(entry.output === 'html' ? { output: 'html' as const } : {}),
         ...(catalogOnly ? { catalogOnly: true } : {}),
@@ -392,7 +522,7 @@ export function read(
         ...(options
           ? {
               options,
-              type: `${outputType}${entry.initialization === true ? "['script']" : entry.root === true ? "['appearance']" : entry.selection === true ? "['themes']" : ''}`,
+              type: `${outputType}${entry.initialization === true ? "['script']" : entry.root === true ? "['appearance']" : entry.selection === true ? (entry.variableConfig === true ? "['vars']" : "['themes']") : ''}`,
             }
           : {}),
         ...(members
@@ -452,6 +582,7 @@ function tokens(tree: Theme.References<Theme.Tokens>): Record<string, unknown> {
 }
 
 function type(value: unknown): string {
+  if (Token.is(value)) return Configurations.type(value)
   if (Array.isArray(value)) return `readonly [${value.map(type).join(',')}]`
   if (!value || typeof value !== 'object') return JSON.stringify(value)
 
@@ -518,6 +649,11 @@ export function write(
       }
 
     return {
+      ...(link.call.variableSet ? { variableSet: true } : {}),
+      ...(link.call.directVariables ? { directVariables: true } : {}),
+      ...(link.call.variableConfig
+        ? { variableConfig: true, variableMappings: link.call.variableMappings }
+        : {}),
       ...(link.call.recipe ? { recipe: true } : {}),
       ...(link.call.output ? { output: link.call.output } : {}),
       ...(link.call.script &&
@@ -534,7 +670,7 @@ export function write(
       ...(link.call.selection ? { selection: true } : {}),
       ...(link.call.initialization ? { initialization: true } : {}),
       ...(link.call.root ? { root: true } : {}),
-      ...(link.call.options ? { options: link.call.options } : {}),
+      ...(link.call.options ? { options: encode(link.call.options) } : {}),
       ...(link.members
         ? {
             members: Object.fromEntries(
@@ -565,15 +701,53 @@ export function write(
           ...(theme[Token.definition].contract.shorthands
             ? { shorthands: theme[Token.definition].contract.shorthands }
             : {}),
+          ...(theme[Token.definition].contract.defaultLayer !== undefined
+            ? { defaultLayer: theme[Token.definition].contract.defaultLayer }
+            : {}),
           ...(theme[Token.definition].contract.cssOutput
             ? { cssOutput: theme[Token.definition].contract.cssOutput }
             : {}),
+          ...(theme[Token.definition].contract.variableSet
+            ? {
+                variableSet: true,
+                mappings: theme[Token.definition].contract.mappings,
+              }
+            : {}),
           identity: theme[Token.definition].contract[Token.identity],
-          tokens: input(theme),
+          tokens: encode(input(theme)),
         },
       ]),
     ),
     version: (() => {
+      if (
+        Object.values(themes).some(
+          (theme) =>
+            theme[Token.definition].contract.defaultLayer !== undefined,
+        )
+      )
+        return 27
+      if (
+        Object.values(themes).some(
+          (theme) => theme[Token.definition].contract.variableSet,
+        )
+      )
+        return 26
+      if (
+        Object.values(themes).some(
+          (theme) =>
+            theme[Token.definition].paths ||
+            Object.hasOwn(theme.tokens, 'borderWidth'),
+        )
+      )
+        return 25
+
+      if (
+        Object.values(themes).some((theme) =>
+          Object.hasOwn(theme.tokens, 'typography'),
+        )
+      )
+        return 24
+
       function callable(link: Themes.Link): boolean {
         return !!link.style || Object.values(link.members ?? {}).some(callable)
       }
@@ -844,3 +1018,35 @@ function extended(signature: NonNullable<Themes.Call['function']>): boolean {
     )
   )
 }
+
+function encode(value: unknown): unknown {
+  if (Token.is(value))
+    return {
+      $variable: {
+        identity: value.contract[Token.identity],
+        path: value.path,
+        value: encode(value.value),
+      },
+    }
+  if (Array.isArray(value)) return value.map(encode)
+  if (!value || typeof value !== 'object') return value
+  const fields = Object.fromEntries(
+    Object.entries(value).map(([key, value]) => [key, encode(value)]),
+  )
+  return Object.hasOwn(fields, '$variable') || Object.hasOwn(fields, '$object')
+    ? { $object: fields }
+    : fields
+}
+
+function variableOptions(
+  options: Record<string, unknown>,
+  mappings?: Vars.Mappings | false,
+): Config.VariableOptions {
+  const { theme, themes, defaultTheme, ...rest } = options
+  return {
+    ...rest,
+    vars: (themes ?? theme) as Vars.Values,
+    ...(themes ? { defaultVars: String(defaultTheme) } : {}),
+    ...(mappings !== undefined ? { mappings } : {}),
+  }
+}

package/src/compiler/internal/Contributions.ts

@@ -18,7 +18,7 @@ import * as Properties from './Properties.js'
 import * as RuleReference from '../../internal/RuleReference.js'
 import type * as Scope from './Scope.js'
 import * as Style from '../../Style.js'
-import * as Theme from '../../Theme.js'
+import * as Theme from '../../internal/Theme.js'
 import * as Themes from './Themes.js'
 import type * as Token from '../../internal/Token.js'
 import * as Walker from 'oxc-walker'

package/src/compiler/internal/Dynamic.ts

@@ -64,7 +64,7 @@ export function read(
         'key',
         'ref',
         'style',
-        'variables',
+        'vars',
         '__proto__',
       ].includes(key) ||
       Object.hasOwn(slots, key)

package/src/compiler/internal/Expression.ts

@@ -4,7 +4,33 @@
  */
 import type * as Ast from '@oxc-project/types'
 import * as Binding from '../../internal/Binding.js'
+import * as Literal from '../../internal/Literal.js'
 import * as Token from '../../internal/Token.js'
+import * as Tree from 'css-tree'
+
+/** Checks color substitutions inside compound CSS values without widening direct reference domains. */
+export function acceptsColor(
+  expression: Token.Expression,
+  property: keyof Literal.Properties,
+): boolean {
+  const value = expression.parts
+    .map((part) => {
+      if (typeof part === 'string') return part
+      if (Binding.is(part) ? part.type === 'color' : part.group === 'color')
+        return 'rgb(1 2 3)'
+      return 'var(--zyzz-reference)'
+    })
+    .join('')
+    .replace(/ !important$/, '')
+
+  try {
+    return (
+      Tree.lexer.matchProperty(Literal.name(property), value).error === null
+    )
+  } catch {
+    return false
+  }
+}
 
 /** Folds cooked template text and literal primitive substitutions; unresolved syntax returns undefined. */
 export function template(

package/src/compiler/internal/Identifiers.ts

@@ -99,8 +99,9 @@ export function read(value: string): string | undefined {
 /** Reads an explicit authoring identity shared with uncompiled execution. */
 export function explicit(
   call: import('@oxc-project/types').CallExpression,
+  index = 1,
 ): string | undefined {
-  const argument = call.arguments[1]
+  const argument = call.arguments[index]
   if (!argument) return undefined
   if (argument.type !== 'ObjectExpression' || argument.properties.length !== 1)
     throw new Error('Definition options require one literal id.')

package/src/compiler/internal/NativeBindings.ts

@@ -19,13 +19,13 @@ export function compile(
   return {
     ...prepared,
     styles: StyleSheet.select(prepared.styles, {
-      theme: options.theme ?? 'default',
+      set: options.set ?? 'default',
       colorScheme: options.colorScheme,
     }),
   }
 }
 
-/** Prepares immutable programs and all theme/scheme tables before selection. */
+/** Prepares immutable programs and all set/scheme tables before selection. */
 export function prepare(
   recipe: Recipe.Definition,
   call: Pick<Source.Call, 'slots' | 'recipe'>,
@@ -131,7 +131,7 @@ export function prepare(
     styles: { styles: fragments },
     fonts: options.fonts,
     platform: options.platform,
-    themes: options.themes,
+    vars: options.vars,
     units: options.units,
   })
   return {

package/src/compiler/internal/PackedStyles.ts

@@ -8,7 +8,7 @@ import * as ConditionalRecipe from '../../runtime/ConditionalRecipe.js'
 import * as Literal from '../../internal/Literal.js'
 import type * as Source from '../Source.js'
 import type * as Style from '../../Style.js'
-import type * as Theme from '../../Theme.js'
+import type * as Theme from '../../internal/Theme.js'
 import * as Token from '../../internal/Token.js'
 
 /** Portable composition inputs; selection behavior remains in the compiled callable. */
@@ -94,11 +94,10 @@ export function read(
       )
       // Catalog themes share identities and paths but retain distinct fallback values.
       tokens.set(
-        JSON.stringify([
-          value.contract[Token.identity],
-          value.path,
-          value.value,
-        ]),
+        JSON.stringify(
+          [value.contract[Token.identity], value.path, value.value],
+          encode,
+        ),
         value,
       )
       return
@@ -320,14 +319,9 @@ export function read(
           const name = string(value)
           if (
             !field ||
-            [
-              '__proto__',
-              'style',
-              'className',
-              'variables',
-              'key',
-              'ref',
-            ].includes(field) ||
+            ['__proto__', 'style', 'className', 'vars', 'key', 'ref'].includes(
+              field,
+            ) ||
             !slots.includes(name)
           )
             throw new Error('Invalid packed dynamic slot.')
@@ -430,22 +424,24 @@ export function write(definition: Definition): unknown {
           cssOutput: definition.style.cssOutput ?? 'atomic',
         },
       },
-      (_, value: unknown) => {
-        if (Token.is(value))
-          return {
-            identity: value.contract[Token.identity],
-            kind: 'token',
-            path: value.path,
-            value: value.value,
-          }
-        if (Token.isExpression(value))
-          return { kind: 'expression', parts: value.parts }
-        return value
-      },
+      encode,
     ),
   )
 }
 
+function encode(_: string, value: unknown): unknown {
+  if (Token.is(value))
+    return {
+      identity: value.contract[Token.identity],
+      kind: 'token',
+      path: value.path,
+      value: value.value,
+    }
+  if (Token.isExpression(value))
+    return { kind: 'expression', parts: value.parts }
+  return value
+}
+
 function array(value: unknown): unknown[] {
   if (!Array.isArray(value)) throw new Error('Expected a packed style array.')
   return value

package/src/compiler/internal/Recipes.ts

@@ -194,7 +194,7 @@ export function expand(
         'key',
         'ref',
         'style',
-        'variables',
+        'vars',
       ].includes(axis)
     )
       throw new Themes.InvalidError(

package/src/compiler/internal/Selectors.ts

@@ -2,7 +2,7 @@
 import type * as Ast from '@oxc-project/types'
 import * as Walker from 'oxc-walker'
 import * as Condition from '../../internal/Condition.js'
-import * as Theme from '../../Theme.js'
+import * as Theme from '../../internal/Theme.js'
 import * as AtRules from './AtRules.js'
 import * as Identity from '../../internal/Identity.js'
 import * as Identifiers from './Identifiers.js'