zyzz 0.0.24 → 0.0.25

package/src/compiler/internal/Applications.ts

@@ -34,6 +34,10 @@ export function create(
     }
     direct: Source.Call | undefined
     members: Map<string, Source.Call>
+    /** Namespace statement start and member identifier ends by extracted name. */
+    namespace?: Namespace | undefined
+    /** Offset after which top-level reads observe an initialized binding. */
+    ready: number
   }[] = []
 
   for (const statement of program.body) {
@@ -43,6 +47,7 @@ export function create(
       statement.body?.type === 'TSModuleBlock'
     ) {
       const members = new Map<string, Source.Call>()
+      const ends = new Map<string, number>()
       let valid = true
 
       for (const member of statement.body.body) {
@@ -71,6 +76,7 @@ export function create(
           }
 
           members.set(declaration.id.name, call)
+          ends.set(call.name, declaration.id.end)
           memberBindings.set(declaration.id.start, call.name)
         }
       }
@@ -80,6 +86,8 @@ export function create(
           declaration: { id: statement.id },
           direct: undefined,
           members,
+          namespace: { ends, start: statement.start },
+          ready: statement.end,
         })
 
       continue
@@ -142,6 +150,7 @@ export function create(
         declaration: { ...declaration, id: declaration.id },
         direct,
         members,
+        ready: declaration.end,
       })
     }
   }
