zyzz 0.0.21 → 0.0.23

package/src/runtime/NativeVars.ts

@@ -0,0 +1,189 @@
+/** Selects immutable native variable tables emitted by the compiler. @module */
+import type * as Literal from '../internal/Literal.js'
+import * as Media from './internal/NativeMedia.js'
+import type * as StyleSheet from '../react-native/StyleSheet.js'
+import type * as Vars from '../Vars.js'
+
+const binding = Symbol('zyzz.native.vars')
+
+/** Static values with deferred diagnostics for unsupported native leaves. */
+export type EncodedTree = {
+  readonly [key: string]: string | number | EncodedTree | readonly [string]
+}
+
+/** Resolves portable reference domains to readonly native value types. */
+export type Values<
+  values,
+  category = undefined,
+  root extends boolean = true,
+> = {
+  readonly [key in Exclude<
+    keyof values,
+    root extends true ? 'breakpoint' | 'containerNames' : never
+  >]: values[key] extends Vars.Value
+    ? category extends 'fontWeight'
+      ? Exclude<StyleSheet.NativeStyle['fontWeight'], undefined>
+      : category extends 'typography'
+        ? key extends 'fontWeight'
+          ? Exclude<StyleSheet.NativeStyle['fontWeight'], undefined>
+          : key extends 'lineHeight'
+            ? number
+            : Scalar<Vars.Scalar<values[key]>>
+        : Scalar<Vars.Scalar<values[key]>>
+    : Values<values[key], root extends true ? key : category, false>
+}
+
+/** Native scalar values nested under their authored variable paths. */
+export type Tree = { readonly [key: string]: string | number | Tree }
+
+type Scalar<value> = value extends number | Literal.Length ? number : string
+
+type Definition = {
+  readonly defaultVars: string
+  readonly media?:
+    | {
+        readonly profiles: Readonly<Record<string, Definition['profiles']>>
+        readonly queries: readonly Media.Query[]
+      }
+    | undefined
+  readonly profiles: Readonly<
+    Record<string, Readonly<Record<'dark' | 'light', Tree>>>
+  >
+  readonly unnamed: boolean
+}
+
+/** Copies and shares equal branches across the compiled profiles. */
+export function create(options: create.Options): object {
+  const shared = new Map<string, Tree>()
+
+  function freeze(tree: EncodedTree): Tree {
+    const key = JSON.stringify(tree)
+    const previous = shared.get(key)
+    if (previous) return previous
+
+    const value: Tree = {}
+    for (const [name, entry] of Object.entries(tree)) {
+      const diagnostic = Array.isArray(entry) ? String(entry[0]) : undefined
+      Object.defineProperty(
+        value,
+        name,
+        diagnostic !== undefined
+          ? {
+              enumerable: true,
+              get() {
+                throw new Error(diagnostic)
+              },
+            }
+          : {
+              enumerable: true,
+              value:
+                typeof entry === 'object'
+                  ? freeze(entry as EncodedTree)
+                  : entry,
+            },
+      )
+    }
+    Object.freeze(value)
+    shared.set(key, value)
+    return value
+  }
+
+  function profiles(value: create.Options['profiles']): Definition['profiles'] {
+    return Object.freeze(
+      Object.fromEntries(
+        Object.entries(value).map(([name, schemes]) => [
+          name,
+          Object.freeze({
+            dark: freeze(schemes.dark),
+            light: freeze(schemes.light),
+          }),
+        ]),
+      ),
+    )
+  }
+
+  return Object.freeze({
+    [binding]: Object.freeze({
+      defaultVars: options.defaultVars,
+      ...(options.media
+        ? {
+            media: Object.freeze({
+              profiles: Object.freeze(
+                Object.fromEntries(
+                  Object.entries(options.media.profiles).map(([key, value]) => [
+                    key,
+                    profiles(value),
+                  ]),
+                ),
+              ),
+              queries: options.media.queries,
+            }),
+          }
+        : {}),
+      profiles: profiles(options.profiles),
+      unnamed: options.unnamed,
+    }),
+  })
+}
+
+/** Compiler-generated native profiles. */
+export declare namespace create {
+  /** Static tables and the owning configuration's default name. */
+  type Options = {
+    /** Fallback when the Provider omits its selection. */
+    readonly defaultVars: string
+    /** Precompiled alternatives for supported window queries. */
+    readonly media?:
+      | {
+          readonly profiles: Readonly<Record<string, Options['profiles']>>
+          readonly queries: readonly Media.Query[]
+        }
+      | undefined
+    /** Native values for every configured name and scheme. */
+    readonly profiles: Readonly<
+      Record<string, Readonly<Record<'dark' | 'light', EncodedTree>>>
+    >
+    /** A standalone definition whose values do not depend on the selected name. */
+    readonly unnamed: boolean
+  }
+}
+
+/** Reads a compiled profile without evaluating authoring or accessing device state. */
+export function read(value: object, selection: read.Options): Tree {
+  if (
+    !value ||
+    (typeof value !== 'object' && typeof value !== 'function') ||
+    !Object.hasOwn(value, binding)
+  )
+    throw new Error(
+      'useVars requires variables compiled by the native adapter.',
+    )
+
+  const definition = (value as { readonly [binding]: Definition })[binding]
+  const profiles =
+    definition.media && selection.viewport
+      ? definition.media.profiles[
+          Media.select(definition.media.queries, selection.viewport)
+        ]!
+      : definition.profiles
+  const name = selection.set ?? definition.defaultVars
+  const profile =
+    (Object.hasOwn(profiles, name) ? profiles[name] : undefined) ??
+    (definition.unnamed ? profiles.default : undefined)
+  if (!profile) throw new Error(`Unknown native vars: ${name}.`)
+
+  return profile[selection.colorScheme]
+}
+
+/** Selection supplied by the nearest native Provider. */
+export declare namespace read {
+  /** Resolved appearance and an optional variable name. */
+  type Options = {
+    /** Resolved native color scheme. */
+    readonly colorScheme: 'dark' | 'light'
+    /** Selected name, or the configuration default when omitted. */
+    readonly set?: string | undefined
+    /** Native window dimensions; unsupported leaves remain lazy when absent. */
+    readonly viewport?: Media.Viewport | undefined
+  }
+}

