zyzz 0.0.20 → 0.0.22

package/src/compiler/internal/Vars.ts

@@ -6,6 +6,7 @@ import * as Theme from '../../internal/Theme.js'
 import type * as Css from '../../web/Css.js'
 import * as Identity from '../../internal/Identity.js'
 import * as Expression from './Expression.js'
+import * as Names from './Names.js'
 import type * as Scope from './Scope.js'
 import type * as Themes from './Themes.js'
 import { InvalidError } from './Themes.js'
@@ -14,6 +15,8 @@ import { InvalidError } from './Themes.js'
 export type Call = {
   /** Exclusive source offset. */
   readonly end: number
+  /** Whether the consumer supplied a portable variable identity. */
+  readonly explicit?: boolean | undefined
   /** Fixed scalar reference retained in portable metadata. */
   readonly slots: Readonly<Record<string, Binding.Reference>>
   /** Inclusive source offset. */
@@ -28,6 +31,7 @@ export function collect(
   links: Readonly<Record<string, Themes.Link>> = {},
   moduleId = namespace,
 ) {
+  const authoredNames = Names.collect(program)
   const imports = new Set<number>()
   const external = new Map<number, Themes.Link>()
   for (const statement of program.body) {
@@ -187,6 +191,7 @@ export function collect(
   })
 
   const calls: Call[] = []
+  const explicit = new Set<number>()
   const definitions = new Map<number, Themes.Link>()
   const registrations: Css.Contribution[] = []
   const registrationStarts: number[] = []
@@ -275,8 +280,10 @@ export function collect(
         descriptor[key] = literal as string | number | boolean
       }
 
+    if (descriptor.id !== undefined) explicit.add(call.start)
+
     const name =
-      `--z-v${descriptor.id === undefined ? `${namespace}-${call.start}` : Identity.requireId(typeof descriptor.id === 'string' ? descriptor.id : undefined, 'variable')}` as const
+      `--z-${descriptor.id === undefined ? authoredNames.get(call.start)! : Identity.requireId(typeof descriptor.id === 'string' ? descriptor.id : undefined, 'variable').slice(3)}` as const
     if (value && Object.keys(descriptor).some((key) => key !== 'id')) {
       const syntax =
         kind === 'signedLength'
@@ -325,6 +332,7 @@ export function collect(
       variable: true as const,
     })
     const entry = Object.freeze({
+      explicit: explicit.has(call.start),
       start: call.start,
       end: call.end,
       slots: Object.freeze({ value: slot }),
@@ -469,6 +477,7 @@ export function collect(
   function reference(
     node: Extract<Ast.Node, { type: 'Identifier' | 'JSXIdentifier' }>,
     parent: Ast.Node,
+    ancestors: readonly Ast.Node[],
     binding: Walker.ScopeTrackerNode | null,
   ) {
     if (binding?.type === 'Import' && imports.has(binding.node.start))
@@ -480,7 +489,17 @@ export function collect(
           : node,
       ) ?? resolve(node)
     if (!link) return false
-    if (link.call.start >= 0 && node.start < link.call.end)
+    // Reads inside functions wait for a call, so only module-scope reads must follow the declaration.
+    if (
+      link.call.start >= 0 &&
+      node.start < link.call.end &&
+      !ancestors.some(
+        (ancestor) =>
+          ancestor.type === 'ArrowFunctionExpression' ||
+          ancestor.type === 'FunctionDeclaration' ||
+          ancestor.type === 'FunctionExpression',
+      )
+    )
       throw new InvalidError('Vars must be declared before use.', node)
     return true
   }

package/src/default.ts

@@ -41,11 +41,10 @@ void [spin, ping, pulse, bounce]
  */
 export const tokens = {
   animate: {
-    spin: 'z-kid-7a-79-7a-7a-2d-73-70-69-6e 1s linear infinite',
-    ping: 'z-kid-7a-79-7a-7a-2d-70-69-6e-67 1s cubic-bezier(0, 0, 0.2, 1) infinite',
-    pulse:
-      'z-kid-7a-79-7a-7a-2d-70-75-6c-73-65 2s cubic-bezier(0.4, 0, 0.6, 1) infinite',
-    bounce: 'z-kid-7a-79-7a-7a-2d-62-6f-75-6e-63-65 1s infinite',
+    spin: 'z-kid-zyzz_2d_spin 1s linear infinite',
+    ping: 'z-kid-zyzz_2d_ping 1s cubic-bezier(0, 0, 0.2, 1) infinite',
+    pulse: 'z-kid-zyzz_2d_pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite',
+    bounce: 'z-kid-zyzz_2d_bounce 1s infinite',
   },
   aspect: {
     video: '16 / 9',
@@ -680,13 +679,13 @@ export const tokens = {
 /** Default appearance, restoration script, and authoring helpers with bundled light/dark tokens. */
 // Generated from tokens by scripts/default-theme.ts; edit tokens and regenerate.
 const config = Config.create({
+  id: 'default',
   vars: {
     animate: {
-      spin: 'z-kid-7a-79-7a-7a-2d-73-70-69-6e 1s linear infinite',
-      ping: 'z-kid-7a-79-7a-7a-2d-70-69-6e-67 1s cubic-bezier(0, 0, 0.2, 1) infinite',
-      pulse:
-        'z-kid-7a-79-7a-7a-2d-70-75-6c-73-65 2s cubic-bezier(0.4, 0, 0.6, 1) infinite',
-      bounce: 'z-kid-7a-79-7a-7a-2d-62-6f-75-6e-63-65 1s infinite',
+      spin: 'z-kid-zyzz_2d_spin 1s linear infinite',
+      ping: 'z-kid-zyzz_2d_ping 1s cubic-bezier(0, 0, 0.2, 1) infinite',
+      pulse: 'z-kid-zyzz_2d_pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite',
+      bounce: 'z-kid-zyzz_2d_bounce 1s infinite',
     },
     aspect: {
       video: '16 / 9',

package/src/internal/Authoring.ts

@@ -3,6 +3,7 @@ import type { style } from '../styleFunction.js'
 import * as Html from '../runtime/CompositionHtml.js'
 import * as Identity from './Identity.js'
 import * as Props from '../runtime/Props.js'
+import * as Token from './Token.js'
 import * as Style from '../Style.js'
 import type * as Theme from './Theme.js'
 
@@ -66,10 +67,12 @@ export function create(
   options: Options = {},
 ): style.ReturnType {
   const dynamic = typeof input === 'function'
+  const identity = options.theme?.[Token.definition].contract[Token.identity]
+  const namespace = identity?.startsWith('id-') ? identity.slice(3) : undefined
   const id =
     options.id === undefined
       ? undefined
-      : Identity.requireId(options.id, 'style')
+      : `id-${namespace ? `${namespace}-` : ''}${Identity.requireId(options.id, 'style').slice(3)}`
   if (dynamic && !id) Identity.requireId(undefined, 'Dynamic style')
   if (!dynamic && !id && Object.keys(input as object).length === 0)
     Identity.requireId(undefined, 'Empty style')
@@ -90,6 +93,7 @@ export function create(
           { style: body(input as Record<string, unknown>) },
           { vars: options.theme },
         ).styles[0]!,
+        namespace,
       )
   const props = Props.create({ className })
   const apply = (values?: style.Options & Record<string, unknown>) => {
@@ -128,7 +132,9 @@ export function variants(
   input: Record<string, unknown>,
   options: Options = {},
 ): unknown {
-  const id = Identity.requireId(options.id, 'variants')
+  const identity = options.theme?.[Token.definition].contract[Token.identity]
+  const namespace = identity?.startsWith('id-') ? identity.slice(3) : undefined
+  const id = `id-${namespace ? `${namespace}-` : ''}${Identity.requireId(options.id, 'variants').slice(3)}`
   if (options.theme) {
     const styles = [
       input.base,

package/src/internal/Binding.ts

@@ -15,10 +15,15 @@ export type Kind =
   | 'signedLength'
   | 'signedPercentage'
 
+/** Marks callback inputs that require an explicit custom token escape. */
+export const dynamic = Symbol('zyzz.binding.dynamic')
+
 /** A compiler-assigned web custom property with its scalar domain. */
 export type Reference<kind extends Domain = Domain> = {
   /** Fixed CSS custom-property name. */
   readonly name: `--${string}`
+  /** Internal callback provenance, independent of the emitted variable name. */
+  readonly [dynamic]?: true | undefined
   /** Scalar domain used by authoring types and runtime primitive checks. */
   readonly type: kind
   /** Distinguishes slots from theme references. */

package/src/internal/Completion.ts

@@ -11,9 +11,12 @@ export type Properties<
   styles = Record<string, unknown>,
 > = {
   readonly [property in keyof Literal.Properties & keyof styles]?:
-    | (string extends Literal.Properties[property]
-        ? never
-        : Literal.Properties[property])
+    // Configured tokens replace literal CSS values, so only token names are suggested.
+    | ([Token.Names<tokens, property>] extends [never]
+        ? string extends Literal.Properties[property]
+          ? never
+          : Literal.Properties[property]
+        : never)
     | Token.Names<tokens, property>
     | (string & {})
     | number

package/src/internal/Configuration.ts

@@ -163,6 +163,9 @@ export function create(
     )
       throw new InvalidError(`Unknown configuration option: ${key}`)
 
+  if (input.id !== undefined && (typeof input.id !== 'string' || !input.id))
+    throw new InvalidError('id must be a nonempty string.')
+
   if (
     input.storageKey !== undefined &&
     (typeof input.storageKey !== 'string' || !input.storageKey)
@@ -291,7 +294,7 @@ export function create(
   function handle(theme: Theme.Definition, name: string) {
     const original = Token.bind(theme, contract)
     const className = () =>
-      `z_theme-${Identity.requireId(typeof input.id === 'string' ? input.id : undefined, 'Config.create')}-${name.replace(/[^a-zA-Z0-9-]/g, (character) => `_${character.charCodeAt(0).toString(16)}_`)}`
+      `z-theme-${Identity.requireId(typeof input.id === 'string' ? input.id : undefined, 'Config.create').slice(3)}-${Identity.name(name)}`
     const select = (options: { colorScheme?: string } = {}) => {
       const scheme = options.colorScheme
       const selection =
@@ -433,7 +436,7 @@ export function create(
   }
 
   const theme =
-    shorthands || input.defaultLayer !== undefined
+    shorthands || input.defaultLayer !== undefined || input.id !== undefined
       ? Token.bind(Theme.define({}), contract)
       : undefined
   return finish({
@@ -452,7 +455,7 @@ export declare namespace create {
     readonly cssOutput?: 'atomic' | 'grouped' | undefined
     /** Fallback CSS layer for bound styles and variants; unlayered when omitted. */
     readonly defaultLayer?: string | undefined
-    /** Stable theme identity required without source rewriting. */
+    /** Consumer-owned namespace; required for uncompiled variable configs. */
     readonly id?: string | undefined
     /** Explicit ordered property aliases; none are installed by default. */
     readonly shorthands?: Shorthands.Map | undefined
@@ -839,7 +842,7 @@ export type VariableOptions = {
   readonly defaultLayer?: string | undefined
   /** Required default key when vars contains named sets. */
   readonly defaultVars?: string | undefined
-  /** Stable identity required without source rewriting. */
+  /** Consumer-owned namespace; required for uncompiled variable configs. */
   readonly id?: string | undefined
   /** Ordered CSS layer names. */
   readonly layers?: readonly string[] | undefined

package/src/internal/Identity.ts

@@ -25,13 +25,6 @@ export function compact(value: string): string {
   return result
 }
 
-/** Encodes an explicit identity without losing punctuation or Unicode distinctions. */
-export function encode(value: string): string {
-  return Array.from(value, (character) =>
-    character.codePointAt(0)!.toString(16),
-  ).join('-')
-}
-
 /** Keeps an authored label readable while its separate hash disambiguates spelling. */
 export function label(value: string): string {
   return (
@@ -42,18 +35,27 @@ export function label(value: string): string {
   )
 }
 
+/** Encodes one name segment, reserving hyphens for path boundaries. */
+export function name(value: string): string {
+  return Array.from(value, (character) =>
+    /^[a-zA-Z0-9]$/.test(character)
+      ? character
+      : `_${character.codePointAt(0)!.toString(16)}_`,
+  ).join('')
+}
+
 /** Requires an explicit identity at an uncompiled authoring boundary. */
 export function requireId(id: string | undefined, kind: string): string {
   if (!id)
     throw new Error(
       `${kind} requires an explicit id without the compiler plugin.`,
     )
-  return `id-${encode(id)}`
+  return `id-${name(id)}`
 }
 
 /** Names one callback input independently of its declaration order. */
 export function slot(id: string, field: string): `--${string}` {
-  return `--z-d${id}-${encode(field)}`
+  return `--z-${id.startsWith('id-') ? id.slice(3) : id}-${name(field)}`
 }
 
 /** Hashes a canonical value using two independent 32-bit accumulators. */
@@ -69,7 +71,7 @@ export function hash(value: string): string {
 }
 
 /** Names ordered style data consistently in runtime and extraction. */
-export function style(input: Style.NamedStyle): string {
+export function style(input: Style.NamedStyle, namespace?: string): string {
   function value(input: Style.Declaration['value']): unknown {
     if (Binding.is(input)) return ['variable', input.name]
     if (Token.is(input))
@@ -105,12 +107,12 @@ export function style(input: Style.NamedStyle): string {
       !!declaration.important,
     ])
   }
-  return `z-content-${hash(JSON.stringify(shape(input)))}`
+  return `z-${namespace ? `${namespace}-` : ''}content-${name(JSON.stringify(shape(input)))}`
 }
 
 /** Names a complete ordered composition, including repeated definitions. */
 export function composition(names: readonly string[]): string {
-  return `z-compose-${hash(JSON.stringify(names))}`
+  return `z-compose-${name(JSON.stringify(names))}`
 }
 
 /** Names a stylesheet declaration with a caller-owned identity. */

package/src/internal/Targets.ts

@@ -147,6 +147,8 @@ export function copy(
 export function web<name extends string>(
   style: Style.NamedStyle<name>,
 ): Style.NamedStyle<name> {
+  if (!style.rules && !style.targets) return style
+
   const rules = style.rules?.map((rule) => ({
     ...rule,
     style: web(rule.style),

package/src/internal/Theme.ts

@@ -599,10 +599,10 @@ function build(
     Object.defineProperty(
       {
         get className(): string {
-          if (scope) return `z_theme-${scope}`
+          if (scope) return `z-theme-${scope}`
           const id = contract[Token.identity]
           if (!id?.startsWith('id-')) throw new MissingTransformError()
-          return `z_theme-${id}-${Identity.hash(JSON.stringify(values))}`
+          return `z-theme-${id.slice(3)}`
         },
         style: (styles?: unknown, options: style.DefinitionOptions = {}) => {
           if (!contract[Token.identity])

package/src/internal/Token.ts

@@ -333,6 +333,7 @@ export function acceptsReference(
 export function bind<tokens extends Theme.Tokens>(
   original: Theme.Definition<tokens>,
   contract: Contract,
+  cssName?: string,
 ): Theme.Definition<tokens> {
   type Tree = { [key: string]: Reference | Tree }
 
@@ -371,7 +372,14 @@ export function bind<tokens extends Theme.Tokens>(
         vars: variables(tokens),
       },
       definition,
-      { value: Object.freeze({ ...metadata, contract, values }) },
+      {
+        value: Object.freeze({
+          ...metadata,
+          ...(cssName !== undefined ? { cssName } : {}),
+          contract,
+          values,
+        }),
+      },
     ),
   ) as Theme.Definition<tokens>
 }
@@ -520,6 +528,8 @@ export function is(value: unknown): value is Reference {
 
 /** Immutable theme data carried directly by each definition. */
 export type Metadata = {
+  /** Authored scope name, independent of private graph ownership. */
+  readonly cssName?: string | undefined
   /** Original segments for typography paths containing query punctuation. */
   readonly paths?: Readonly<Record<string, readonly string[]>> | undefined
   readonly queries?: Query.Metadata | undefined

package/src/internal/Value.ts

@@ -190,6 +190,26 @@ type CheckedArray<values, property extends PropertyKey, tokens> = {
   >[property]
 }
 
+/** Lists the values a token-constrained property accepts, so mismatch diagnostics name them. */
+export type Mismatch<tokens, property extends keyof Literal.Properties> =
+  // Resolving through a conditional prints the expected values instead of this alias's arguments.
+  tokens extends unknown
+    ? Expected<
+        | Extract<Token.Names<tokens, property>, string>
+        | NumericNames<Token.Names<tokens, property>>
+        | `${string} !custom`
+      >
+    : never
+
+// An object brand never reduces with a string literal, so the diagnostic keeps the expected values.
+type Expected<values> = { readonly [expected]: values }
+
+declare const expected: unique symbol
+
+type NumericNames<names> = names extends `${infer value extends number}`
+  ? value
+  : never
+
 /** Requires tokens for properties with configured values. */
 export type Tokens<
   value,

package/src/internal/VariableSets.ts

@@ -33,7 +33,7 @@ export function theme(
       get: () => {
         const identity = metadata.contract[Token.identity]
         return identity
-          ? `z_theme-${identity}-${Identity.hash(JSON.stringify(metadata.values))}`
+          ? `z-theme-${identity.startsWith('id-') ? identity.slice(3) : Identity.name(identity)}`
           : original.className
       },
       enumerable: true,