zyzz 0.0.0 → 0.0.2

package/src/web/internal/ClassName.ts

@@ -0,0 +1,112 @@
+/** Names atomic declarations with readable values and scoped conflict identities. @module */
+import * as Literal from '../../internal/Literal.js'
+
+/** Creates a CSS identifier without embedding arbitrary CSS syntax. */
+export function create(options: create.Options): string {
+  const property = Object.hasOwn(aliases, options.property)
+    ? aliases[options.property]!
+    : Literal.name(options.property)
+  const condition =
+    /^&:(hover|focus|focus-visible|active|disabled)\{([^{}]+)\}$/.exec(
+      options.body,
+    )
+  const body = condition?.[2] ?? options.body
+  const prefix = `${Literal.name(options.property)}:`
+  const literal =
+    body.startsWith(prefix) && body.endsWith(';')
+      ? body.slice(prefix.length, -1)
+      : ''
+  const simple = /^[a-zA-Z0-9-]{1,24}$/.test(literal)
+  const label =
+    options.property === 'display' && displays.has(literal)
+      ? literal
+      : `${property.startsWith('--') ? encode(property).replaceAll('-', '_2d_') : property}${simple ? `-${literal}` : ''}`
+
+  const suffix = (() => {
+    if (options.context !== undefined)
+      return `-${hash(options.stable || simple ? options.context : JSON.stringify([options.context, options.body]))}${options.slot === undefined ? '' : `-${options.slot}`}`
+    if (!simple) return `-${hash(options.body)}`
+    return ''
+  })()
+
+  if (options.stable) return `z-${encode(property)}${suffix}`
+
+  // Custom properties and vendor spellings can contain identifier punctuation.
+  return `z-${condition ? `${condition[1]}-` : ''}${encode(label)}${suffix}`
+}
+
+/** Atomic naming inputs; context retains declaration ordering and module ownership. */
+export declare namespace create {
+  /** Serialized declaration and its optional stable slot identity. */
+  type Options = {
+    /** Complete declaration, including fallbacks and conditions. */
+    readonly body: string
+    /** Identity required when the declaration cannot share a global rule. */
+    readonly context?: string | undefined
+    /** Authoring property spelling. */
+    readonly property: string
+    /** Ordered declaration slot inside a contextual style. */
+    readonly slot?: number | undefined
+    /** Keep names independent of values for CSS-only development updates. */
+    readonly stable?: boolean | undefined
+  }
+}
+
+const aliases: Readonly<Record<string, string>> = {
+  backgroundColor: 'bg',
+  color: 'text',
+  height: 'h',
+  margin: 'm',
+  marginBottom: 'mb',
+  marginLeft: 'ml',
+  marginRight: 'mr',
+  marginTop: 'mt',
+  opacity: 'opacity',
+  padding: 'p',
+  paddingBottom: 'pb',
+  paddingLeft: 'pl',
+  paddingRight: 'pr',
+  paddingTop: 'pt',
+  width: 'w',
+}
+
+// Flex and grid also name shorthand properties, so retain their display prefix.
+const displays = new Set([
+  'block',
+  'inline',
+  'inline-block',
+  'inline-flex',
+  'inline-grid',
+  'none',
+])
+
+function encode(value: string): string {
+  return value.replace(
+    /[^a-zA-Z0-9-]/g,
+    (character) => `_${character.charCodeAt(0).toString(16)}_`,
+  )
+}
+
+// Six CSS identifier characters retain 36 bits from two deterministic streams.
+function hash(value: string): string {
+  let first = 2166136261
+  let second = 5381
+
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index)
+    first = Math.imul(first ^ code, 16777619)
+    second = Math.imul(second, 33) ^ code
+  }
+
+  const alphabet =
+    '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_-'
+  let bits = (first >>> 0) * 16 + (second >>> 28)
+  let result = ''
+
+  for (let index = 0; index < 6; index++) {
+    result = alphabet[bits % 64]! + result
+    bits = Math.floor(bits / 64)
+  }
+
+  return result
+}

