zyzz 0.0.23 → 0.0.25

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, 29, 30, 31, 32, 33,
+      22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34,
     ].includes(data.version as number)
   )
     throw new Error('Unsupported Zyzz contract version.')
@@ -149,6 +149,22 @@ export function read(
       | 'grouped'
       | undefined
 
+    if (entry.composition !== undefined) {
+      if ((data.version as number) < 34)
+        throw new Error(
+          'Composition modes require contract version 34 or later.',
+        )
+      if (
+        entry.composition !== 'independent' &&
+        entry.composition !== 'ordered'
+      )
+        throw new Error('Invalid packed composition mode.')
+    }
+    const composition = entry.composition as
+      | 'independent'
+      | 'ordered'
+      | undefined
+
     if (entry.defaultLayer !== undefined) {
       if ((data.version as number) < 27)
         throw new Error('Default layers require contract version 27 or later.')
@@ -180,6 +196,14 @@ export function read(
         'Conflicting packed shorthand mappings for one theme identity.',
       )
 
+    if (
+      contract &&
+      (contract.composition ?? 'ordered') !== (composition ?? 'ordered')
+    )
+      throw new Error(
+        'Conflicting packed composition modes for one theme identity.',
+      )
+
     if (
       contract &&
       (contract.cssOutput ?? 'atomic') !== (cssOutput ?? 'atomic')
@@ -204,6 +228,7 @@ export function read(
         ...(entry.shorthands !== undefined
           ? { shorthands: Shorthands.read(entry.shorthands) }
           : {}),
+        ...(composition ? { composition } : {}),
         ...(cssOutput ? { cssOutput } : {}),
         ...(defaultLayer !== undefined ? { defaultLayer } : {}),
         [Token.complete]: true,
@@ -333,7 +358,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, 29, 30, 31, 32, 33,
+          27, 28, 29, 30, 31, 32, 33, 34,
         ].includes(data.version as number) ||
         ![
           'cssFunction',
@@ -514,6 +539,14 @@ export function read(
           'Configuration CSS output disagrees with linked theme metadata.',
         )
 
+      if (
+        (options.composition ?? 'ordered') !==
+        (definition[Token.definition].contract.composition ?? 'ordered')
+      )
+        throw new Error(
+          'Configuration composition disagrees with linked theme metadata.',
+        )
+
       if (
         options.defaultLayer !==
         definition[Token.definition].contract.defaultLayer
@@ -829,6 +862,9 @@ export function write(
           ...(theme[Token.definition].contract.defaultLayer !== undefined
             ? { defaultLayer: theme[Token.definition].contract.defaultLayer }
             : {}),
+          ...(theme[Token.definition].contract.composition
+            ? { composition: theme[Token.definition].contract.composition }
+            : {}),
           ...(theme[Token.definition].contract.cssOutput
             ? { cssOutput: theme[Token.definition].contract.cssOutput }
             : {}),
@@ -843,13 +879,29 @@ export function write(
         },
       ]),
     ),
-    version: Object.values(links).some(nativeCatalog)
-      ? 33
-      : Object.values(links).some(nativeProvider)
-        ? 32
-        : 31,
+    version: (() => {
+      if (
+        Object.values(themes).some(
+          (theme) => theme[Token.definition].contract.composition,
+        ) ||
+        Object.values(links).some(composed)
+      )
+        return 34
+
+      if (Object.values(links).some(nativeCatalog)) return 33
+      if (Object.values(links).some(nativeProvider)) return 32
+
+      return 31
+    })(),
   })
 
+  function composed(link: Themes.Link): boolean {
+    return (
+      Boolean(link.style?.style.composition) ||
+      Object.values(link.members ?? {}).some(composed)
+    )
+  }
+
   function nativeProvider(link: Themes.Link): boolean {
     return (
       link.call.nativeProvider === true ||

package/src/compiler/internal/PackedStyles.ts

@@ -160,7 +160,16 @@ export function read(
       item.cssOutput !== 'grouped'
     )
       throw new Error('Invalid packed style CSS output mode.')
+    if (
+      item.composition !== undefined &&
+      (version < 34 ||
+        (item.composition !== 'independent' && item.composition !== 'ordered'))
+    )
+      throw new Error('Invalid packed style composition mode.')
     return {
+      ...(item.composition
+        ? { composition: item.composition as 'independent' | 'ordered' }
+        : {}),
       ...(item.cssOutput
         ? { cssOutput: item.cssOutput as 'atomic' | 'grouped' }
         : {}),

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'

package/src/internal/Configuration.ts

@@ -63,7 +63,8 @@ export function create(
           ? (value as Vars.Definition)
           : Vars.define(value as Vars.Values)
       const theme = VariableSets.theme(definition, variableMappings)
-      if (variableMappings === false) return theme
+      // Tokens are ambiguous only through an explicit mapping, so skip the property scan without one.
+      if (!variableMappings) return theme
       const metadata = theme[Token.definition]
       const names = new Map<string, string>()
       for (const path of Object.keys(metadata.values)) {
@@ -149,6 +150,7 @@ export function create(
   for (const key of Object.keys(input))
     if (
       ![
+        'composition',
         'cssOutput',
         'id',
         'defaultLayer',
@@ -189,6 +191,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.')
 
@@ -252,6 +261,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 }
       : {}),
@@ -451,6 +463,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. */
@@ -836,6 +853,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/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),
       )
     }

package/src/node/Host.ts

@@ -12,7 +12,10 @@ import { ResolverFactory } from 'oxc-resolver'
 import * as Graph from '../compiler/Graph.js'
 import * as AtRules from '../compiler/internal/AtRules.js'
 import * as Catalogs from '../compiler/internal/Catalogs.js'
+import * as ClassName from '../web/internal/ClassName.js'
+import * as Contracts from './internal/Contracts.js'
 import * as Relative from '../compiler/internal/Relative.js'
+import * as Scheme from '../internal/Scheme.js'
 import * as Snapshot from './internal/Snapshot.js'
 import * as Syntax from '../compiler/internal/Syntax.js'
 import * as Source from '../compiler/Source.js'
@@ -134,6 +137,7 @@ export async function create(options: create.Options): Promise<Runtime> {
   const manifestPath = Path.join(outDir, '.zyzz.json')
 
   const compiler = Graph.create()
+  const packages = Contracts.create()
   const snapshot = Snapshot.create()
   const stylesheets = new WeakMap<Transform.compile.ReturnType, Stylesheet>()
   let closed = false
@@ -315,18 +319,16 @@ export async function create(options: create.Options): Promise<Runtime> {
     async function contract(file: string, required = false): Promise<boolean> {
       if (Object.hasOwn(contracts, file)) return true
 
-      observe(`${file}.zyzz.json`)
-      try {
-        contracts[file] = await snapshot.read(`${file}.zyzz.json`)
-      } catch (error) {
-        if (
-          !required &&
-          !previousContracts.has(file) &&
-          (error as NodeJS.ErrnoException).code === 'ENOENT'
-        )
-          return false
-        throw error
-      }
+      const source = await packages.read(file, {
+        read(path) {
+          observe(path)
+          return snapshot.read(path)
+        },
+        required: required || previousContracts.has(file),
+        resolve: async (specifier, importer) => resolve(specifier, importer),
+      })
+      if (source === undefined) return false
+      contracts[file] = source
 
       const metadata = (() => {
         try {
@@ -459,6 +461,7 @@ export async function create(options: create.Options): Promise<Runtime> {
     }
 
     const graph = compiler.compile({
+      [ClassName.complete]: true,
       [ThemeRules.shared]:
         options.modules === false && !native ? 'all' : undefined,
       [Syntax.cache]: snapshot.programs(modules),
@@ -469,13 +472,7 @@ export async function create(options: create.Options): Promise<Runtime> {
       imports,
     })
 
-    snapshot.retain(
-      new Set([
-        ...inputs,
-        ...Object.keys(contracts).map((file) => `${file}.zyzz.json`),
-      ]),
-      modules,
-    )
+    snapshot.retain(new Set([...inputs, ...observed]), modules)
 
     const artifactNames = [
       'zyzz.css',
@@ -620,7 +617,10 @@ export async function create(options: create.Options): Promise<Runtime> {
       artifacts.set('zyzz.shared.css.map', shared.map)
     }
 
-    const moduleStylesheets = new Map<string, Stylesheet>()
+    const moduleStylesheets = new Map<
+      string,
+      { name: string; stylesheet: Stylesheet }
+    >()
 
     for (const name of Object.keys(sources)) {
       const output = graph.modules[`${options.packageId}/${name}`]!
@@ -661,23 +661,46 @@ export async function create(options: create.Options): Promise<Runtime> {
 
       artifacts.set(`${name}.css`, stylesheet.code)
       artifacts.set(`${name}.css.map`, stylesheet.map)
-      // Module URLs resolve beside the module file; the complete stylesheet at
-      // the output root carries a copy with those URLs rebased.
-      moduleStylesheets.set(
-        `${options.packageId}/${name}`,
-        rebase(stylesheet, name, css === false ? false : css.minify),
-      )
+      moduleStylesheets.set(`${options.packageId}/${name}`, {
+        name,
+        stylesheet,
+      })
     }
 
     // The complete stylesheet follows the module graph so a consumer's rules
     // cascade over the rules of the modules it imports.
     if (shared || moduleStylesheets.size) {
-      const complete = concatenate([
-        ...(shared ? [shared] : []),
-        ...order(graph.dependencies, [...moduleStylesheets.keys()]).map(
-          (id) => moduleStylesheets.get(id)!,
-        ),
-      ])
+      const parts = shared ? [shared] : []
+      const units = new Set<string>()
+      let schemes = false
+
+      // Each module stylesheet declares the scheme classes and shared rules it
+      // uses to load alone. The complete stylesheet keeps the first declaration.
+      for (const id of order(graph.dependencies, [
+        ...moduleStylesheets.keys(),
+      ])) {
+        const { name, stylesheet } = moduleStylesheets.get(id)!
+        const declares = Object.values(Scheme.classes).some((className) =>
+          stylesheet.code.includes(`.${className}`),
+        )
+        const names = [
+          ...(graph.modules[id]![ClassName.units]?.values() ?? []),
+        ].map((decision) => decision.name)
+
+        parts.push(
+          rebase(
+            stylesheet,
+            name,
+            css === false ? false : css.minify,
+            schemes && declares,
+            new Set(names.filter((name) => units.has(name))),
+          ),
+        )
+        schemes ||= declares
+        for (const name of names) units.add(name)
+      }
+
+      const complete = concatenate(parts)
 
       artifacts.set('zyzz.css', complete.code)
       artifacts.set('zyzz.css.map', complete.map)
@@ -1025,7 +1048,7 @@ function concatenate(parts: readonly { code: string; map: string }[]) {
   let offset = 0
 
   for (const part of parts) {
-    if (!part.code) continue
+    if (!part.code.trim()) continue
 
     const code = part.code.endsWith('\n') ? part.code : `${part.code}\n`
     const traced = Mapping.fromMap(part.map)
@@ -1169,15 +1192,27 @@ async function read(
   }
 }
 
-/** Rewrites a nested module stylesheet's relative URLs against the output root. */
+/**
+ * Copies a module stylesheet into the complete stylesheet at the output root,
+ * rebasing nested relative URLs and optionally dropping the scheme rules.
+ */
 function rebase(
   stylesheet: { code: string; map: string },
   name: string,
   minify: boolean,
+  schemes: boolean,
+  emitted: ReadonlySet<string>,
 ) {
   const directory = Path.posix.dirname(name)
 
-  if (directory === '.' || !stylesheet.code.includes('url(')) return stylesheet
+  if (
+    !schemes &&
+    !emitted.size &&
+    (directory === '.' || !stylesheet.code.includes('url('))
+  )
+    return stylesheet
+
+  const classes = Object.values(Scheme.classes)
 
   const result = AtRules.transform({
     code: Buffer.from(stylesheet.code),
@@ -1186,8 +1221,27 @@ function rebase(
     minify,
     sourceMap: true,
     visitor: {
+      Rule: {
+        style(rule) {
+          const [selector, ...others] = rule.value.selectors
+          const [component, ...rest] = selector ?? []
+
+          if (
+            !others.length &&
+            !rest.length &&
+            component?.type === 'class' &&
+            ((schemes && classes.includes(component.name)) ||
+              emitted.has(component.name))
+          )
+            return []
+        },
+      },
       Url(url) {
-        if (/^(?:\/|[?#]|[a-z][a-z\d+.-]*:)/i.test(url.url)) return url
+        if (
+          directory === '.' ||
+          /^(?:\/|[?#]|[a-z][a-z\d+.-]*:)/i.test(url.url)
+        )
+          return url
 
         return { ...url, url: Path.posix.join(directory, url.url) }
       },