zyzz 0.0.5 → 0.0.7

package/src/Style.ts

@@ -68,13 +68,20 @@ export type Accepted<
                   ? never
                   : Value.Atom<Typography.Names<tokens>>
                 : key extends keyof Literal.Properties
-                  ? Value.Accepted<
-                      Pick<style, key>,
-                      literal extends true
+                  ? (literal extends true
+                      ? LiteralDeclarations
+                      : keyof tokens extends never
                         ? LiteralDeclarations
-                        : DeclarationProperties<tokens>
-                    >[key] &
-                      Value.Checked<Pick<style, key>, tokens>[key]
+                        : DeclarationProperties<tokens>)[key] extends style[key]
+                    ? style[key]
+                    : Value.Accepted<
+                        Pick<style, key>,
+                        literal extends true
+                          ? LiteralDeclarations
+                          : DeclarationProperties<tokens>
+                      >[key] &
+                        Value.Checked<Pick<style, key>, tokens>[key] &
+                        Value.Tokens<style[key], tokens, key>
                   : key extends Condition.Keys<tokens, key>
                     ? [style[key]] extends [undefined]
                       ? never
@@ -605,10 +612,11 @@ export function define(
           )
           continue
         }
+        const custom = parsed?.custom
         const scalar = parsed ? parsed.value : entry
 
         const resolved = (() => {
-          if (!theme) return scalar
+          if (!theme || custom) return scalar
 
           if (typeof scalar !== 'string' && typeof scalar !== 'number')
             return scalar
@@ -645,6 +653,25 @@ export function define(
           continue
         }
 
+        if (
+          theme &&
+          !custom &&
+          Token.mapped(theme, key) &&
+          !Token.is(resolved) &&
+          !(Binding.is(resolved) && !resolved.name.startsWith('--z-d')) &&
+          !(
+            Token.isExpression(resolved) &&
+            resolved.parts.every((part) => Token.is(part) || part === '')
+          )
+        ) {
+          report(
+            'invalid_value',
+            [name, authoredProperty],
+            'Expected a configured token or a bracketed CSS value.',
+          )
+          continue
+        }
+
         const value = parsed && resolved === '0' ? 0 : resolved
 
         declarations.push(
@@ -774,6 +801,7 @@ export class InvalidError extends Error {
 type LiteralAtoms = {
   readonly [property in keyof Literal.Properties]-?: Value.Atom<
     | Exclude<Literal.Properties[property], undefined>
+    | `[${string}]`
     | Binding.Reference<'*'>
     | {
         [kind in Binding.Kind]: property extends Binding.Property<
@@ -812,7 +840,13 @@ export type NamedStyle<name extends string = string> = {
 /** Supported literal and token declarations. Unknown properties and undefined values are rejected. */
 export type DeclarationProperties<tokens extends Theme.Tokens = {}> = {
   readonly [property in keyof Literal.Properties]: Value.Fallbacks<
-    | LiteralAtoms[property]
+    | (property extends `--${string}`
+        ? LiteralAtoms[property]
+        : [Token.Names<tokens, property>] extends [never]
+          ? LiteralAtoms[property]
+          :
+              | Value.Atom<`[${string}]`>
+              | Extract<LiteralAtoms[property], Binding.Reference>)
     | Value.Atom<Token.Names<tokens, property>>
     | {
         [group in Token.Group]: property extends Token.Properties<group>

package/src/babel/index.ts

@@ -36,6 +36,8 @@ export type WebOptions = {
   readonly cssOutput?: Transform.compile.Options['cssOutput']
   /** Portable identity. Defaults to the filename relative to Babel's root. */
   readonly moduleId?: string | undefined
+  /** Import the CSS reset once per transformed module. Defaults to false. */
+  readonly reset?: boolean | undefined
   /** Selects rewritten JavaScript and extracted CSS. */
   readonly target: 'web'
 }
@@ -326,7 +328,27 @@ export function zyzz(api: typeof Babel, options: Options): Babel.PluginObj {
     visitor:
       options.target !== 'web' && options.colorScheme === undefined
         ? NativeJsx.visitor(api, callables)
-        : {},
+        : {
+            Program(path) {
+              if (options.target !== 'web' || !options.reset) return
+              if (
+                path.node.body.some(
+                  (node) =>
+                    node.type === 'ImportDeclaration' &&
+                    node.source.value === 'zyzz/reset.css',
+                )
+              )
+                return
+
+              path.unshiftContainer(
+                'body',
+                api.types.importDeclaration(
+                  [],
+                  api.types.stringLiteral('zyzz/reset.css'),
+                ),
+              )
+            },
+          },
   }
   return plugin
 }

package/src/compiler/Graph.ts

@@ -65,6 +65,8 @@ export declare namespace compile {
       | undefined
     /** Complete source graph keyed by stable package-relative module identities. */
     readonly modules: Readonly<Record<string, string>>
+    /** Optional reset stylesheet supplied by the host, ordered before authored layers. */
+    readonly reset?: string | undefined
   }
 
   /** Compiled modules and their direct source dependencies. */
@@ -119,6 +121,7 @@ type Cache = {
   development: boolean
   extracted: ReadonlyMap<string, Source.extract.ReturnType>
   libraries: Readonly<Record<string, ReturnType<typeof Contract.read>>>
+  reset: string | undefined
   resolutions: Readonly<Record<string, string>>
   native: compile.Options['native']
   result: compile.ReturnType
@@ -148,11 +151,16 @@ function build(options: compile.Options, cache?: Cache): Cache {
     })
   )
     cache = undefined
+  if (options.native && options.reset !== undefined)
+    throw new Native.CompileError(
+      'The CSS reset is only supported by web builds.',
+    )
   if (options.native && options.compiler === false)
     throw new Native.CompileError(
       'Native graph compilation requires source rewriting.',
     )
   if (cache?.compiler !== (options.compiler !== false)) cache = undefined
+  if (cache?.reset !== options.reset) cache = undefined
   if (cache?.cssOutput !== options.cssOutput) cache = undefined
   if (cache?.composition !== options.composition) cache = undefined
   const ids = Object.keys(options.modules).sort()
@@ -1063,6 +1071,7 @@ function build(options: compile.Options, cache?: Cache): Cache {
         ...(options.native.vars && { vars: { ...options.native.vars } }),
         ...(options.native.units && { units: { ...options.native.units } }),
       },
+      reset: options.reset,
       resolutions: Object.freeze(resolutions),
       result: Object.freeze({
         contracts: Object.freeze(
@@ -1244,6 +1253,7 @@ function build(options: compile.Options, cache?: Cache): Cache {
     try {
       const sharedSections = ids.flatMap((id) => reachable(id, sharedVisited))
       const resetSource =
+        (options.reset === undefined ? undefined : 'zyzz/reset.css') ??
         resetOwners[0] ??
         sharedSections.find((section) => section.key === 'optional-reset-order')
           ?.source
@@ -1262,6 +1272,17 @@ function build(options: compile.Options, cache?: Cache): Cache {
               },
             ]),
         ...sharedSections,
+        ...(options.reset === undefined
+          ? []
+          : [
+              {
+                source: 'zyzz/reset.css',
+                key: 'optional-reset',
+                css: options.reset,
+                content: options.reset,
+                layers: [['reset']],
+              },
+            ]),
       ])
     } catch (error) {
       return fail(
@@ -1509,6 +1530,7 @@ function build(options: compile.Options, cache?: Cache): Cache {
     extracted,
     libraries: Object.freeze(libraries),
     native: undefined,
+    reset: options.reset,
     resolutions: Object.freeze(resolutions),
     result: Object.freeze({
       ...(sharedCss

package/src/compiler/Source.ts

@@ -471,7 +471,10 @@ export function extract(options: extract.Options): extract.ReturnType {
 
   pending.sort((a, b) => a.start - b.start)
 
-  const staticCalls = new Set(pending.map((call) => call.start))
+  const staticCalls = new Set([
+    ...pending.map((call) => call.start),
+    ...contributions.calls.map((call) => call.start),
+  ])
   const opaque = new Set(variables.references.keys())
   const normalized = new Map<number, Ast.Node | Error>()
   const selectorKeys = new Set<number>()
@@ -1365,6 +1368,7 @@ export function extract(options: extract.Options): extract.ReturnType {
         contributions,
         themes?.tokens ?? new Map(),
         contributionStarts,
+        (node) => staticData.resolve(node, staticCalls),
       ),
       ...(themes?.calls ?? []).flatMap((call) =>
         call.options?.layers

package/src/compiler/internal/Contributions.ts

@@ -506,12 +506,13 @@ export function extract(
   scanned: ReturnType<typeof scan>,
   tokens: ReadonlyMap<number, { end: number; reference: Token.Reference }>,
   starts?: number[],
+  resolve: (node: Ast.Node) => Ast.Node = Expression.unwrap,
 ): readonly Css.Contribution[] {
   const result: Css.Contribution[] = []
   function value(node: Ast.Node, property?: string): unknown {
     const reference = tokens.get(node.start)
     if (reference?.end === node.end) return reference.reference
-    node = Expression.unwrap(node)
+    node = Expression.unwrap(resolve(node))
 
     const animation = scanned.references.get(node.start)
     if (animation) return animation
@@ -545,7 +546,9 @@ export function extract(
 
     if (node.type === 'TemplateLiteral') {
       const template = Expression.template(node, 0, (expression, prefix) => {
-        const node = Expression.unwrap(expression)
+        const node = Expression.unwrap(resolve(expression))
+        if (node.type === 'Literal' && typeof node.value === 'string')
+          return node.value
         const name = scanned.references.get(node.start)
         const kind = name ? scanned.kinds.get(name) : undefined
         if (

package/src/compiler/internal/Static.ts

@@ -117,6 +117,7 @@ export function create(
       const binding = scope.getDeclaration(node.name) ?? null
       if (!binding && node.name === 'undefined') absent.add(node.start)
       if (!binding || !values.has(binding.node.start)) return binding
+      if (ancestors.some((node) => node.type === 'TSTypeQuery')) return binding
 
       references.set(node.start, binding.node.start)
       const value = Expression.unwrap(values.get(binding.node.start)!)

package/src/internal/Authoring.ts

@@ -74,6 +74,10 @@ export function create(
   if (!dynamic && !id && Object.keys(input as object).length === 0)
     Identity.requireId(undefined, 'Empty style')
 
+  if (id && !dynamic && options.theme)
+    Style.define({ style: body(input as Record<string, unknown>) } as never, {
+      vars: options.theme,
+    })
   const className = id
     ? `z-style-${id}`
     : Identity.style(
@@ -125,6 +129,23 @@ export function variants(
   options: Options = {},
 ): unknown {
   const id = Identity.requireId(options.id, 'variants')
+  if (options.theme) {
+    const styles = [
+      input.base,
+      ...Object.values(
+        (input.variants ?? {}) as Record<string, Record<string, unknown>>,
+      ).flatMap(Object.values),
+      ...((input.compoundVariants ?? []) as readonly { style: unknown }[]).map(
+        (entry) => entry.style,
+      ),
+    ]
+    for (const input of styles)
+      if (input && typeof input === 'object')
+        Style.define(
+          { style: body(input as Record<string, unknown>) } as never,
+          { vars: options.theme },
+        )
+  }
   const className = `z-style-${id}`
   const axes = Object.entries(
     (input.variants ?? {}) as Record<string, Record<string, unknown>>,

package/src/internal/Binding.ts

@@ -127,6 +127,36 @@ export type Checked<style> = {
         : unknown
 }
 
+/** Excludes token-name slots, which cannot resolve token names during application. */
+export type TokenSlots<style, values, tokens, mappings = {}> = {
+  [property in keyof style]: property extends keyof Literal.Properties
+    ? SlotValue<
+        style[property],
+        values[keyof values],
+        Token.Names<tokens, property>
+      >
+    : property extends keyof mappings
+      ? mappings[property] extends readonly (infer target extends
+          keyof Literal.Properties)[]
+        ? SlotValue<
+            style[property],
+            values[keyof values],
+            Token.Names<tokens, target>
+          >
+        : unknown
+      : property extends 'vars'
+        ? unknown
+        : style[property] extends Record<string, unknown>
+          ? TokenSlots<style[property], values, tokens, mappings>
+          : unknown
+}
+
+type SlotValue<value, inputs, names> = value extends readonly unknown[]
+  ? { [key in keyof value]: SlotValue<value[key], inputs, names> }
+  : Extract<Extract<value, inputs>, names> extends never
+    ? unknown
+    : never
+
 /** Rejects reserved callback field names and importance-bearing value domains. */
 export type Inputs<values> = {
   [key in keyof values]: key extends

package/src/internal/Configuration.ts

@@ -277,14 +277,16 @@ export function create(
       })
     }
   }
-  function boundVariants(
-    definition: Record<string, unknown>,
-    options: style.DefinitionOptions = {},
-  ) {
-    return Authoring.variants(definition, {
-      ...options,
-      output: input.output as style.Output | undefined,
-    })
+  function boundVariants(theme?: Theme.Definition) {
+    return (
+      definition: Record<string, unknown>,
+      options: style.DefinitionOptions = {},
+    ) =>
+      Authoring.variants(definition, {
+        ...options,
+        output: input.output as style.Output | undefined,
+        theme,
+      })
   }
   function handle(theme: Theme.Definition, name: string) {
     const original = Token.bind(theme, contract)
@@ -313,7 +315,7 @@ export function create(
     })
     Object.assign(select, {
       style: boundStyle(original),
-      variants: boundVariants,
+      variants: boundVariants(original),
     })
     return select
   }
@@ -410,7 +412,9 @@ export function create(
       ),
       theme: bound[input.defaultTheme],
       themes: Object.freeze(select),
-      variants: boundVariants,
+      variants: boundVariants(
+        bound[input.defaultTheme] as unknown as Theme.Definition,
+      ),
     })
   }
 
@@ -424,7 +428,7 @@ export function create(
       script: Appearance.create([], { storageKey }),
       style: boundStyle(theme as unknown as Theme.Definition),
       theme,
-      variants: boundVariants,
+      variants: boundVariants(theme as unknown as Theme.Definition),
     })
   }
 
@@ -436,7 +440,7 @@ export function create(
     appearance: Appearance.root([], { storageKey }),
     script: Appearance.create([], { storageKey }),
     style: boundStyle(theme),
-    variants: boundVariants,
+    variants: boundVariants(theme),
   })
 }
 
@@ -590,7 +594,9 @@ export type StyleFactory<
         values: values,
       ) => styles &
         NoInfer<
-          Body<styles, tokens, layers, mappings> & Binding.Checked<styles>
+          Body<styles, tokens, layers, mappings> &
+            Binding.Checked<styles> &
+            Binding.TokenSlots<styles, values, tokens, mappings>
         >) &
       Completion.Properties<tokens, NoInfer<styles>>,
     ...options: Parameters<callback> extends [Record<string, string | number>]

package/src/internal/Theme.ts

@@ -30,7 +30,11 @@ export type StyleFactory<tokens extends Tokens> = {
     styles: ((
       values: values,
     ) => styles &
-      NoInfer<Style.Accepted<styles, tokens> & Binding.Checked<styles>>) &
+      NoInfer<
+        Style.Accepted<styles, tokens> &
+          Binding.Checked<styles> &
+          Binding.TokenSlots<styles, values, tokens>
+      >) &
       (values extends Binding.Inputs<values> ? unknown : never),
     options?: style.DefinitionOptions,
   ): style.Dynamic<values>

package/src/internal/Token.ts

@@ -444,11 +444,11 @@ export type Reference<group extends Group = Group> = {
 
 const reference = Symbol('zyzz.token')
 
-/** Resolves shorthand tokens with literal precedence, with specific colors first. */
+/** Resolves configured token names, with specific color groups first. */
 export function resolve(value: unknown, options: resolve.Options): unknown {
   if (
-    (typeof value !== 'string' && typeof value !== 'number') ||
-    Literal.isLiteral(options.property, value)
+    options.property.startsWith('--') ||
+    (typeof value !== 'string' && typeof value !== 'number')
   )
     return value
 
@@ -529,6 +529,37 @@ export function resolve(value: unknown, options: resolve.Options): unknown {
   return value
 }
 
+/** Whether the configured catalog supplies tokens for a property. */
+export function mapped(
+  theme: object,
+  property: keyof Literal.Properties,
+): boolean {
+  if (property.startsWith('--')) return false
+  const data = Object.getOwnPropertyDescriptor(theme, definition)
+    ?.value as Metadata
+  return Object.keys(data.values).some((path) => {
+    const category = path.split('.')[0]!
+    const targets =
+      data.contract.mappings === false
+        ? undefined
+        : data.contract.mappings?.[category]
+    if (
+      data.contract.mappings !== false &&
+      !(targets
+        ? targets.includes(property)
+        : accepts(category as Group, property))
+    )
+      return false
+    let leaf: unknown = Object.getOwnPropertyDescriptor(theme, 'tokens')?.value
+    for (const key of path.split('.'))
+      leaf =
+        leaf && typeof leaf === 'object'
+          ? Object.getOwnPropertyDescriptor(leaf, key)?.value
+          : undefined
+    return is(leaf) && acceptsReference(leaf, property)
+  })
+}
+
 /** Input contract for theme token resolution. */
 export declare namespace resolve {
   /** Property domain and immutable theme metadata supplied by style validation. */