@@ -149,6 +158,9 @@ export function create(
   if (!candidates.length) return undefined
 
   const lexical = new Set<Ast.Node>()
+  // Reads inside functions, classes, or namespaces may run before initialization.
+  const deferred = new Set<Ast.Node>()
+  const terminals = new Set<Ast.Node>()
   const scope = new Scope.Tracker({ preserveExitedScopes: true })
   Walker.walk(program, { scopeTracker: scope })
   scope.freeze()
@@ -185,8 +197,23 @@ export function create(
         candidates.some(
           (candidate) => candidate.declaration.id.start === id.start,
         )
-      )
+      ) {
         lexical.add(node)
+        if (terminal(ancestors)) terminals.add(node)
+        if (
+          ancestors.some((node) =>
+            [
+              'ArrowFunctionExpression',
+              'ClassDeclaration',
+              'ClassExpression',
+              'FunctionDeclaration',
+              'FunctionExpression',
+              'TSModuleDeclaration',
+            ].includes(node.type),
+          )
+        )
+          deferred.add(node)
+      }
     },
     leave() {
       ancestors.pop()
@@ -200,6 +227,80 @@ export function create(
   >(candidates.map(({ declaration }) => [declaration.id.name, []]))
   let evaluation = false
 
+  // Returns undefined when any read escapes. Recipes, dynamic styles, and
+  // applications with overrides keep their runtime calls.
+  function collect(candidate: (typeof candidates)[number]):
+    | {
+        readonly applications: readonly Application[]
+        readonly called: ReadonlySet<string>
+      }
+    | undefined {
+    const { declaration, direct, members } = candidate
+    const applications: Application[] = []
+    const called = new Set<string>()
+
+    for (const reference of references.get(declaration.id.name) ?? []) {
+      if (reference === declaration.id) continue
+
+      let callee: Ast.Node = reference
+      let call = direct
+
+      if (!direct) {
+        const member = parents.get(reference)
+
+        if (
+          member?.type !== 'MemberExpression' ||
+          member.object !== reference ||
+          member.computed ||
+          member.optional ||
+          member.property.type !== 'Identifier'
+        )
+          return undefined
+
+        call = members.get(member.property.name)
+        callee = member
+      }
+
+      if (
+        call?.composition ||
+        call?.runtimeComposition ||
+        (!options.dynamic && (call?.slots || call?.recipe))
+      )
+        continue
+
+      const application = parents.get(callee)
+
+      if (
+        !call ||
+        application?.type !== 'CallExpression' ||
+        application.callee !== callee ||
+        application.optional
+      )
+        return undefined
+
+      // An override needs the runtime callable, but exposes no other definition.
+      if (!options.dynamic && application.arguments.length) {
+        called.add(call.name)
+        continue
+      }
+
+      applications.push({
+        calleeEnd: callee.end,
+        end: application.end,
+        initialized:
+          !deferred.has(reference) &&
+          reference.start >= candidate.ready &&
+          (!candidate.namespace ||
+            namespaceCounts.get(declaration.id.name) === 1),
+        name: call.name,
+        start: application.start,
+        terminal: terminals.has(reference),
+      })
+    }
+
+    return { applications, called }
+  }
+
   return {
     dead() {
       if (evaluation) return new Set<string>()
@@ -255,6 +356,58 @@ export function create(
 
       return result
     },
+    definitions() {
+      const namespaces: Namespace[] = []
+      const values = new Map<string, boolean>()
+
+      if (evaluation) return { namespaces, values }
+
+      const counts = new Map<string, number>()
+
+      for (const { declaration } of candidates)
+        counts.set(
+          declaration.id.name,
+          (counts.get(declaration.id.name) ?? 0) + 1,
+        )
+
+      for (const candidate of candidates) {
+        const name = candidate.declaration.id.name
+        if (counts.get(name)! > 1 || (namespaceCounts.get(name) ?? 0) > 1)
+          continue
+
+        const result = collect(candidate)
+        if (!result) continue
+
+        let erased = !!candidate.namespace
+
+        for (const call of candidate.direct
+          ? [candidate.direct]
+          : candidate.members.values()) {
+          if (
+            call.composition ||
+            call.runtimeComposition ||
+            call.slots ||
+            call.recipe ||
+            result.called.has(call.name)
+          ) {
+            erased = false
+            continue
+          }
+
+          const initialized = result.applications.every(
+            (application) =>
+              application.name !== call.name || application.initialized,
+          )
+
+          values.set(call.name, initialized)
+          erased &&= initialized
+        }
+
+        if (erased) namespaces.push(candidate.namespace!)
+      }
+
+      return { namespaces, values }
+    },
     enter(node, parent) {
       if (
         node.type === 'MemberExpression' &&
@@ -280,68 +433,9 @@ export function create(
     find() {
       if (evaluation) return []
 
-      const result: Application[] = []
-
-      for (const { declaration, direct, members } of candidates) {
-        const applications: Application[] = []
-        let valid = true
-
-        for (const reference of references.get(declaration.id.name) ?? []) {
-          if (reference === declaration.id) continue
-
-          let callee: Ast.Node = reference
-          let call = direct
-
-          if (!direct) {
-            const member = parents.get(reference)
-
-            if (
-              member?.type !== 'MemberExpression' ||
-              member.object !== reference ||
-              member.computed ||
-              member.optional ||
-              member.property.type !== 'Identifier'
-            ) {
-              valid = false
-              break
-            }
-
-            call = members.get(member.property.name)
-            callee = member
-          }
-
-          if (
-            call?.composition ||
-            call?.runtimeComposition ||
-            (!options.dynamic && (call?.slots || call?.recipe))
-          )
-            continue
-
-          const application = parents.get(callee)
-
-          if (
-            !call ||
-            application?.type !== 'CallExpression' ||
-            application.callee !== callee ||
-            application.optional ||
-            (!options.dynamic && application.arguments.length)
-          ) {
-            valid = false
-            break
-          }
-
-          applications.push({
-            calleeEnd: callee.end,
-            end: application.end,
-            name: call.name,
-            start: application.start,
-          })
-        }
-
-        if (valid) result.push(...applications)
-      }
-
-      return result
+      return candidates.flatMap(
+        (candidate) => collect(candidate)?.applications ?? [],
+      )
     },
   }
 }
@@ -352,16 +446,37 @@ type Application = {
   readonly calleeEnd: number
   /** End of the application. */
   readonly end: number
+  /** Whether the read runs at top level after its definition initializes. */
+  readonly initialized: boolean
   /** Extracted class identity. */
   readonly name: string
   /** Start of the application. */
   readonly start: number
+  /** Whether a DOM element receives the props alone, so its classes meet no other style's. */
+  readonly terminal: boolean
+}
+
+/** A top-level namespace whose members are all static definitions. */
+type Namespace = {
+  /** Member identifier ends keyed by extracted name. */
+  readonly ends: ReadonlyMap<string, number>
+  /** Start of the namespace statement. */
+  readonly start: number
 }
 
 /** Binding references gathered during the transform's existing walk. */
 type Collector = {
   /** Definitions with no observable value reads, retaining escaped containers. */
   dead: () => ReadonlySet<string>
+  /**
+   * Static definitions whose every read is a found application, keyed by
+   * extracted name with whether every read is initialized. Namespaces list
+   * those whose definitions all qualify with initialized reads.
+   */
+  definitions: () => {
+    readonly namespaces: readonly Namespace[]
+    readonly values: ReadonlyMap<string, boolean>
+  }
   /** Records relevant reads and their immediate parents. */
   enter: (node: Ast.Node, parent: Ast.Node | null | undefined) => void
   /** Resolves applications after traversal completes. */
@@ -376,3 +491,64 @@ export declare namespace create {
     readonly dynamic?: boolean | undefined
   }
 }
+
+// Matches a no-argument application spread onto, or read as the class of, a DOM element.
+function terminal(path: readonly Ast.Node[]): boolean {
+  let index = path.length - 1
+  let node = path[index]
+  const member = path[index - 1]
+  if (member?.type === 'MemberExpression' && member.object === node)
+    node = path[--index]
+
+  const call = path[--index]
+  if (
+    call?.type !== 'CallExpression' ||
+    call.callee !== node ||
+    call.arguments.length
+  )
+    return false
+
+  const parent = path[--index]
+  if (parent?.type === 'JSXSpreadAttribute')
+    return parent.argument === call && alone(path[index - 1], parent)
+
+  if (
+    parent?.type !== 'MemberExpression' ||
+    parent.object !== call ||
+    parent.computed ||
+    parent.property.type !== 'Identifier' ||
+    !/^class(?:Name)?$/.test(parent.property.name)
+  )
+    return false
+
+  const container = path[--index]
+  const attribute = path[--index]
+  return (
+    container?.type === 'JSXExpressionContainer' &&
+    container.expression === parent &&
+    attribute?.type === 'JSXAttribute' &&
+    attribute.value === container &&
+    attribute.name.type === 'JSXIdentifier' &&
+    /^class(?:Name)?$/.test(attribute.name.name) &&
+    alone(path[index - 1], attribute)
+  )
+}
+
+// Other spreads or class attributes could add another style's classes.
+function alone(element: Ast.Node | undefined, own: Ast.Node): boolean {
+  return (
+    element?.type === 'JSXOpeningElement' &&
+    element.name.type === 'JSXIdentifier' &&
+    /^[a-z]/.test(element.name.name) &&
+    element.attributes.every(
+      (attribute) =>
+        attribute === own ||
+        (attribute.type === 'JSXAttribute' &&
+          !(
+            attribute.name.type === 'JSXIdentifier'
+              ? attribute.name.name
+              : attribute.name.namespace.name
+          ).startsWith('class')),
+    )
+  )
+}

package/src/compiler/internal/Compositions.ts

@@ -405,7 +405,15 @@ export function collect(options: collect.Options) {
         node,
       )
     const name = `composition-${options.identity}-${node.start}`
+    // A composition of independent styles keeps their sharing contract.
+    const independent = (calls: readonly Source.Call[]) =>
+      calls.every(
+        (call) => styles.get(call.name)!.composition === 'independent',
+      )
+        ? ({ composition: 'independent' } as const)
+        : {}
     const style: Style.NamedStyle = {
+      ...independent(selected),
       cssOutput: 'atomic',
       name,
       declarations: [],
@@ -580,6 +588,7 @@ export function collect(options: collect.Options) {
             .join(' '),
         },
         style: {
+          ...independent(included),
           cssOutput: 'atomic',
           name,
           declarations: [],

package/src/compiler/internal/Configurations.ts

@@ -149,6 +149,9 @@ export function collect(options: collect.Options): Themes.Link {
       : {}),
     [Token.identity]: identity,
     ...(input.id !== undefined ? { [Token.complete]: true } : {}),
+    ...(input.composition !== undefined
+      ? { composition: input.composition }
+      : {}),
     cssOutput: input.cssOutput ?? 'atomic',
     ...(input.defaultLayer !== undefined
       ? { defaultLayer: input.defaultLayer }
@@ -243,6 +246,7 @@ export function collect(options: collect.Options): Themes.Link {
       return {}
     })(),
     ...(input.id !== undefined ? { id: input.id } : {}),
+    ...(input.composition ? { composition: input.composition } : {}),
     ...(input.cssOutput ? { cssOutput: input.cssOutput } : {}),
     ...(input.defaultLayer !== undefined
       ? { defaultLayer: input.defaultLayer }

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

@@ -150,6 +150,7 @@ export function create(
   for (const key of Object.keys(input))
     if (
       ![
+        'composition',
         'cssOutput',
         'id',
         'defaultLayer',
@@ -190,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.')
 
@@ -253,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 }
       : {}),
@@ -452,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. */
@@ -837,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. */