zyzz 0.0.24 → 0.0.26

package/src/compiler/internal/Themes.ts

@@ -494,13 +494,31 @@ export function collect(program: Ast.Program, options: collect.Options) {
       root = root.object
     }
     if (root.type !== 'Identifier') return undefined
-    const local = derived?.name === root.name
-    const call = names.get(root.name)
-    if (!local && !call) return undefined
-    let value: unknown = local ? derived.vars : themes[call!.name]?.tokens
-    if (!local && !call!.variableSet && !call!.directVariables) {
-      if (!['vars', 'tokens'].includes(path.shift()!)) return undefined
-    }
+    const name = root.name
+    let value: unknown = (() => {
+      if (derived?.name === name) return derived.vars
+
+      const call = names.get(name)
+      if (call) {
+        if (
+          !call.variableSet &&
+          !call.directVariables &&
+          !['vars', 'tokens'].includes(path.shift()!)
+        )
+          return undefined
+        return themes[call.name]?.tokens
+      }
+
+      // Config-bound vars read the configured variables, so they follow set scoping.
+      const config = configs.get(name)
+      if (
+        !config?.call.variableConfig ||
+        (!config.call.selection && path.shift() !== 'vars')
+      )
+        return undefined
+      return themes[config.call.name]?.tokens
+    })()
+    if (value === undefined) return undefined
     for (const key of path)
       value =
         value && typeof value === 'object'
@@ -615,6 +633,68 @@ export function collect(program: Ast.Program, options: collect.Options) {
     return result
   }
 
+  /** Reads a derived-variables callback as one parameter name and a literal body. */
+  function derivation(argument: Ast.Node | undefined) {
+    const callback = argument && Expression.unwrap(argument)
+    if (
+      callback?.type !== 'ArrowFunctionExpression' &&
+      callback?.type !== 'FunctionExpression'
+    )
+      return undefined
+
+    const parameter = callback.params[0]
+    const body = (() => {
+      if (callback.body?.type !== 'BlockStatement') return callback.body
+      if (
+        callback.body.body.length === 1 &&
+        callback.body.body[0]?.type === 'ReturnStatement'
+      )
+        return callback.body.body[0].argument
+      return undefined
+    })()
+    if (
+      callback.async ||
+      callback.generator ||
+      callback.params.length !== 1 ||
+      parameter?.type !== 'Identifier' ||
+      !body
+    )
+      fail(
+        'Derived variables require one named parameter and a literal return value.',
+        callback,
+      )
+
+    return { body, name: parameter.name }
+  }
+
+  /** Authored values of an extension, keeping base values at existing paths as `Vars.extend` types do. */
+  function extendedValues(base: Theme.Definition, extension: Theme.Definition) {
+    const metadata = extension[Token.definition]
+    const known = base[Token.definition].values
+    const tree: Record<string, unknown> = Object.create(null)
+
+    for (const path of Object.keys(metadata.values)) {
+      const parts = metadata.paths?.[path] ?? path.split('.')
+      const source = Object.hasOwn(known, path) ? base : extension
+      let target = tree
+      let token: unknown = source.tokens
+
+      for (const part of parts.slice(0, -1)) {
+        target = (target[part] ??= Object.create(null)) as Record<
+          string,
+          unknown
+        >
+        token = (token as Record<string, unknown>)[part]
+      }
+
+      const name = parts.at(-1)!
+      // Every metadata path has a reference in its own token tree.
+      target[name] = (token as Record<string, Token.Reference>)[name]!.value
+    }
+
+    return tree
+  }
+
   function fail(message: string, node: Pick<Ast.Node, 'end' | 'start'>): never {
     throw new InvalidError(message, node)
   }
@@ -750,6 +830,18 @@ export function collect(program: Ast.Program, options: collect.Options) {
         )
         if (id !== undefined) name = Identity.requireId(id, 'Vars.define')
       }