package/src/web/internal/Context.ts

@@ -0,0 +1,16 @@
+/** Defines legal enclosing contexts for stylesheet declaration helpers. @module */
+/** Conditional and layer headers accepted around stylesheet declarations. */
+export type Group =
+  | '@layer'
+  | `@${'container' | 'layer' | 'media' | 'supports'}${'\t' | '\n' | '\r' | '\f' | '(' | `/*${string}*/`}${string}`
+  | `@container ${string}`
+  | `@layer ${string}`
+  | `@media ${string}`
+  | `@supports ${string}`
+/** Ordered enclosing groups, from outermost to innermost. */
+export type Options = {
+  /** Explicit identity for named declarations without source rewriting. */
+  readonly id?: string | undefined
+  /** Enclosing groups; omitted means stylesheet scope. */
+  readonly within?: readonly Group[] | undefined
+}

package/src/web/internal/Contributions.ts

@@ -0,0 +1,219 @@
+/** Pure ordered stylesheet contribution data and layer ordering. @module */
+import * as Block from './Block.js'
+import * as Namespace from './Namespace.js'
+import type * as Style from '../../Style.js'
+
+/** Explicit stylesheet data supplied by source adapters or in-memory callers. */
+export type Definition = {
+  /** Enclosing groups in authored outermost-first order. */
+  readonly within?: readonly string[] | undefined
+} & (
+  | {
+      /** Whether the registered value inherits from its parent element. */
+      readonly inherits: boolean
+      /** Computationally independent initial CSS value. */
+      readonly initialValue?: number | string | undefined
+      /** Emits a CSS custom-property registration rule. */
+      readonly kind: 'property'
+      /** Registered custom-property name, including the -- prefix. */
+      readonly name: `--${string}`
+      /** CSS Properties and Values syntax descriptor. */
+      readonly syntax: string
+    }
+  | {
+      readonly kind: 'rule'
+      readonly selector: string
+      readonly style: Style.NamedStyle
+    }
+  | {
+      readonly kind: 'font-face'
+      readonly declarations: Readonly<Record<string, string | number>>
+    }
+  | {
+      readonly kind: 'keyframes'
+      readonly name: string
+      readonly frames: readonly {
+        readonly stop: string
+        readonly style: Style.NamedStyle
+      }[]
+    }
+  | {
+      /** Structured named descriptor rule. */
+      readonly kind: 'descriptor'
+      /** Compiler-owned rule name. */
+      readonly name: string
+      /** CSS descriptor rule family. */
+      readonly rule: 'color-profile' | 'counter-style' | 'font-palette-values'
+      /** Authored scalar descriptors. */
+      readonly declarations: Readonly<Record<string, string | number>>
+    }
+  | {
+      /** Structured document-level descriptor rule. */
+      readonly kind: 'block'
+      /** CSS rule header. */
+      readonly header: string
+      /** Descriptors and nested blocks in authored order. */
+      readonly entries: readonly Block.Entry[]
+    }
+  | (Namespace.Definition & { readonly kind: 'namespace' })
+  | {
+      readonly kind: 'import'
+      readonly url: string
+      readonly layer?: string | true | undefined
+      readonly supports?: string | undefined
+      readonly media?: string | undefined
+    }
+  | {
+      readonly kind: 'custom-media'
+      readonly name: string
+      readonly query: string | boolean
+    }
+  | { readonly kind: 'layers'; readonly names: readonly string[] }
+)
+
+/** Merges declared ordering constraints with deterministic unconstrained ties. */
+export function order(
+  lists: readonly (readonly string[])[],
+): readonly string[] {
+  const scopes = new Map<string, Map<string, Set<string>>>()
+  const authored = new Set<string>()
+
+  function scope(parent: string) {
+    let graph = scopes.get(parent)
+
+    if (!graph) {
+      graph = new Map()
+      scopes.set(parent, graph)
+    }
+
+    return graph
+  }
+
+  for (const list of lists) {
+    if (new Set(list).size !== list.length)
+      throw new Error('Duplicate layer name.')
+
+    for (const name of list) {
+      if (
+        !/^(?:--|-?[_a-zA-Z])[\w-]*(?:\.(?:--|-?[_a-zA-Z])[\w-]*)*$/.test(
+          name,
+        ) ||
+        name
+          .split('.')
+          .some((part) =>
+            [
+              'default',
+              'inherit',
+              'initial',
+              'revert',
+              'revert-layer',
+              'unset',
+            ].includes(part.toLowerCase()),
+          )
+      )
+        throw new Error('Invalid layer name.')
+
+      authored.add(name)
+
+      const parts = name.split('.')
+
+      for (let index = 0; index < parts.length; index++) {
+        const graph = scope(parts.slice(0, index).join('.'))
+
+        if (!graph.has(parts[index]!)) graph.set(parts[index]!, new Set())
+      }
+    }
+
+    for (let index = 1; index < list.length; index++) {
+      const before = list[index - 1]!.split('.'),
+        after = list[index]!.split('.')
+      const at = before.findIndex((value, index) => value !== after[index])
+
+      if (at >= 0 && after[at] !== undefined)
+        scope(before.slice(0, at).join('.')).get(before[at]!)!.add(after[at]!)
+    }
+  }
+
+  const result: string[] = []
+
+  function emit(parent: string) {
+    const graph = scopes.get(parent)
+    if (!graph) return
+
+    while (graph.size) {
+      const targets = new Set(
+        [...graph.values()].flatMap((values) => [...values]),
+      )
+      const next = [...graph.keys()].find((name) => !targets.has(name))
+      if (next === undefined)
+        throw new Error('Conflicting layer order constraints.')
+
+      const name = parent ? `${parent}.${next}` : next
+
+      if (authored.has(name)) result.push(name)
+
+      graph.delete(next)
+      emit(name)
+    }
+  }
+
+  emit('')
+
+  return result
+}
+
+/** Renders static contributions without registration or environment access. */
+export function render(
+  definitions: readonly Definition[],
+  style: (value: Style.NamedStyle) => string,
+): string {
+  const layers = order(
+    definitions.flatMap((value) =>
+      value.kind === 'layers' ? [value.names] : [],
+    ),
+  )
+
+  return [
+    layers.length ? `@layer ${layers.join(',')};` : '',
+    ...definitions
+      .toSorted((a, b) => rank(a) - rank(b))
+      .map((value) => {
+        if (value.kind === 'layers') return ''
+        const css = (() => {
+          if (value.kind === 'namespace') return Namespace.statement(value)
+          if (value.kind === 'custom-media')
+            return `@custom-media ${value.name} ${value.query};`
+          if (value.kind === 'import')
+            return `@import url(${JSON.stringify(value.url)})${value.layer === true ? ' layer' : value.layer ? ` layer(${value.layer})` : ''}${value.supports ? ` supports(${value.supports})` : ''}${value.media ? ` ${value.media}` : ''};`
+          if (value.kind === 'block')
+            return `${value.header}{${Block.render(value.entries, style)}}`
+          if (value.kind === 'rule')
+            return `${value.selector}{${style(value.style)}}`
+          if (value.kind === 'property')
+            return `@property ${value.name}{syntax:${JSON.stringify(value.syntax)};inherits:${value.inherits};${value.initialValue === undefined ? '' : `initial-value:${value.initialValue};`}}`
+          if (value.kind === 'font-face' || value.kind === 'descriptor')
+            return `@${value.kind === 'font-face' ? 'font-face' : `${value.rule} ${value.name}`}{${Object.entries(
+              value.declarations,
+            )
+              .map(
+                ([key, value]) =>
+                  `${key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}:${value};`,
+              )
+              .join('')}}`
+          return `@keyframes ${value.name}{${value.frames.map((frame) => `${frame.stop}{${style(frame.style)}}`).join('')}}`
+        })()
+        return (value.within ?? []).reduceRight(
+          (body, header) => `${header}{${body}}`,
+          css,
+        )
+      }),
+  ]
+    .filter(Boolean)
+    .join('\n')
+}
+
+function rank(value: Definition): number {
+  if (value.kind === 'import') return 0
+  if (value.kind === 'namespace') return 1
+  return 2
+}