package/src/runtime/index.ts

@@ -29,6 +29,12 @@ export * as NativeContext from './NativeContext.js'
 /** Ordered native scalar bindings for generated dynamic callables. */
 export * as NativeDynamic from './NativeDynamic.js'
 
+/** Finite native selection without dynamic value conversion. */
+export * as NativeStatic from './NativeStatic.js'
+
+/** Readonly native variable selection for compiled hooks. */
+export * as NativeVars from './NativeVars.js'
+
 /** Scoped recipe inputs bound to fixed variable slots. */
 export * as PayloadRecipe from './PayloadRecipe.js'
 

package/src/runtime/internal/NativeMedia.ts

@@ -0,0 +1,63 @@
+/** Selects precompiled media alternatives using native logical dimensions. @module */
+
+/** Comparison data emitted by the compiler, with no CSS parsing at application time. */
+export type Query =
+  | { readonly kind: 'and'; readonly queries: readonly Query[] }
+  | {
+      readonly kind: 'compare'
+      readonly left: number | 'height' | 'width'
+      readonly operator: '<' | '<=' | '=' | '>' | '>='
+      readonly right: number | 'height' | 'width'
+    }
+  | { readonly kind: 'not'; readonly query: Query }
+  | { readonly kind: 'or'; readonly queries: readonly Query[] }
+
+/** Window measurements supplied by the native React adapter. */
+export type Viewport = {
+  readonly height: number
+  readonly width: number
+}
+
+/** Computes the selected alternative without interpreting authoring code. */
+export function select(
+  queries: readonly Query[],
+  viewport: Viewport | undefined,
+): string {
+  if (!viewport)
+    throw new Error(
+      'Native media queries require the native Provider window dimensions.',
+    )
+  if (
+    !Number.isFinite(viewport.height) ||
+    viewport.height < 0 ||
+    !Number.isFinite(viewport.width) ||
+    viewport.width < 0
+  )
+    throw new Error('Native window dimensions must be finite and nonnegative.')
+
+  const dimensions = viewport
+  function matches(query: Query): boolean {
+    if (query.kind === 'and') return query.queries.every(matches)
+    if (query.kind === 'or') return query.queries.some(matches)
+    if (query.kind === 'not') return !matches(query.query)
+
+    const left =
+      typeof query.left === 'number' ? query.left : dimensions[query.left]
+    const right =
+      typeof query.right === 'number' ? query.right : dimensions[query.right]
+    switch (query.operator) {
+      case '<':
+        return left < right
+      case '<=':
+        return left <= right
+      case '=':
+        return left === right
+      case '>':
+        return left > right
+      case '>=':
+        return left >= right
+    }
+  }
+
+  return queries.map((query) => (matches(query) ? '1' : '0')).join('')
+}