+      if (!config && method === 'extend') {
+        const argument = expression.arguments[2]
+        const callback = argument && Expression.unwrap(argument)
+        const id = Identifiers.explicit(
+          expression,
+          callback?.type === 'ArrowFunctionExpression' ||
+            callback?.type === 'FunctionExpression'
+            ? 3
+            : 2,
+        )
+        if (id !== undefined) name = Identity.requireId(id, 'Vars.extend')
+      }
 
       if (config) {
         const nativeProvider =
@@ -931,42 +1023,17 @@ export function collect(program: Ast.Program, options: collect.Options) {
 
           tokenType = type(expression.arguments[0]!)
 
-          const argument = expression.arguments[1]
-          const callback = argument && Expression.unwrap(argument)
-          if (
-            variableSet &&
-            (callback?.type === 'ArrowFunctionExpression' ||
-              callback?.type === 'FunctionExpression')
-          ) {
-            const parameter = callback.params[0]
-            const body = (() => {
-              if (callback.body?.type !== 'BlockStatement') return callback.body
-              if (
-                callback.body.body.length === 1 &&
-                callback.body.body[0]?.type === 'ReturnStatement'
-              )
-                return callback.body.body[0].argument
-              return undefined
-            })()
-            if (
-              callback.async ||
-              callback.generator ||
-              callback.params.length !== 1 ||
-              parameter?.type !== 'Identifier' ||
-              !body
-            )
-              fail(
-                'Derived variables require one named parameter and a literal return value.',
-                callback,
-              )
-
+          const derive = variableSet
+            ? derivation(expression.arguments[1])
+            : undefined
+          if (derive) {
             const base = VariableSets.build(
               input,
               Object.freeze({ variableSet: true, [Token.identity]: name }),
             )
             input = VariableSets.merge(
               input,
-              data(body, { name: parameter.name, vars: base }),
+              data(derive.body, { name: derive.name, vars: base }),
             )
             tokenType = Configurations.type(input)
           } else if (expression.arguments.length > 2)
@@ -994,33 +1061,88 @@ export function collect(program: Ast.Program, options: collect.Options) {
         } else {
           const base = expression.arguments[0]
           const parent = base ? resolve(base)?.call : undefined
+          const derive = variableSet
+            ? derivation(expression.arguments[2])
+            : undefined
 
-          if (expression.arguments.length !== 2 || !parent)
+          const arity = derive ? 3 : 2
+          // A trailing options object names a new set over the base's variables.
+          const id =
+            expression.arguments.length === arity + 1
+              ? Identifiers.explicit(expression, arity)
+              : undefined
+          const named = id !== undefined
+          if (
+            (expression.arguments.length !== arity && !named) ||
+            !parent
+          )
             fail(
               'Vars.extend requires a preceding variable set and literal overrides.',
               expression,
             )
 
           factoryReferences.add(base!.start)
-          definition = variableSet
-            ? VariableSets.theme(
-                Vars.extend(
-                  VariableSets.from(themes[parent.name]![Token.definition]),
-                  data(expression.arguments[1]!) as Vars.Overrides<Vars.Values>,
-                ),
-              )
-            : Theme.extend(
-                themes[parent.name]!,
-                data(expression.arguments[1]!) as Theme.Overrides<Theme.Tokens>,
-              )
+          tokenType = parent.tokenType
+          output = parent.output
+
+          if (variableSet) {
+            const theme = themes[parent.name]!
+            const original = VariableSets.from(theme[Token.definition])
+            const extend = Vars.extend as (
+              variables: Vars.Definition,
+              values: Vars.Values,
+              derive: (vars: Vars.References<Vars.Values>) => Vars.Values,
+              options: { readonly id?: string | undefined },
+            ) => Vars.Definition
+            const extended = extend(
+              original,
+              data(expression.arguments[1]!) as Vars.Values,
+              (vars) =>
+                derive
+                  ? (data(derive.body, {
+                      name: derive.name,
+                      vars: vars as Vars.Definition,
+                    }) as Vars.Values)
+                  : {},
+              { id },
+            )
+            definition = named
+              ? Token.bind(
+                  VariableSets.theme(extended),
+                  Object.freeze({
+                    ...extended[Token.definition].contract,
+                    [Token.identity]: name,
+                  }),
+                )
+              : VariableSets.theme(extended)
+
+            const metadata = definition[Token.definition]
+            // Additions grow the token contract; overridden leaves keep their base types, as in `Vars.extend`.
+            if (
+              named ||
+              Object.keys(metadata.values).length !==
+                Object.keys(theme[Token.definition].values).length ||
+              JSON.stringify(metadata.queries) !==
+                JSON.stringify(theme[Token.definition].queries)
+            )
+              tokenType = Configurations.type({
+                ...extendedValues(theme, definition),
+                ...metadata.queries,
+              })
+          } else
+            definition = Theme.extend(
+              themes[parent.name]!,
+              data(expression.arguments[1]!) as Theme.Overrides<Theme.Tokens>,
+            )
+
+          // Extensions share their base identity, so the binding keeps sibling sets distinct.
           if (
+            !named &&
             definition[Token.definition].contract[Token.identity]?.startsWith(
               'id-',
             )
           )
-            name = definition.className.slice('z-theme-'.length)
-          tokenType = parent.tokenType
-          output = parent.output
+            name = `${definition.className.slice('z-theme-'.length)}-${binding}`
         }
       } catch (error) {
         if (error instanceof InvalidError) throw error

package/src/internal/Configuration.ts

@@ -137,11 +137,12 @@ export function create(
       appearance: result.appearance,
       script: result.script,
       style: result.style,
+      // The default set's metadata lets Vars.extend grow configured vars.
       vars: Object.freeze(
-        Object.defineProperties(
-          vars,
-          Object.getOwnPropertyDescriptors(theme.tokens),
-        ),
+        Object.defineProperties(vars, {
+          ...Object.getOwnPropertyDescriptors(theme.tokens),
+          [Token.definition]: { value: theme[Token.definition] },
+        }),
       ),
       variants: result.variants,
     })
@@ -150,6 +151,7 @@ export function create(
   for (const key of Object.keys(input))
     if (
       ![
+        'composition',
         'cssOutput',
         'id',
         'defaultLayer',
@@ -190,6 +192,13 @@ export function create(
   )
     throw new InvalidError('cssOutput must be atomic or grouped.')
 
+  if (
+    input.composition !== undefined &&
+    input.composition !== 'independent' &&
+    input.composition !== 'ordered'
+  )
+    throw new InvalidError('composition must be independent or ordered.')
+
   if (input.theme !== undefined && input.themes !== undefined)
     throw new InvalidError('Use either theme or themes, not both.')
 
@@ -253,6 +262,9 @@ export function create(
 
   const contract = Object.freeze({
     ...(variableMode ? { variableSet: true, mappings: variableMappings } : {}),
+    ...(input.composition !== undefined
+      ? { composition: input.composition as 'independent' | 'ordered' }
+      : {}),
     ...(input.defaultLayer !== undefined
       ? { defaultLayer: input.defaultLayer as string }
       : {}),
@@ -452,6 +464,11 @@ export function create(
 export declare namespace create {
   /** Optional layer names and mutually exclusive theme modes. */
   type Options = {
+    /**
+     * Whether bound styles' class lists may combine. Independent atomic styles
+     * share rules for repeated declarations, so combine them only with `cx`.
+     */
+    readonly composition?: 'independent' | 'ordered' | undefined
     /** CSS representation inherited by bound helpers; atomic by default. */
     readonly cssOutput?: 'atomic' | 'grouped' | undefined
     /** Fallback CSS layer for bound styles and variants; unlayered when omitted. */
@@ -837,6 +854,11 @@ type Validated<options> = Record<
 
 /** Vars, optional named alternatives, and category-to-property mappings. */
 export type VariableOptions = {
+  /**
+   * Whether bound styles' class lists may combine. Independent atomic styles
+   * share rules for repeated declarations, so combine them only with `cx`.
+   */
+  readonly composition?: 'independent' | 'ordered' | undefined
   /** CSS representation inherited by bound helpers; atomic by default. */
   readonly cssOutput?: 'atomic' | 'grouped' | undefined
   /** Fallback CSS layer for bound styles and variants; unlayered when omitted. */

package/src/internal/Token.ts

@@ -393,6 +393,8 @@ export type Contract = {
   readonly variableSet?: boolean | undefined
   /** Configuration-local category-to-property mappings. */
   readonly mappings?: VariableSets.Mappings | false | undefined
+  /** Whether bound styles' class lists combine, retained by configuration-bound handles. */
+  readonly composition?: 'independent' | 'ordered' | undefined
   /** Web emission mode retained by configuration-bound theme handles. */
   readonly cssOutput?: 'atomic' | 'grouped' | undefined
   /** Fallback layer for declarations without an explicit layer. */

package/src/internal/VariableSets.ts

@@ -55,19 +55,30 @@ export function from(metadata: Token.Metadata): Vars.Definition {
   ) as Vars.Definition
 }
 
-/** Validates and freezes a complete set or compatible partial override. */
+/**
+ * Validates and freezes a complete set, or grows a base set with compatible
+ * overrides and new leaves.
+ */
 export function build(
   input: unknown,
   contract: Token.Contract,
-  base?: Token.Metadata['values'],
-  baseQueries?: Query.Metadata,
-  basePaths?: Token.Metadata['paths'],
+  options: build.Options = {},
 ): Vars.Definition {
+  const base = options.base
   const values: Record<string, Token.Value> = Object.assign(
     Object.create(null),
-    base,
+    base?.values,
   )
-  const paths = { ...basePaths }
+  const paths = { ...base?.paths }
+  // Segment keys keep dotted typography conditions distinct from nested paths.
+  const leaves = new Set<string>()
+  const categories = new Set<string>()
+  for (const path of Object.keys(base?.values ?? {})) {
+    const parts = base!.paths?.[path] ?? path.split('.')
+    leaves.add(JSON.stringify(parts))
+    for (let index = 1; index < parts.length; index++)
+      categories.add(JSON.stringify(parts.slice(0, index)))
+  }
   const conditions: string[][] = []
   const active = new Set<object>()
   function visit(input: unknown, path: string[]) {
@@ -86,14 +97,31 @@ export function build(
     ) {
       if (!path.length)
         throw new Vars.InvalidError(path, 'Expected a variable record.')
-      const value = read(input, path, queryData)
+      if (categories.has(JSON.stringify(path)))
+        throw new Vars.InvalidError(
+          path,
+          'Extensions cannot replace a variable category with a leaf.',
+        )
       const name = path.join('.')
-      if (base && !Object.hasOwn(base, name))
+      const previous =
+        base && Object.hasOwn(base.values, name) ? base.values[name] : undefined
+      if (previous !== undefined && options.derived)
         throw new Vars.InvalidError(
           path,
-          'Extensions cannot add variable paths.',
+          'Derived variables cannot replace existing paths.',
         )
-      if (base && domain(base[name]!) !== domain(value))
+      // Restating the base reference would make the variable reference itself.
+      if (
+        previous !== undefined &&
+        Token.is(input) &&
+        input.path === name &&
+        (input.contract === contract ||
+          (contract[Token.identity] !== undefined &&
+            input.contract[Token.identity] === contract[Token.identity]))
+      )
+        return
+      const value = read(input, path, queryData)
+      if (previous !== undefined && domain(previous) !== domain(value))
         throw new Vars.InvalidError(
           path,
           'Variable overrides must preserve their domain.',
@@ -103,11 +131,19 @@ export function build(
       values[name] = value
       return
     }
+    if (leaves.has(JSON.stringify(path)))
+      throw new Vars.InvalidError(
+        path,
+        'Extensions cannot replace a variable leaf with a category.',
+      )
     const entries = record(input, path)
     if (active.has(input as object))
       throw new Vars.InvalidError(path, 'Cyclic variables are not supported.')
     active.add(input as object)
-    if (!entries.length && !base)
+    if (
+      !entries.length &&
+      (!base || (path.length > 0 && !categories.has(JSON.stringify(path))))
+    )
       throw new Vars.InvalidError(path, 'Variable records cannot be empty.')
     for (const [key, value] of entries) {
       const query = path[0] === 'typography' && Typography.condition(key)
@@ -122,34 +158,29 @@ export function build(
     active.delete(input as object)
   }
   const fields = Object.fromEntries(record(input, []))
-  const queries = { ...baseQueries }
+  const queries = { ...base?.queries }
   for (const key of ['breakpoint', 'container', 'containerNames'] as const) {
     if (Object.hasOwn(fields, key)) {
       const value = fields[key]
       if (base) {
         if (key === 'containerNames') {
           if (
-            JSON.stringify(value) !==
-            JSON.stringify(baseQueries?.containerNames ?? [])
+            !Array.isArray(value) ||
+            (base.queries?.containerNames ?? []).some(
+              (name) => !value.includes(name),
+            )
           )
             throw new Vars.InvalidError(
               [key],
-              'Extensions cannot change container identities.',
+              'Extensions cannot remove container identities.',
             )
-        } else {
-          for (const [name] of record(value, [key]))
-            if (!Object.hasOwn(baseQueries?.[key] ?? {}, name))
-              throw new Vars.InvalidError(
-                [key, name],
-                'Extensions cannot add query thresholds.',
-              )
-        }
+        } else record(value, [key])
       }
       Object.assign(queries, {
         [key]:
           key === 'containerNames'
             ? value
-            : { ...baseQueries?.[key], ...value },
+            : { ...base?.queries?.[key], ...value },
       })
       if (key !== 'container' || Object.keys(value as object).length === 0)
         delete fields[key]
@@ -178,6 +209,55 @@ export function build(
   ) as Vars.Definition
 }
 
+/** Set construction inputs. */
+export declare namespace build {
+  /** Base set metadata and how its existing paths may change. */
+  type Options = {
+    /** Set whose leaves the input overrides or extends. */
+    readonly base?:
+      | Pick<Token.Metadata, 'paths' | 'queries' | 'values'>
+      | undefined
+    /** Rejects existing paths, as derived leaves only add to the set. */
+    readonly derived?: boolean | undefined
+  }
+}
+
+/**
+ * Reads a set's references as values for a named extension. Typography presets
+ * keep their base values, since presets expand at each use.
+ */
+export function references(
+  variables: object,
+  metadata: Pick<Token.Metadata, 'paths' | 'queries' | 'values'>,
+): Vars.Values {
+  const tree: Record<string, unknown> = Object.create(null)
+
+  for (const [path, value] of Object.entries(metadata.values)) {
+    const parts = metadata.paths?.[path] ?? path.split('.')
+    let target = tree
+    let source: unknown = variables
+
+    for (const part of parts.slice(0, -1)) {
+      target = (target[part] ??= Object.create(null)) as Record<string, unknown>
+      source = (source as Record<string, unknown>)[part]
+    }
+
+    const name = parts.at(-1)!
+    target[name] =
+      parts[0] === 'typography'
+        ? value
+        : (source as Record<string, unknown>)[name]
+  }
+
+  for (const key of ['breakpoint', 'container'] as const)
+    if (Object.keys(metadata.queries?.[key] ?? {}).length)
+      tree[key] = metadata.queries![key]
+  if (metadata.queries?.containerNames?.length)
+    tree.containerNames = metadata.queries.containerNames
+
+  return tree as Vars.Values
+}
+
 function buildTree(
   values: Token.Metadata['values'],
   contract: Token.Contract,

package/src/next/internal/Project.ts

@@ -1,5 +1,6 @@
 /** Retains filesystem snapshots and an incremental graph within a Next.js loader worker. @module */
 import * as Contract from '../../compiler/internal/Contract.js'
+import * as Contracts from '../../node/internal/Contracts.js'
 import * as Fs from 'node:fs/promises'
 import * as Graph from '../../compiler/Graph.js'
 import * as Path from 'node:path'
@@ -26,6 +27,7 @@ export type Context = {
 /** Creates project state owned by a loader configuration in one worker process. */
 export function create(options: create.Options) {
   let compiler = Graph.create()
+  const packages = Contracts.create()
   const files = new Map<string, { source: string; version: string }>()
   const libraries = new Map<
     string,
@@ -122,6 +124,20 @@ export function create(options: create.Options) {
       }
       return pending
     }
+    // Files behind package contracts stay dependencies even when the module is unchanged.
+    const inputs = new Set<string>()
+    const host: Contracts.read.Options = {
+      read: async (file) => {
+        const source = await read(file)
+        // Next ignores node_modules edits, and tracked manifests stalled webpack rebuilds after a failed compile.
+        if (Path.basename(file) === 'package.json') return source
+        track(file)
+        inputs.add(file)
+        return source
+      },
+      resolve: async (specifier, importer) =>
+        (await resolve(Path.dirname(importer), specifier)) || undefined,
+    }
     const id = (file: string) =>
       `app/${Path.relative(root, file).split(Path.sep).join('/')}`
     const eligible = (file: string) =>
@@ -322,14 +338,10 @@ export function create(options: create.Options) {
           await visit(resolved)
           continue
         }
-        const sidecar = `${resolved}.zyzz.json`
-        try {
-          contracts[resolved] = await read(sidecar)
-          track(sidecar)
-          links[specifier] = resolved
-        } catch (error) {
-          if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
-        }
+        const contract = await packages.read(resolved, host)
+        if (contract === undefined) continue
+        contracts[resolved] = contract
+        links[specifier] = resolved
       }
     }
 
@@ -360,11 +372,10 @@ export function create(options: create.Options) {
 
           const links = (imports[owner] ??= Object.create(null))
           links[specifier] = target
-          if (!Object.hasOwn(contracts, target)) {
-            const sidecar = `${target}.zyzz.json`
-            contracts[target] = await read(sidecar)
-            track(sidecar)
-          }
+          contracts[target] ??= (await packages.read(target, {
+            ...host,
+            required: true,
+          }))!
           await dependencies(target)
           owner = target
         }
@@ -388,16 +399,10 @@ export function create(options: create.Options) {
     if (output.code === source && !output.css) {
       context.addDependency(context.resourcePath)
       for (const file of runtime) context.addDependency(file)
-      for (const file of tracked)
-        if (file.endsWith('.zyzz.json')) context.addDependency(file)
-      for (const target of Object.values(imports[entry] ?? {})) {
-        if (!target) continue
-        context.addDependency(
-          target.startsWith('app/')
-            ? Path.join(root, target.slice(4))
-            : `${target}.zyzz.json`,
-        )
-      }
+      for (const file of inputs) context.addDependency(file)
+      for (const target of Object.values(imports[entry] ?? {}))
+        if (target?.startsWith('app/'))
+          context.addDependency(Path.join(root, target.slice(4)))
     } else {
       for (const file of tracked) context.addDependency(file)
     }

package/src/next/loader.ts

@@ -161,7 +161,8 @@ async function compile(context: Context, source: string) {
         placeholder,
         Path.relative(directory, file)
           .split(Path.sep)
-          .map(encodeURIComponent)
+          // Bundlers resolve url() paths without decoding, so escape only characters that change URL parsing.
+          .map((part) => part.replace(/[%#?]/g, encodeURIComponent))
           .join('/') + target.slice(raw.length),
       )
     }