zyzz 0.0.19 → 0.0.20

package/src/compiler/internal/Contract.ts

@@ -26,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, 24, 25, 26, 27, 28,
+      22, 23, 24, 25, 26, 27, 28, 29,
     ].includes(data.version as number)
   )
     throw new Error('Unsupported Zyzz contract version.')
@@ -69,6 +69,26 @@ export function read(
           decode(value),
         ]),
       )
+    if (Object.hasOwn(fields, '$composition')) {
+      if ((data.version as number) < 29)
+        throw new Error(
+          'Composed variables require contract version 29 or later.',
+        )
+      const composition = record(fields.$composition)
+      if (
+        (composition.group !== 'color' && composition.group !== 'spacing') ||
+        !Array.isArray(composition.parts)
+      )
+        throw new Error('Invalid packed variable composition.')
+      return Vars.compose(
+        composition.group,
+        composition.parts.map(decode) as readonly (
+          | string
+          | number
+          | Vars.Reference
+        )[],
+      )
+    }
     if (Object.hasOwn(fields, '$variable')) {
       const reference = record(fields.$variable)
       const identity = string(reference.identity)
@@ -294,7 +314,7 @@ export function read(
       if (
         ![
           9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
-          27, 28,
+          27, 28, 29,
         ].includes(data.version as number) ||
         ![
           'cssFunction',
@@ -590,7 +610,8 @@ function tokens(tree: Theme.References<Theme.Tokens>): Record<string, unknown> {
 }
 
 function type(value: unknown): string {
-  if (Token.is(value)) return Configurations.type(value)
+  if (Token.is(value) || Token.isExpression(value))
+    return Configurations.type(value)
   if (Array.isArray(value)) return `readonly [${value.map(type).join(',')}]`
   if (!value || typeof value !== 'object') return JSON.stringify(value)
 
@@ -727,6 +748,22 @@ export function write(
       ]),
     ),
     version: (() => {
+      function composed(value: unknown): boolean {
+        if (Token.isExpression(value)) return true
+        if (Token.is(value)) return composed(value.value)
+        return (
+          !!value &&
+          typeof value === 'object' &&
+          Object.values(value).some(composed)
+        )
+      }
+      if (
+        Object.values(themes).some((theme) =>
+          composed(theme[Token.definition].values),
+        )
+      )
+        return 29
+
       if (
         Object.values(themes).some(
           (theme) =>
@@ -1031,6 +1068,10 @@ function extended(signature: NonNullable<Themes.Call['function']>): boolean {
 }
 
 function encode(value: unknown): unknown {
+  if (Token.isExpression(value) && 'group' in value)
+    return {
+      $composition: { group: value.group, parts: value.parts.map(encode) },
+    }
   if (Token.is(value))
     return {
       $variable: {
@@ -1044,7 +1085,9 @@ function encode(value: unknown): unknown {
   const fields = Object.fromEntries(
     Object.entries(value).map(([key, value]) => [key, encode(value)]),
   )
-  return Object.hasOwn(fields, '$variable') || Object.hasOwn(fields, '$object')
+  return Object.hasOwn(fields, '$composition') ||
+    Object.hasOwn(fields, '$variable') ||
+    Object.hasOwn(fields, '$object')
     ? { $object: fields }
     : fields
 }

package/src/compiler/internal/Themes.ts

@@ -144,6 +144,7 @@ export function collect(program: Ast.Program, options: collect.Options) {
   const imports = new Set<number>()
   const variableImports = new Set<number>()
   const configImports = new Set<number>()
+  const factoryImports = new Map<number, 'create' | 'define' | 'extend'>()
   const configs = new Map<string, Link>()
   const configBindings = new Map<number, Link>()
   const factoryReferences = new Set<number>()
@@ -188,11 +189,31 @@ export function collect(program: Ast.Program, options: collect.Options) {
           : specifier.imported.value) === 'Config'
       )
         configImports.add(specifier.start)
+      else if (
+        specifier.type === 'ImportSpecifier' &&
+        specifier.importKind !== 'type' &&
+        ['defineConfig', 'defineVars', 'extendVars'].includes(
+          specifier.imported.type === 'Identifier'
+            ? specifier.imported.name
+            : specifier.imported.value,
+        )
+      ) {
+        const name =
+          specifier.imported.type === 'Identifier'
+            ? specifier.imported.name
+            : specifier.imported.value
+        if (name === 'defineConfig')
+          factoryImports.set(specifier.start, 'create')
+        else if (name === 'defineVars')
+          factoryImports.set(specifier.start, 'define')
+        else factoryImports.set(specifier.start, 'extend')
+      }
   }
 
   if (
     !imports.size &&
     !configImports.size &&
+    !factoryImports.size &&
     !Object.keys(options.links ?? {}).length
   )
     return undefined
@@ -251,6 +272,7 @@ export function collect(program: Ast.Program, options: collect.Options) {
 
   const namespaces = new Set<string>()
   const configNamespaces = new Set<string>()
+  const factoryFunctions = new Map<string, 'create' | 'define' | 'extend'>()
   const variableNamespaces = new Set<string>()
   for (const node of program.body)
     if (node.type === 'ImportDeclaration')
@@ -264,6 +286,11 @@ export function collect(program: Ast.Program, options: collect.Options) {
         if (imports.has(specifier.start)) namespaces.add(specifier.local.name)
         else if (configImports.has(specifier.start))
           configNamespaces.add(specifier.local.name)
+        else if (factoryImports.has(specifier.start))
+          factoryFunctions.set(
+            specifier.local.name,
+            factoryImports.get(specifier.start)!,
+          )
 
   function resolve(node: Ast.Node): Link | undefined {
     if (node.type === 'Identifier') {
@@ -426,6 +453,35 @@ export function collect(program: Ast.Program, options: collect.Options) {
     if (node.type === 'TSAsExpression' || node.type === 'TSSatisfiesExpression')
       return data(node.expression, derived)
 
+    if (node.type === 'CallExpression' && !node.optional) {
+      const callee = node.callee
+      if (
+        callee.type === 'MemberExpression' &&
+        !callee.computed &&
+        !callee.optional &&
+        callee.object.type === 'Identifier' &&
+        variableNamespaces.has(callee.object.name) &&
+        derived?.name !== callee.object.name &&
+        callee.property.type === 'Identifier' &&
+        callee.property.name === 'compose'
+      ) {
+        if (node.arguments.length !== 2)
+          return fail(
+            'Vars.compose requires a literal domain and parts array.',
+            node,
+          )
+        const group = data(node.arguments[0]!, derived)
+        const parts = data(node.arguments[1]!, derived)
+        if ((group !== 'color' && group !== 'spacing') || !Array.isArray(parts))
+          return fail(
+            'Vars.compose requires a literal domain and parts array.',
+            node,
+          )
+        factoryReferences.add(callee.start)
+        return Vars.compose(group, parts)
+      }
+    }
+
     if (
       node.type === 'Literal' &&
       (typeof node.value === 'string' || typeof node.value === 'number')
@@ -536,37 +592,52 @@ export function collect(program: Ast.Program, options: collect.Options) {
       registerAlias({ declaration, statement, variable })
 
       const expression = variable.init
-      if (
-        expression?.type !== 'CallExpression' ||
-        expression.callee.type !== 'MemberExpression' ||
-        expression.callee.object.type !== 'Identifier' ||
-        (!namespaces.has(expression.callee.object.name) &&
-          !configNamespaces.has(expression.callee.object.name))
-      )
-        continue
+      if (expression?.type !== 'CallExpression' || expression.optional) continue
 
       const member = expression.callee
+      const directFactory =
+        member.type === 'Identifier'
+          ? factoryFunctions.get(member.name)
+          : undefined
       if (
-        member.computed ||
-        member.optional ||
-        expression.optional ||
-        member.property.type !== 'Identifier' ||
-        !(
-          configNamespaces.has(expression.callee.object.name)
-            ? ['create']
-            : ['define', 'extend']
-        ).includes(member.property.name)
+        !directFactory &&
+        (member.type !== 'MemberExpression' ||
+          member.object.type !== 'Identifier' ||
+          (!namespaces.has(member.object.name) &&
+            !configNamespaces.has(member.object.name)) ||
+          member.computed ||
+          member.optional ||
+          member.property.type !== 'Identifier' ||
+          !(
+            configNamespaces.has(member.object.name)
+              ? ['create']
+              : ['define', 'extend']
+          ).includes(member.property.name))
       )
         continue
 
+      const config =
+        directFactory === 'create' ||
+        (member.type === 'MemberExpression' &&
+          member.object.type === 'Identifier' &&
+          configNamespaces.has(member.object.name))
+      const method =
+        member.type === 'MemberExpression' &&
+        member.property.type === 'Identifier'
+          ? member.property.name
+          : directFactory
+      const variableSet =
+        directFactory === 'define' ||
+        directFactory === 'extend' ||
+        (member.type === 'MemberExpression' &&
+          member.object.type === 'Identifier' &&
+          variableNamespaces.has(member.object.name))
+
       if (
         (statement.type === 'ExportNamedDeclaration' && !options.linked) ||
         declaration.kind !== 'const' ||
         (variable.id.type !== 'Identifier' &&
-          !(
-            configNamespaces.has(expression.callee.object.name) &&
-            variable.id.type === 'ObjectPattern'
-          ))
+          !(config && variable.id.type === 'ObjectPattern'))
       )
         fail(
           'Define local themes with a module-level const; exported themes require source linking.',
@@ -601,10 +672,7 @@ export function collect(program: Ast.Program, options: collect.Options) {
         fail('Configuration destructuring requires a binding.', variable)
 
       let name = `${options.namespace}-${binding}`
-      if (
-        !configNamespaces.has(expression.callee.object.name) &&
-        member.property.name === 'define'
-      ) {
+      if (!config && method === 'define') {
         const argument = expression.arguments[1]
         const callback = argument && Expression.unwrap(argument)
         const id = Identifiers.explicit(
@@ -617,7 +685,7 @@ export function collect(program: Ast.Program, options: collect.Options) {
         if (id !== undefined) name = Identity.requireId(id, 'Vars.define')
       }
 
-      if (configNamespaces.has(expression.callee.object.name)) {
+      if (config) {
         try {
           const link = Configurations.collect({
             data,
@@ -772,7 +840,7 @@ export function collect(program: Ast.Program, options: collect.Options) {
       let output: Call['output']
 
       try {
-        if (member.property.name === 'define') {
+        if (method === 'define') {
           if (
             expression.arguments.length < 1 ||
             expression.arguments.length > 3
@@ -786,9 +854,6 @@ export function collect(program: Ast.Program, options: collect.Options) {
 
           tokenType = type(expression.arguments[0]!)
 
-          const variableSet = variableNamespaces.has(
-            expression.callee.object.name,
-          )
           const argument = expression.arguments[1]
           const callback = argument && Expression.unwrap(argument)
           if (
@@ -860,7 +925,7 @@ export function collect(program: Ast.Program, options: collect.Options) {
             )
 
           factoryReferences.add(base!.start)
-          definition = variableNamespaces.has(expression.callee.object.name)
+          definition = variableSet
             ? VariableSets.theme(
                 Vars.extend(
                   VariableSets.from(themes[parent.name]![Token.definition]),
@@ -892,7 +957,7 @@ export function collect(program: Ast.Program, options: collect.Options) {
       }
 
       const call = Object.freeze({
-        ...(variableNamespaces.has(expression.callee.object.name)
+        ...(variableSet
           ? {
               variableSet: true,
               directVariables: true,
@@ -1286,12 +1351,22 @@ export function collect(program: Ast.Program, options: collect.Options) {
 
     if (
       binding?.type === 'Import' &&
-      (imports.has(binding.node.start) || configImports.has(binding.node.start))
+      (imports.has(binding.node.start) ||
+        configImports.has(binding.node.start) ||
+        factoryImports.has(binding.node.start))
     ) {
+      if (
+        factoryImports.has(binding.node.start) &&
+        parent.type === 'CallExpression' &&
+        factories.has(parent.start)
+      )
+        return true
+
       if (
         parent.type === 'MemberExpression' &&
         grandparent?.type === 'CallExpression' &&
-        factories.has(grandparent.start)
+        (factories.has(grandparent.start) ||
+          factoryReferences.has(parent.start))
       )
         return true
 

package/src/default.ts

@@ -80,8 +80,8 @@ export const tokens = {
       1000: { dark: '#fef3dc', light: '#4e2009' },
     },
     background: {
-      100: { dark: '#0a0a0a', light: '#fff' },
-      200: { dark: '#000', light: '#fafafa' },
+      primary: { dark: '#000', light: '#fafafa' },
+      surface: { dark: '#0a0a0a', light: '#fff' },
     },
     black: '#000',
     blue: {
@@ -169,7 +169,6 @@ export const tokens = {
       900: { dark: '#ff6166', light: '#cb2a2f' },
       1000: { dark: '#feecee', light: '#391417' },
     },
-    surface: { dark: '#0a0a0a', light: '#fff' },
     teal: {
       100: { dark: '#04201b', light: '#eefcf9' },
       200: { dark: '#062822', light: '#e5faf6' },
@@ -428,14 +427,14 @@ export const tokens = {
         fontSize: '20px',
         fontWeight: 400,
         letterSpacing: '0px',
-        lineHeight: '36px',
+        lineHeight: '28px',
         strong: {
           fontFamily:
             'Geist, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
           fontSize: '20px',
           fontWeight: 550,
           letterSpacing: '0px',
-          lineHeight: '36px',
+          lineHeight: '28px',
         },
       },
       '24': {
@@ -722,8 +721,8 @@ const config = Config.create({
         1000: { dark: '#fef3dc', light: '#4e2009' },
       },
       background: {
-        100: { dark: '#0a0a0a', light: '#fff' },
-        200: { dark: '#000', light: '#fafafa' },
+        primary: { dark: '#000', light: '#fafafa' },
+        surface: { dark: '#0a0a0a', light: '#fff' },
       },
       black: '#000',
       blue: {
@@ -811,7 +810,6 @@ const config = Config.create({
         900: { dark: '#ff6166', light: '#cb2a2f' },
         1000: { dark: '#feecee', light: '#391417' },
       },
-      surface: { dark: '#0a0a0a', light: '#fff' },
       teal: {
         100: { dark: '#04201b', light: '#eefcf9' },
         200: { dark: '#062822', light: '#e5faf6' },
@@ -1070,14 +1068,14 @@ const config = Config.create({
           fontSize: '20px',
           fontWeight: 400,
           letterSpacing: '0px',
-          lineHeight: '36px',
+          lineHeight: '28px',
           strong: {
             fontFamily:
               'Geist, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
             fontSize: '20px',
             fontWeight: 550,
             letterSpacing: '0px',
-            lineHeight: '36px',
+            lineHeight: '28px',
           },
         },
         '24': {

package/src/index.ts

@@ -8,6 +8,21 @@ export * as Config from './Config.js'
 export { style } from './styleFunction.js'
 /** Ordered composition of applied styling props. */
 export { cx } from './cx.js'
+/**
+ * Creates isolated authoring with optional vars and named alternatives.
+ * @alias Config.create
+ */
+export { create as defineConfig } from './Config.js'
+/**
+ * Creates immutable typed variable sets without emitting CSS.
+ * @alias Vars.define
+ */
+export { define as defineVars } from './Vars.js'
+/**
+ * Overrides variable values while preserving their shared contract.
+ * @alias Vars.extend
+ */
+export { extend as extendVars } from './Vars.js'
 /** Inferred component inputs from callable style definitions. */
 export type * as Props from './Props.js'
 /** Typed literal style definitions and validation diagnostics. */

package/src/internal/Authoring.ts

@@ -157,7 +157,7 @@ export function variants(
   return (values: Record<string, unknown> & style.Options = {}) => {
     const result = { ...props(values as style.Options) } as {
       className: string
-      style?: style.Props['style']
+      style?: NonNullable<style.Props['style']>
       [key: `data-${string}`]: string | undefined
     }
     const bindings: Record<string, string | number> = {}

package/src/internal/Token.ts

@@ -262,6 +262,11 @@ export function acceptsReference(
   if (property.startsWith('--')) return true
   function check(value: Value): boolean {
     if (is(value)) return acceptsReference(value, property)
+    if (isExpression(value))
+      return Binding.accepts(
+        value.group === 'color' ? 'color' : 'length',
+        property,
+      )
     if (typeof value === 'object') return Object.values(value).every(check)
     if (typeof value === 'number') {
       const rule = Literal.rule(property)
@@ -403,6 +408,18 @@ export type Expression = {
   readonly parts: readonly (string | Reference | Binding.Reference)[]
 }
 
+/** A composed variable value with an explicit scalar domain. */
+export type Composition<
+  group extends 'color' | 'spacing' = 'color' | 'spacing',
+> = {
+  /** Structured expression discriminator. */
+  readonly [expression]: true
+  /** Domain retained by variable references and compatible overrides. */
+  readonly group: group
+  /** CSS text and references to portable variable values. */
+  readonly parts: readonly (string | Reference)[]
+}
+
 /** Identifies structured web expressions independently of literal CSS text. */
 export const expression = Symbol('zyzz.expression')
 
@@ -558,17 +575,27 @@ type Paths<tree, property extends keyof Literal.Properties = never> = [
         > extends Value
           ? [property] extends [never]
             ? PathKey<key>
-            : VariableSets.Scalar<
-                  NonNullable<tree[key]>
-                > extends Literal.Properties[property] &
-                  ValueSyntax.Checked<
-                    Record<
-                      property,
-                      VariableSets.Scalar<NonNullable<tree[key]>>
-                    >
-                  >[property]
-              ? PathKey<key>
-              : never
+            : Literal.Color extends VariableSets.Scalar<NonNullable<tree[key]>>
+              ? property extends Properties<'color'>
+                ? PathKey<key>
+                : never
+              : Literal.Length extends VariableSets.Scalar<
+                    NonNullable<tree[key]>
+                  >
+                ? Binding.Property<'length', property> extends never
+                  ? never
+                  : PathKey<key>
+                : VariableSets.Scalar<
+                      NonNullable<tree[key]>
+                    > extends Literal.Properties[property] &
+                      ValueSyntax.Checked<
+                        Record<
+                          property,
+                          VariableSets.Scalar<NonNullable<tree[key]>>
+                        >
+                      >[property]
+                  ? PathKey<key>
+                  : never
           : `${key}.${Paths<NonNullable<tree[key]>, property>}`
       }[Extract<keyof tree, number | string>]
 
@@ -794,6 +821,7 @@ export type Value =
   | number
   | string
   | Reference
+  | Composition
   | { readonly dark: Value; readonly light: Value }
   | Conditions
 

package/src/internal/VariableSets.ts

@@ -75,6 +75,7 @@ export function build(
       typeof input === 'string' ||
       typeof input === 'number' ||
       Token.is(input) ||
+      Token.isExpression(input) ||
       (path.length > 0 &&
         input &&
         typeof input === 'object' &&
@@ -244,6 +245,17 @@ function read(
   active = new Set<object>(),
 ): Token.Value {
   if (Token.is(input)) return input
+  if (Token.isExpression(input)) {
+    if (
+      !('group' in input) ||
+      (input.group !== 'color' && input.group !== 'spacing')
+    )
+      throw new Vars.InvalidError(path, 'Expected a composed variable value.')
+    return Vars.compose(
+      input.group,
+      input.parts as readonly (string | Token.Reference)[],
+    )
+  }
   if (typeof input === 'number' && Number.isFinite(input)) return input
   if (typeof input === 'string' && input.trim() && !/[;{}]/.test(input))
     return input
@@ -307,7 +319,7 @@ function read(
 
 /** Infers the shared declaration domain after following defaults and references. */
 export function domain(value: Token.Value): Token.Group {
-  if (Token.is(value)) return value.group
+  if (Token.is(value) || Token.isExpression(value)) return value.group
   if (typeof value === 'object')
     return 'default' in value ? domain(value.default) : 'color'
   if (
@@ -383,6 +395,7 @@ export function merge(
           typeof entry !== 'object' ||
           Array.isArray(entry) ||
           Token.is(entry) ||
+          Token.isExpression(entry) ||
           'default' in entry ||
           ('light' in entry && 'dark' in entry) ||
           (Object.keys(entry).length <= 2 &&
@@ -424,6 +437,17 @@ export function rebind(
         value: visit(value.path),
       })
     }
+    if (Token.isExpression(value))
+      return Vars.compose(
+        value.group,
+        value.parts.map((part) => {
+          if (typeof part === 'string') return part
+          const reference = resolve(part)
+          if (!Token.is(reference))
+            throw new Vars.InvalidError([], 'Expected a variable reference.')
+          return reference
+        }),
+      )
     if (typeof value !== 'object') return value
 
     return Object.freeze(

package/src/node/Host.ts

@@ -49,6 +49,14 @@ export async function create(options: create.Options): Promise<Runtime> {
           targets: { ...options.css?.targets },
         }
 
+  const externals = [...(options.external ?? [])]
+  if (
+    externals.some((pattern) => !pattern || pattern.slice(0, -1).includes('*'))
+  )
+    throw new Error(
+      'External imports require exact names or a trailing * prefix.',
+    )
+
   const native = options.native
     ? Object.freeze({
         ...options.native,
@@ -404,6 +412,15 @@ export async function create(options: create.Options): Promise<Runtime> {
           (!specifier.startsWith('#') && specifier.includes('#'))
         )
           continue
+        if (
+          externals.some((pattern) =>
+            pattern.endsWith('*')
+              ? specifier.startsWith(pattern.slice(0, -1))
+              : specifier === pattern,
+          )
+        )
+          continue
+
         try {
           if (specifier.startsWith('.')) {
             const target = Relative.resolve({ moduleId, modules, specifier })
@@ -951,6 +968,8 @@ export declare namespace create {
           readonly targets?: Readonly<LightningCss.Targets> | undefined
         }
       | undefined
+    /** Imports left for downstream tooling. Matches exact names or prefixes ending in *. */
+    readonly external?: readonly string[] | undefined
     /** Native context captured at creation. Emits modules and maps without CSS or web initialization. */
     readonly native?: Graph.compile.Options['native']
     /** Output directory exclusively locked until close; may be nested under root. Defaults to `dist`. */

package/src/react-native/StyleSheet.ts

@@ -785,6 +785,12 @@ function resolve(
       resolved = resolved.value
       continue
     }
+    if (Token.isExpression(resolved))
+      fail(
+        'unsupported_feature',
+        'Composed variables require a web target.',
+        path,
+      )
     if ('default' in resolved)
       fail(
         'unsupported_feature',

package/src/styleFunction.ts

@@ -114,9 +114,7 @@ export declare namespace style {
         /** Compiled and supplied class names. */
         readonly className: string
         /** Supplied inline styling overrides when present. */
-        readonly style?:
-          | Readonly<Record<string, string | number | undefined>>
-          | undefined
+        readonly style?: Readonly<Record<string, string | number | undefined>>
       }
 
   /** Callable definition; source rewriting supplies its implementation. */