package/src/vite/index.ts

@@ -20,6 +20,7 @@ import * as Scope from '../compiler/internal/Scope.js'
 import type { Environment, Plugin, Rollup, ViteDevServer } from 'vite'
 import * as Graph from '../compiler/Graph.js'
 import * as Source from '../compiler/Source.js'
+import * as ThemeRules from '../web/internal/Themes.js'
 
 /**
  * Compiles physical project source without executing authoring code.
@@ -749,6 +750,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
       )
 
     const result = entry.compiler.compile({
+      [ThemeRules.shared]: native ? undefined : 'all',
       [Syntax.cache]: snapshot(entry.environment).programs(modules),
       compiler: options.compiler,
       reset: options.reset ? Reset.read() : undefined,
@@ -812,46 +814,6 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
         configurations.set(key, configuration)
       }
 
-    const map = new Mapping.GenMapping()
-    const styles: string[] = []
-    let line = 0
-
-    for (const [id, output] of Object.entries(result.modules)) {
-      if (!connected.has(sourceFile(id)!)) continue
-      if (!output.css) continue
-
-      for (const mapping of Mapping.allMappings(
-        Mapping.fromMap(JSON.stringify(output.cssMap)),
-      )) {
-        const generated = {
-          column: mapping.generated.column,
-          line: mapping.generated.line + line,
-        }
-
-        if (mapping.source !== undefined && mapping.original !== undefined) {
-          const location = {
-            generated,
-            original: mapping.original,
-            source: sourceFile(mapping.source) ?? mapping.source,
-          }
-
-          if (mapping.name === undefined) Mapping.addMapping(map, location)
-          else Mapping.addMapping(map, { ...location, name: mapping.name })
-        } else Mapping.addMapping(map, { generated })
-      }
-
-      for (const [index, source] of output.cssMap.sources.entries())
-        if (source !== null)
-          Mapping.setSourceContent(
-            map,
-            sourceFile(source) ?? source,
-            output.cssMap.sourcesContent?.[index] ?? null,
-          )
-
-      styles.push(output.css)
-      line += output.css.split('\n').length
-    }
-
     const owners = new Map<string, string>()
 
     for (const id of new Set(Object.values(result.sharedAssetOwners ?? {}))) {
@@ -1018,10 +980,15 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
       contractIds: Object.keys(compiled),
       configurations,
       connections: staged,
-      css: styles.join('\n'),
+      css: output.css,
       sharedCss: new TextDecoder().decode(shared.code),
       sharedCssMap: sharedMap,
-      cssMap: Mapping.toEncodedMap(map),
+      cssMap: {
+        ...output.cssMap,
+        sources: output.cssMap.sources.map((source) =>
+          source === null ? null : (sourceFile(source) ?? source),
+        ),
+      },
       map: {
         ...output.map,
         sources: output.map.sources.map((source) =>

package/src/web/Css.ts

@@ -56,7 +56,18 @@ export function compile<
     return result
   }
 
+  const bodies = new Map<Style.NamedStyle, string>()
+  const declarations = new Map<Style.Declaration, string>()
+  type Property = {
+    readonly important: Map<Style.Declaration['value'], string>
+    readonly name: string
+    readonly normal: Map<Style.Declaration['value'], string>
+  }
+  const declarationProperties = new Map<string, Property>()
+  const serialized = new Map<object, string>()
+
   // Only primitive declaration lists can be interned without erasing token identity.
+  // Reuse their emitted bodies throughout analysis and output.
   const repeated = new Map<string, Style.NamedStyle>()
 
   const canonicalStyles = options.styles.styles.map((style) => {
@@ -68,13 +79,7 @@ export function compile<
     )
       return style
 
-    const key = JSON.stringify(
-      style.declarations.map(({ important, property, value }) => [
-        property,
-        value,
-        important,
-      ]),
-    )
+    const key = nested(style)
     const previous = repeated.get(key)
     if (previous) return previous
 
@@ -269,8 +274,6 @@ export function compile<
     if (Object.hasOwn(Cascade.shorthands, property))
       join(property, domain(property))
 
-  const serialized = new Map<object, string>()
-
   function serialize(input: Style.Declaration['value']): number | string {
     if (typeof input !== 'object' || input === null) return input
 
@@ -298,22 +301,32 @@ export function compile<
     return input as number | string
   }
 
-  const declarations = new Map<Style.Declaration, string>()
-  const propertyNames = new Map<string, string>()
-
   function declarationBody(declaration: Style.Declaration): string {
     const previous = declarations.get(declaration)
     if (previous !== undefined) return previous
+
     const { important, property, value } = declaration
-    const name = propertyNames.get(property) ?? Literal.name(property)
-    propertyNames.set(property, name)
-    const body = `${name}:${serialize(value)}${important ? '!important' : ''};`
+    let entry = declarationProperties.get(property)
+    if (!entry) {
+      entry = {
+        important: new Map(),
+        name: Literal.name(property),
+        normal: new Map(),
+      }
+      declarationProperties.set(property, entry)
+    }
+
+    const values = important ? entry.important : entry.normal
+    let body = values.get(value)
+    if (body === undefined) {
+      body = `${entry.name}:${serialize(value)}${important ? '!important' : ''};`
+      values.set(value, body)
+    }
+
     declarations.set(declaration, body)
     return body
   }
 
-  const bodies = new Map<Style.NamedStyle, string>()
-
   function nested(style: Style.NamedStyle): string {
     const previous = bodies.get(style)
     if (previous !== undefined) return previous
@@ -401,11 +414,8 @@ export function compile<
   }
 
   function validate(style: Style.NamedStyle) {
-    if (
-      outputMode(style) !== undefined &&
-      outputMode(style) !== 'atomic' &&
-      outputMode(style) !== 'grouped'
-    )
+    const mode = outputMode(style)
+    if (mode !== undefined && mode !== 'atomic' && mode !== 'grouped')
       throw new CompileError([
         {
           code: 'invalid_output',
@@ -421,7 +431,8 @@ export function compile<
   const rules = new Map<string, string>()
   type ConditionalRule = { conditions: readonly string[]; value: string }
   const conditionalRules = new Map<string, ConditionalRule>()
-  const identical = new Map<string, string>()
+  type SharedRules = Record<'atomic' | 'grouped', Map<string, string>>
+  const identical = new Map<string | undefined, SharedRules>()
   const explicitBodies = new Map<string, string>()
   const selectors = new Map<string, string>()
   const explicitModes = new Set<string>()
@@ -465,7 +476,7 @@ export function compile<
       explicit === undefined &&
       options.composition === 'independent' &&
       !options.development
-        ? `${mode}:${JSON.stringify(representation(style))}:${nested(canonicalStyles[styleIndex]!)}`
+        ? `${mode}:${style.rules ? JSON.stringify(representation(style)) : ''}:${nested(canonicalStyles[styleIndex]!)}`
         : undefined
     if (application !== undefined && applications.has(application)) {
       classes[style.name] = applications.get(application)!
@@ -478,6 +489,11 @@ export function compile<
     const cssNamespace =
       labels?.[style.name]?.namespace ??
       (options.scope ? Identity.name(options.scope) : undefined)
+    let sharedRules = identical.get(cssNamespace)
+    if (!sharedRules) {
+      sharedRules = { atomic: new Map(), grouped: new Map() }
+      identical.set(cssNamespace, sharedRules)
+    }
 
     function emit(
       body: string,
@@ -493,9 +509,8 @@ export function compile<
         !options.development &&
         output === mode &&
         options.composition === 'independent'
-      const key = JSON.stringify([cssNamespace, output, body])
       const reusable = explicit === undefined && (shared || independent)
-      const previous = reusable ? identical.get(key) : undefined
+      const previous = reusable ? sharedRules![output].get(body) : undefined
       if (previous && !names.includes(previous)) {
         names.push(previous)
         return
@@ -544,7 +559,7 @@ export function compile<
         conditionalRules.set(identity, conditional)
       if (explicit !== undefined) selectors.set(identity, explicit)
       else {
-        if (reusable) identical.set(key, identity)
+        if (reusable) sharedRules![output].set(body, identity)
         names.push(identity)
       }
     }

package/src/web/internal/Themes.ts

@@ -15,6 +15,24 @@ export function create() {
     { identity: string | undefined; paths: Map<string, string> }
   >()
 
+  const anonymous = new Map<Token.Contract, Map<string, string>>()
+  let nextVariable = 0
+  function property(contract: Token.Contract, path: string): string {
+    const identity = contract[Token.identity]
+    if (identity) return variable(identity, path)
+    let paths = anonymous.get(contract)
+    if (!paths) {
+      paths = new Map()
+      anonymous.set(contract, paths)
+    }
+    let name = paths.get(path)
+    if (!name) {
+      name = `--z${(nextVariable++).toString(36)}`
+      paths.set(path, name)
+    }
+    return name
+  }
+
   const defaults = new Map<string, readonly Rule[]>()
   const defaultGroups = new Map<Token.Contract, Set<string>>()
 
@@ -33,11 +51,7 @@ export function create() {
     let name = contract.paths.get(token.path)
 
     if (!name) {
-      name = variable(
-        contract.identity,
-        token.path,
-        token.contract.variableNaming,
-      )
+      name = property(token.contract, token.path)
       contract.paths.set(token.path, name)
     }
 
@@ -51,6 +65,7 @@ export function create() {
     separate?: 'all' | 'defaults',
   ) {
     const classes: Record<string, string> = Object.create(null)
+    let nextScope = 0
     const scopeBodies = new Map<string, string>()
     const completeDefaults = new Set<Token.Contract>()
     const empty: string[] = []
@@ -68,14 +83,17 @@ export function create() {
 
       // Anonymous contracts are graph-local. Source-owned contracts retain stable
       // identities across separately compiled components and theme scopes.
-      const className = scope(
-        data.cssName ??
-          (data.contract[Token.identity] &&
-          name.startsWith(`${data.contract[Token.identity]}-`)
-            ? name.slice(data.contract[Token.identity]!.length + 1)
-            : name),
-        data.contract[Token.identity],
-      )
+      const className =
+        data.contract[Token.identity] || data.cssName
+          ? scope(
+              data.cssName ??
+                (data.contract[Token.identity] &&
+                name.startsWith(`${data.contract[Token.identity]}-`)
+                  ? name.slice(data.contract[Token.identity]!.length + 1)
+                  : name),
+              data.contract[Token.identity],
+            )
+          : `z${(nextScope++).toString(36)}`
 
       classes[name] = className
 
@@ -91,10 +109,7 @@ export function create() {
         for (const path of Object.keys(data.values)) {
           if (contract.paths.has(path)) continue
 
-          contract.paths.set(
-            path,
-            variable(contract.identity, path, data.contract.variableNaming),
-          )
+          contract.paths.set(path, property(data.contract, path))
         }
 
         contracts.set(data.contract, contract)
@@ -125,28 +140,6 @@ export function create() {
           selector: `.${className}`,
           value: literal(value, label, data.contract),
         })
-        // Standalone styles have no contract metadata to select their original spelling.
-        if (
-          contract.identity?.startsWith('id-') &&
-          data.contract.variableNaming === undefined
-        )
-          declarations.push({
-            conditions: [],
-            property: variable(
-              `id-${Array.from(
-                contract.identity
-                  .slice(3)
-                  .replace(/_([0-9a-f]+)_/g, (_, code: string) =>
-                    String.fromCodePoint(Number.parseInt(code, 16)),
-                  ),
-                (character) => character.codePointAt(0)!.toString(16),
-              ).join('-')}`,
-              path,
-              'legacy',
-            ),
-            selector: `.${className}`,
-            value: `var(${name})`,
-          })
       }
 
       rules.push(...declarations)
@@ -266,7 +259,7 @@ export function create() {
       const base = literal(value.default, label, owner)
       // Rule consolidation must not change existing variable identities.
       const css = `:where(*){--fallback:${base};}${conditionalCss(value, '--fallback', ':where(*)', label, owner)}`
-      const name = `${variable(owner?.[Token.identity], label ?? 'value')}-fallback-${Identity.name(css)}`
+      const name = `${owner ? property(owner, label ?? 'value') : variable(undefined, label ?? 'value')}-fallback-${Identity.name(css)}`
       const emitted: Rule[] = [
         { conditions: [], property: name, selector: ':where(*)', value: base },
       ]
@@ -341,14 +334,6 @@ export function create() {
   return { emit, serialize }
 }
 
-/** Escapes a scope key into the identifier segment of its compiled class. */
-export function encode(value: string): string {
-  return value.replace(
-    /[^a-zA-Z0-9-]/g,
-    (character) => `_${character.charCodeAt(0).toString(16)}_`,
-  )
-}
-
 /** Combines generated declarations without crossing competing declarations of the same property. */
 export function render(rules: readonly Rule[]): string {
   const groups: {
@@ -424,15 +409,7 @@ export function scope(value: string, identity?: string): string {
   return `z-theme-${namespace}${Identity.name(value)}`
 }
 
-function variable(
-  identity: string | undefined,
-  path: string,
-  naming?: 'legacy' | 'hashed',
-): string {
-  if (naming === 'legacy' && identity)
-    return `--z-t${encode(identity)}-${encode(path)}`
-  if (naming === 'hashed')
-    return `--z-${Identity.label(path)}-${Identity.compact(JSON.stringify([identity, path]))}`
+function variable(identity: string | undefined, path: string): string {
   const namespace = identity?.startsWith('id-') ? `${identity.slice(3)}-` : ''
   return `--z-${namespace}${path.split('.').map(Identity.name).join('-')}`
 }

package/src/web/page.ts

@@ -35,6 +35,8 @@ export declare namespace page {
       | 'crop cross'
       | 'cross crop'
       | undefined
+    /** Handling of page margins that exceed the printer's printable area. */
+    readonly pageMarginSafety?: 'none' | 'clamp' | 'add' | undefined
     /** Rotation applied to a laid-out page. */
     readonly pageOrientation?:
       | 'upright'