package/src/web/internal/Namespace.ts

@@ -0,0 +1,21 @@
+/** Defines source-owned namespace bindings and their CSS statement encoding. @module */
+/** One authored namespace and its compiler-owned output prefix. */
+export type Definition = {
+  /** Unique emitted namespace prefix. */
+  readonly name: string
+  /** Authored selector prefix, or omitted for the default namespace. */
+  readonly prefix?: string | undefined
+  /** Namespace URI; this is an identity, not an asset URL. */
+  readonly uri: string
+}
+
+/** Encodes a namespace URI as a CSS string, including control characters and quotes. */
+export function statement(value: Definition): string {
+  // eslint-disable-next-line no-control-regex -- CSS strings require escaping control characters.
+  const uri = value.uri.replace(/[\x00-\x1f\x7f"\\]/g, (char) => {
+    if (char === '\0') return '\uFFFD'
+    if (char === '"' || char === '\\') return `\\${char}`
+    return `\\${char.charCodeAt(0).toString(16)} `
+  })
+  return `@namespace ${value.name} "${uri}";`
+}

package/src/web/internal/Themes.ts

@@ -0,0 +1,133 @@
+/**
+ * Collects live theme references and emits graph-local variables and scope rules.
+ * @module
+ */
+import * as Scheme from '../../internal/Scheme.js'
+import * as Token from '../../internal/Token.js'
+import type * as Theme from '../../Theme.js'
+
+/** Collects live token references within one in-memory compilation graph. */
+export function create() {
+  let nextScope = 0
+  let nextVariable = 0
+  const contracts = new Map<
+    Token.Contract,
+    { identity: string | undefined; paths: Map<string, string> }
+  >()
+
+  function serialize(token: Token.Reference): string {
+    const value = token.value
+    let contract = contracts.get(token.contract)
+
+    if (!contract) {
+      contract = {
+        identity: token.contract[Token.identity],
+        paths: new Map(),
+      }
+      contracts.set(token.contract, contract)
+    }
+
+    let name = contract.paths.get(token.path)
+
+    if (!name) {
+      name =
+        contract.identity === undefined
+          ? `--z${nextVariable++}`
+          : variable(contract.identity, token.path)
+      contract.paths.set(token.path, name)
+    }
+
+    return `var(${name},${literal(value)})`
+  }
+
+  function emit(
+    themes: Readonly<Record<string, Theme.Definition>>,
+    schemes = false,
+  ) {
+    const classes: Record<string, string> = Object.create(null)
+    const rules: string[] = []
+
+    for (const [name, theme] of Object.entries(themes)) {
+      if (!name) throw new Error('Theme names must be nonempty.')
+
+      const data =
+        theme &&
+        (Object.getOwnPropertyDescriptor(theme, Token.definition)?.value as
+          | Token.Metadata
+          | undefined)
+      if (!data) throw new Error('Expected a theme definition.')
+
+      // Anonymous contracts are graph-local. Source-owned contracts retain stable
+      // identities across separately compiled components and theme scopes.
+      const className =
+        data.contract[Token.identity] === undefined
+          ? `t_${nextScope++}`
+          : `z_theme-${encode(name)}`
+
+      classes[name] = className
+
+      let contract = contracts.get(data.contract)
+
+      if (data.contract[Token.complete]) {
+        contract ??= {
+          identity: data.contract[Token.identity],
+          paths: new Map(),
+        }
+
+        // Separately compiled components may reference tokens absent from this graph.
+        for (const path of Object.keys(data.values)) {
+          if (contract.paths.has(path)) continue
+
+          contract.paths.set(
+            path,
+            contract.identity === undefined
+              ? `--z${nextVariable++}`
+              : variable(contract.identity, path),
+          )
+        }
+
+        contracts.set(data.contract, contract)
+      }
+
+      if (!contract) continue
+
+      const body = [...contract.paths]
+        .map(([path, name]) => {
+          const value = data.values[path]
+          if (value === undefined)
+            throw new Error('Theme scope is missing a live token.')
+
+          return `${name}:${literal(value)};`
+        })
+        .join('')
+
+      rules.push(`.${className}{${body}}`)
+    }
+
+    // Scheme rules travel with the module that can apply them, so lowered
+    // light-dark() resolves wherever selection helpers load.
+    if (schemes) rules.push(Scheme.css)
+
+    return { classes: Object.freeze(classes), css: rules.join('\n') }
+  }
+
+  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)}_`,
+  )
+}
+
+function literal(value: Token.Value): string {
+  return typeof value === 'object'
+    ? `light-dark(${value.light},${value.dark})`
+    : String(value)
+}
+
+function variable(index: number | string, path: string): string {
+  return `--z-t${encode(String(index))}-${encode(path)}`
+}

package/src/web/keyframes.ts

@@ -0,0 +1,43 @@
+/** Declares statically named animation frames. @module */
+import type * as Context from './internal/Context.js'
+import type * as Lexical from '../internal/Lexical.js'
+import * as Identity from '../internal/Identity.js'
+import type * as Style from '../Style.js'
+import type * as Value from '../internal/Value.js'
+
+/** Compiles ordered frame stops and returns a fixed animation name. */
+export function keyframes<const frames extends Record<string, unknown>>(
+  frames: frames &
+    NoInfer<{
+      [key in keyof frames]: key extends string
+        ? Stops<Lexical.Fold<Lexical.Normalized<key>>> extends true
+          ? Value.Accepted<frames[key], Style.DeclarationProperties> &
+              Value.Checked<frames[key]>
+          : never
+        : never
+    }>,
+  context: Context.Options = {},
+): string {
+  void context
+  void frames
+  return Identity.contribution('keyframes', context.id)
+}
+
+type Space = ' ' | '\t' | '\n' | '\r' | '\f'
+type Trim<value extends string> = value extends `${Space}${infer rest}`
+  ? Trim<rest>
+  : value extends `${infer rest}${Space}`
+    ? Trim<rest>
+    : value
+
+type Stops<value extends string> = value extends `${infer first},${infer rest}`
+  ? Stops<first> extends true
+    ? Stops<rest>
+    : false
+  : Trim<value> extends
+        | 'from'
+        | 'to'
+        | `${number}%`
+        | `${'contain' | 'cover' | 'entry' | 'entry-crossing' | 'exit' | 'exit-crossing'}${Space}${number}%`
+    ? true
+    : false

package/src/web/layers.ts

@@ -0,0 +1,6 @@
+/** Declares eager module-level cascade layer ordering. @module */
+/** Contributes ordered layer names; compilation removes this authoring call. */
+export function layers(names: readonly string[]): void {
+  void names
+  return
+}

package/src/web/namespace.ts

@@ -0,0 +1,19 @@
+/** Declares a module-owned CSS namespace. @module */
+/** Emits an isolated namespace binding for the module's selectors. The last declaration for each decoded prefix applies throughout the module. */
+export function namespace<const options extends namespace.Options>(
+  options: options &
+    Record<Exclude<keyof options, keyof namespace.Options>, never>,
+): void {
+  void options
+  return
+}
+/** CSS namespace authoring options. */
+export declare namespace namespace {
+  /** Namespace URI and optional authored selector prefix. */
+  type Options = {
+    /** CSS identifier spelling, including Unicode and escapes; omitted creates a default namespace. */
+    readonly prefix?: string | undefined
+    /** Namespace URI, never an asset to fetch or relocate. */
+    readonly uri: string
+  }
+}