zyzz 0.0.18 → 0.0.20

package/src/Vars.ts

@@ -7,9 +7,16 @@ import * as Token from './internal/Token.js'
 import * as VariableSets from './internal/VariableSets.js'
 import type { style } from './styleFunction.js'
 
-/** Portable scalar reference with its accepted value domain. */
-export type Reference<group extends Token.Group = Token.Group> =
-  Token.Reference<group>
+export type { Composition } from './internal/Token.js'
+
+/** Portable scalar reference retaining its value domain and optional literal precision. */
+export type Reference<
+  group extends Token.Group = Token.Group,
+  scalar = never,
+> = Token.Reference<group> &
+  ([scalar] extends [never]
+    ? { readonly [Token.scalar]?: unknown }
+    : { readonly [Token.scalar]: scalar })
 
 const shape = Symbol('zyzz.variables.shape')
 
@@ -18,9 +25,10 @@ export type Value =
   | string
   | number
   | Token.Reference
+  | Token.Composition
   | {
-      readonly light: string | Token.Reference
-      readonly dark: string | Token.Reference
+      readonly light: string | Token.Reference | Token.Composition<'color'>
+      readonly dark: string | Token.Reference | Token.Composition<'color'>
     }
   | ({ readonly default: Value } & {
       readonly [query: `@media ${string}`]: Value
@@ -47,32 +55,41 @@ export type References<values, root extends boolean = true> = {
     keyof values,
     root extends true ? 'breakpoint' | 'containerNames' : never
   >]: values[key] extends Value
-    ? Token.Reference<Domain<Scalar<values[key]>>> & {
-        readonly [Token.scalar]: Scalar<values[key]>
-      }
+    ? Reference<
+        Domain<Scalar<values[key]>>,
+        Literal.Color extends Scalar<values[key]>
+          ? never
+          : Literal.Length extends Scalar<values[key]>
+            ? never
+            : Scalar<values[key]>
+      >
     : References<values[key], false>
 }
 
 /** Resolves the scalar types represented by all conditional branches. */
 export type Scalar<value> = Value extends value
   ? string | number
-  : value extends { readonly [Token.scalar]: infer scalar }
-    ? scalar
-    : value extends readonly string[]
-      ? value
-      : value extends Token.Reference<infer group>
-        ? group extends 'color'
-          ? Literal.Color
-          : group extends 'spacing'
-            ? Literal.Length
-            : group extends 'number'
-              ? number
-              : string
-        : value extends { default: unknown }
-          ? Scalar<value[keyof value]>
-          : value extends { light: infer light; dark: infer dark }
-            ? Scalar<light | dark>
-            : value
+  : value extends Token.Composition<infer group>
+    ? group extends 'color'
+      ? Literal.Color
+      : Literal.Length
+    : value extends { readonly [Token.scalar]: infer scalar }
+      ? scalar
+      : value extends readonly string[]
+        ? value
+        : value extends Token.Reference<infer group>
+          ? group extends 'color'
+            ? Literal.Color
+            : group extends 'spacing'
+              ? Literal.Length
+              : group extends 'number'
+                ? number
+                : string
+          : value extends { default: unknown }
+            ? Scalar<value[keyof value]>
+            : value extends { light: infer light; dark: infer dark }
+              ? Scalar<light | dark>
+              : value
 
 /** Scalar domain shared by compatible set alternatives. */
 export type Domain<value> = [value] extends [Literal.Color]
@@ -83,6 +100,41 @@ export type Domain<value> = [value] extends [Literal.Color]
       ? 'number'
       : 'string'
 
+/**
+ * Composes immutable web CSS text and live references in a color or spacing domain.
+ * @throws {InvalidError} If parts are empty, nonfinite, contain declaration markers, or include unsupported values.
+ */
+export function compose<group extends 'color' | 'spacing'>(
+  group: group,
+  parts: readonly (string | number | Reference)[],
+): Token.Composition<group> {
+  if (group !== 'color' && group !== 'spacing')
+    throw new InvalidError(
+      [],
+      'Compositions require a color or spacing domain.',
+    )
+  if (!Array.isArray(parts) || !parts.length)
+    throw new InvalidError([], 'Compositions require nonempty CSS parts.')
+
+  const values = Array.from(parts, (part) => {
+    if (Token.is(part)) return part
+    if (typeof part === 'number' && Number.isFinite(part)) return String(part)
+    if (typeof part === 'string' && !/[;{}!]/.test(part)) return part
+    throw new InvalidError(
+      [],
+      'Composition parts must be CSS text, finite numbers, or variable references.',
+    )
+  })
+  if (!values.some((part) => typeof part !== 'string' || part.trim()))
+    throw new InvalidError([], 'Compositions require nonempty CSS parts.')
+
+  return Object.freeze({
+    [Token.expression]: true as const,
+    group,
+    parts: Object.freeze(values),
+  })
+}
+
 /** Creates typed references without emitting CSS or reading the environment. */
 export function define<const values extends Values>(
   values: values & NoInfer<Validated<values, false, true>>,
@@ -166,12 +218,19 @@ type Compatible<scalar> = [scalar] extends [Literal.Color]
   ?
       | Literal.Color
       | Token.Reference<'color'>
+      | Token.Composition<'color'>
       | {
-          readonly light: Literal.Color | Token.Reference<'color'>
-          readonly dark: Literal.Color | Token.Reference<'color'>
+          readonly light:
+            | Literal.Color
+            | Token.Reference<'color'>
+            | Token.Composition<'color'>
+          readonly dark:
+            | Literal.Color
+            | Token.Reference<'color'>
+            | Token.Composition<'color'>
         }
   : [scalar] extends [Literal.Length]
-    ? Literal.Length | Token.Reference<'spacing'>
+    ? Literal.Length | Token.Reference<'spacing'> | Token.Composition<'spacing'>
     : [scalar] extends [number]
       ? number | Token.Reference<'number'>
       : string | Token.Reference<'string'>
@@ -221,7 +280,7 @@ type Validated<
   ? value
   : value extends readonly string[]
     ? never
-    : value extends Token.Reference
+    : value extends Token.Reference | Token.Composition
       ? value
       : value extends string | number
         ? Literal.Checked<value>

package/src/cli/index.ts

@@ -25,6 +25,10 @@ const options = z.object({
     .boolean()
     .default(false)
     .describe('Emit only CSS and CSS maps without source transformation'),
+  external: z
+    .array(z.string())
+    .optional()
+    .describe('External import name or trailing * prefix (repeatable)'),
   minify: z.boolean().default(false).describe('Minify emitted CSS'),
   'out-dir': z.string().default('dist').describe('Output directory'),
   'package-id': z
@@ -178,6 +182,7 @@ async function open(context: open.Context) {
       : {}),
     compiler: !context.options['css-only'],
     css: { minify: context.options.minify },
+    external: context.options.external,
     modules: !context.options['css-only'],
     outDir: Path.resolve(context.options['out-dir']),
     packageId,

package/src/compiler/Source.ts

@@ -375,6 +375,9 @@ export function extract(options: extract.Options): extract.ReturnType {
           if (
             name === 'Config' ||
             name === 'cx' ||
+            name === 'defineConfig' ||
+            name === 'defineVars' ||
+            name === 'extendVars' ||
             name === 'style' ||
             name === 'Theme' ||
             name === 'Vars' ||

package/src/compiler/internal/Configurations.ts

@@ -148,6 +148,7 @@ export function collect(options: collect.Options): Themes.Link {
         }
       : {}),
     [Token.identity]: identity,
+    ...(input.id !== undefined ? { [Token.complete]: true } : {}),
     cssOutput: input.cssOutput ?? 'atomic',
     ...(input.defaultLayer !== undefined
       ? { defaultLayer: input.defaultLayer }
@@ -294,6 +295,8 @@ export declare namespace collect {
 
 /** Encodes validated literal options as a declaration type, never executable text. */
 export function type(value: unknown): string {
+  if (Token.isExpression(value) && 'group' in value)
+    return `import('zyzz').Vars.Composition<'${value.group}'>`
   if (Token.is(value)) return `import('zyzz').Vars.Reference<'${value.group}'>`
   if (Array.isArray(value)) return `readonly [${value.map(type).join(',')}]`
   if (!value || typeof value !== 'object') return JSON.stringify(value)

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> = {}