zyzz 0.0.27 → 0.0.29

package/src/web/internal/Wire.ts

@@ -0,0 +1,466 @@
+/**
+ * Encodes `Css.compile` input as the Rust compiler's JSON wire format and decodes its result.
+ * The format is documented in `crates/compiler/src/wire.rs`.
+ * @module
+ */
+import * as Binding from '../../internal/Binding.js'
+import * as Token from '../../internal/Token.js'
+import type * as Style from '../../Style.js'
+import * as Css from '../Css.js'
+import type * as Block from './Block.js'
+import * as ClassName from './ClassName.js'
+import type * as Contributions from './Contributions.js'
+import * as Themes from './Themes.js'
+
+/**
+ * Encodes compiler input, listing each identity-compared object once in post order.
+ * Reads own properties without invoking accessors on definitions and leaves inputs unchanged.
+ * @param options - Input accepted by `Css.compile`.
+ * @returns JSON text for the Rust compiler.
+ */
+export function encode(options: Css.compile.Options): string {
+  const indexes = new Map<object, number>()
+  const objects: unknown[] = []
+  // Declarations share reference objects, which are classified once per encoding.
+  const references = new Map<object, number | undefined>()
+  const strings: string[] = []
+  const stringIndexes = new Map<string, number>()
+
+  // Repeated property names and values are written once.
+  function string(value: string): number {
+    const previous = stringIndexes.get(value)
+    if (previous !== undefined) return previous
+
+    stringIndexes.set(value, strings.length)
+    strings.push(value)
+
+    return strings.length - 1
+  }
+
+  // Dependencies are encoded first, so every entry refers only to earlier entries.
+  function add(key: object, entry: () => unknown): number {
+    const previous = indexes.get(key)
+    if (previous !== undefined) return previous
+
+    const value = entry()
+
+    indexes.set(key, objects.length)
+    objects.push(value)
+
+    return objects.length - 1
+  }
+
+  function contract(value: Token.Contract): number {
+    return add(value, () => {
+      const fields: Record<string, unknown> = { keys: Object.keys(value) }
+
+      if (value[Token.complete]) fields.complete = true
+
+      const identity = value[Token.identity]
+      if (typeof identity === 'string') fields.identity = identity
+
+      if (value.variableSet) fields.variableSet = true
+      if (value.mappings !== undefined) fields.mappings = value.mappings
+      if (typeof value.composition === 'string')
+        fields.composition = value.composition
+      if (typeof value.cssOutput === 'string')
+        fields.cssOutput = value.cssOutput
+      if (typeof value.defaultLayer === 'string')
+        fields.defaultLayer = value.defaultLayer
+      if (value.shorthands !== undefined) fields.shorthands = value.shorthands
+
+      return ['c', fields]
+    })
+  }
+
+  function reference(value: unknown): number {
+    if (Binding.is(value))
+      return add(value, () => [
+        'b',
+        value.name,
+        value.type,
+        value[Binding.dynamic] === true,
+      ])
+
+    if (Token.is(value))
+      return add(value, () => [
+        't',
+        contract(value.contract),
+        value.group,
+        value.path,
+        tokenValue(value.value),
+        (value as Partial<Record<typeof Token.web, boolean>>)[Token.web] ===
+          true,
+      ])
+
+    if (Token.isExpression(value))
+      return add(value, () => [
+        'e',
+        Object.hasOwn(value, 'group')
+          ? (value as unknown as Token.Composition).group
+          : null,
+        value.parts.map((part) =>
+          typeof part === 'string' ? part : [reference(part)],
+        ),
+      ])
+
+    throw new Error('Expected a binding, token reference, or expression.')
+  }
+
+  function number(value: number): unknown {
+    return Number.isFinite(value) ? value : { n: String(value) }
+  }
+
+  function tokenValue(input: unknown): unknown {
+    if (typeof input === 'string') return input
+    if (typeof input === 'number') return number(input)
+    if (Token.is(input) || Token.isExpression(input)) return [reference(input)]
+
+    if (typeof input === 'object' && input !== null)
+      return {
+        r: Object.entries(input).map(([key, entry]) => [
+          key,
+          tokenValue(entry),
+        ]),
+      }
+
+    return String(input)
+  }
+
+  // The encoded index of a binding, token reference, or expression, classified once per object.
+  function known(value: object): number | undefined {
+    if (references.has(value)) return references.get(value)
+
+    const index =
+      Binding.is(value) || Token.is(value) || Token.isExpression(value)
+        ? reference(value)
+        : undefined
+
+    references.set(value, index)
+
+    return index
+  }
+
+  // Flat triples of property, value, and flags: bit 0 marks importance, and the remaining
+  // bits select a string, finite number, object, or non-finite number value.
+  function declarations(input: readonly Style.Declaration[]): number[] {
+    const output: number[] = []
+
+    for (const declaration of input) {
+      const value: unknown = declaration.value
+      const important = declaration.important ? 1 : 0
+
+      output.push(string(declaration.property))
+
+      if (typeof value === 'string') output.push(string(value), important)
+      else if (typeof value === 'number' && Number.isFinite(value))
+        output.push(value, 2 | important)
+      else if (typeof value === 'number')
+        output.push(Number.isNaN(value) ? 0 : Math.sign(value), 6 | important)
+      else {
+        const index =
+          typeof value === 'object' && value !== null ? known(value) : undefined
+
+        // Values outside the declaration contract serialize as their template-literal text.
+        if (index === undefined) output.push(string(String(value)), important)
+        else output.push(index, 4 | important)
+      }
+    }
+
+    return output
+  }
+
+  function theme(value: Token.Metadata): number {
+    return add(value, () => [
+      'm',
+      contract(value.contract),
+      value.cssName ?? null,
+      Object.entries(value.values).map(([path, entry]) => [
+        path,
+        tokenValue(entry),
+      ]),
+      value.paths ?? null,
+      value.queries ?? null,
+    ])
+  }
+
+  function own(value: object, key: string): unknown {
+    return Object.getOwnPropertyDescriptor(value, key)?.value
+  }
+
+  function style(input: Style.NamedStyle): unknown {
+    const output: Record<string, unknown> = {
+      d: declarations(input.declarations),
+      n: input.name,
+    }
+
+    if (input.rules)
+      output.r = input.rules.map((rule) => [
+        rule.condition === undefined ? null : String(rule.condition),
+        style(rule.style),
+      ])
+
+    // Only own modes apply; inherited metadata is ignored.
+    const cssOutput = own(input, 'cssOutput')
+    if (cssOutput !== undefined)
+      output.o = typeof cssOutput === 'string' ? cssOutput : false
+
+    const composition = own(input, 'composition')
+    if (composition !== undefined && composition !== null)
+      output.c = typeof composition === 'string' ? composition : false
+
+    if (input.targets) {
+      const targets: Record<string, unknown> = {}
+
+      for (const key of ['android', 'ios', 'native'] as const)
+        if (input.targets[key] !== undefined) targets[key] = input.targets[key]
+
+      if (input.targets.web) targets.web = style(input.targets.web)
+
+      output.t = targets
+    }
+
+    return output
+  }
+
+  function scalar(value: string | number): unknown {
+    return typeof value === 'number' && !Number.isFinite(value)
+      ? String(value)
+      : value
+  }
+
+  function entry(value: Block.Entry): unknown {
+    if (value.kind === 'style')
+      return { kind: 'style', style: style(value.style) }
+
+    if (value.kind === 'block')
+      return {
+        entries: value.entries.map(entry),
+        header: value.header,
+        kind: 'block',
+      }
+
+    return { kind: 'descriptor', name: value.name, value: scalar(value.value) }
+  }
+
+  function contribution(value: Contributions.Definition): unknown {
+    const within = value.within?.length ? { within: value.within } : {}
+
+    switch (value.kind) {
+      case 'block':
+        return {
+          entries: value.entries.map(entry),
+          header: value.header,
+          kind: value.kind,
+          ...within,
+        }
+      case 'custom-media':
+        return {
+          kind: value.kind,
+          name: value.name,
+          query: String(value.query),
+          ...within,
+        }
+      case 'descriptor':
+        return {
+          declarations: Object.entries(value.declarations).map(
+            ([key, entry]) => [key, scalar(entry)],
+          ),
+          kind: value.kind,
+          name: value.name,
+          rule: value.rule,
+          ...within,
+        }
+      case 'font-face':
+        return {
+          declarations: Object.entries(value.declarations).map(
+            ([key, entry]) => [key, scalar(entry)],
+          ),
+          kind: value.kind,
+          ...within,
+        }
+      case 'import':
+        return {
+          kind: value.kind,
+          ...(value.layer === true
+            ? { layer: true }
+            : value.layer
+              ? { layer: value.layer }
+              : {}),
+          ...(value.media ? { media: value.media } : {}),
+          ...(value.supports ? { supports: value.supports } : {}),
+          url: value.url,
+          ...within,
+        }
+      case 'keyframes':
+        return {
+          frames: value.frames.map((frame) => [frame.stop, style(frame.style)]),
+          kind: value.kind,
+          name: value.name,
+          ...within,
+        }
+      case 'layers':
+        return { kind: value.kind, names: value.names, ...within }
+      case 'namespace':
+        return {
+          kind: value.kind,
+          name: value.name,
+          ...(value.prefix === undefined ? {} : { prefix: value.prefix }),
+          uri: value.uri,
+          ...within,
+        }
+      case 'property':
+        return {
+          inherits: value.inherits,
+          ...(value.initialValue === undefined
+            ? {}
+            : { initialValue: scalar(value.initialValue) }),
+          kind: value.kind,
+          name: value.name,
+          syntax: value.syntax,
+          ...within,
+        }
+      case 'rule':
+        return {
+          kind: value.kind,
+          selector: value.selector,
+          style: style(value.style),
+          ...within,
+        }
+    }
+  }
+
+  // `??` treats null as absent for composition, while any present output mode is validated.
+  function mode(value: unknown, nullable: boolean): unknown {
+    if (value === undefined || (nullable && value === null)) return undefined
+    return typeof value === 'string' ? value : false
+  }
+
+  const styles = options.styles.styles.map(style)
+  const contributions = (options.contributions ?? []).map(contribution)
+  const vars =
+    options.vars &&
+    Object.entries(options.vars).map(([name, value]) => {
+      if (value === null || value === undefined) return [name, null]
+
+      const metadata = Object.getOwnPropertyDescriptor(value, Token.definition)
+        ?.value as Token.Metadata | undefined
+
+      return [name, value && metadata ? theme(metadata) : false]
+    })
+  const labels = options[ClassName.labels] ?? options.styles[ClassName.labels]
+  const units = options[ClassName.units]?.[ClassName.state]?.read()
+  const shared = options[Themes.shared]
+  const composition = mode(options.composition, true)
+  const cssOutput = mode(options.cssOutput, true)
+
+  // The decoder resolves the object and string tables before it reads styles.
+  return JSON.stringify({
+    objects,
+    strings,
+    ...(composition === undefined ? {} : { composition }),
+    ...(contributions.length ? { contributions } : {}),
+    ...(cssOutput === undefined ? {} : { cssOutput }),
+    ...(options.development ? { development: true } : {}),
+    ...(labels
+      ? {
+          labels: Object.entries(labels).map(([name, label]) => [
+            name,
+            label?.name ?? null,
+            label?.namespace ?? null,
+          ]),
+        }
+      : {}),
+    ...(options.names
+      ? {
+          names: Object.entries(options.names).filter(
+            ([, id]) => typeof id === 'string',
+          ),
+        }
+      : {}),
+    ...(options.schemes ? { schemes: true } : {}),
+    ...(typeof options.scope === 'string' && options.scope
+      ? { scope: options.scope }
+      : {}),
+    ...(shared ? { shared: shared === 'all' ? 'all' : 'defaults' } : {}),
+    styles,
+    ...(units
+      ? {
+          units: {
+            names: units.names,
+            owner: units.owner,
+            qualifier: units.qualifier,
+            visible: units.visible ?? null,
+          },
+        }
+      : {}),
+    ...(vars ? { vars } : {}),
+  })
+}
+
+/** Decoded output fields, as the Rust compiler emits them. */
+type Output = {
+  readonly classes: Readonly<Record<string, string>>
+  readonly contributionCss?: string | undefined
+  readonly css: string
+  readonly error?:
+    | {
+        readonly diagnostics?: readonly Css.Diagnostic[] | undefined
+        readonly message: string
+        readonly name: string
+      }
+    | undefined
+  readonly rules: Readonly<Record<string, string>>
+  readonly scopedCss?: string | undefined
+  readonly shared?: readonly Themes.Resource[] | undefined
+  readonly units: readonly (readonly [string, boolean, string])[]
+  readonly vars: Readonly<Record<string, string>>
+}
+
+/**
+ * Decodes a Rust compiler result into the frozen `Css.compile` result.
+ * Records unit naming decisions in the supplied scope's shared table.
+ * @param json - JSON text from the Rust compiler.
+ * @param units - The scope whose table the compilation borrowed, when one was supplied.
+ * @returns The same shape `Css.compile` returns.
+ * @throws {Css.CompileError} When the compilation reported diagnostics.
+ */
+export function decode(
+  json: string,
+  units?: ClassName.Units | undefined,
+): Css.compile.ReturnType {
+  const output = JSON.parse(json) as Output
+
+  if (output.error) {
+    if (output.error.diagnostics)
+      throw new Css.CompileError(output.error.diagnostics)
+    throw new Error(output.error.message)
+  }
+
+  const used = new Map(
+    output.units.map(([key, borrowed, name]) => [key, { borrowed, name }]),
+  )
+
+  units?.[ClassName.state]?.record(used)
+
+  const result = {
+    ...(output.shared ? { [Themes.shared]: output.shared } : {}),
+    ...(output.contributionCss === undefined
+      ? {}
+      : {
+          contributionCss: output.contributionCss,
+          scopedCss: output.scopedCss,
+        }),
+    [ClassName.units]: units?.used ?? used,
+    // Parsed records are fresh, so they freeze in place rather than as copies.
+    [ClassName.rules]: Object.freeze(output.rules),
+    classes: Object.freeze(Object.setPrototypeOf(output.classes, null)),
+    css: output.css,
+    vars: Object.freeze(Object.setPrototypeOf(output.vars, null)),
+  }
+
+  Object.defineProperty(result, ClassName.rules, { enumerable: false })
+  Object.defineProperty(result, ClassName.units, { enumerable: false })
+
+  return Object.freeze(result) as Css.compile.ReturnType
+}

package/src/web/internal/wasm.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Declares the generated WebAssembly compiler module for type checks that run before a build.
+ * `scripts/build-wasm.ts` writes `Wasm.generated.ts`, which `#wasm` resolves to when present.
+ * @module
+ */
+declare module '#wasm' {
+  /** The `crates/wasm` web build, base64 encoded. */
+  export const base64: string
+}

package/dist/compiler/internal/Applications.d.ts

@@ -1,55 +0,0 @@
-/** Finds nonescaping local static callables whose applications can become props. @module */
-import type * as Ast from '@oxc-project/types';
-import type * as Source from '../Source.js';
-/** Conservatively proves direct applications without changing binding reads. */
-export declare function create(program: Ast.Program, calls: readonly Source.Call[], options?: create.Options): Collector | undefined;
-/** Proven call site and its compiled definition. */
-type Application = {
-    /** End of the original binding or property read. */
-    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. */
-    find: () => readonly Application[];
-};
-/** Local application collection modes. */
-export declare namespace create {
-    /** Controls whether arguments are retained for fixed runtime compositions. */
-    type Options = {
-        /** Includes recipe/value applications while preserving their runtime calls. */
-        readonly dynamic?: boolean | undefined;
-    };
-}
-export {};
-//# sourceMappingURL=Applications.d.ts.map

package/dist/compiler/internal/Applications.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Applications.d.ts","sourceRoot":"","sources":["../../../src/compiler/internal/Applications.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,OAAO,KAAK,KAAK,GAAG,MAAM,oBAAoB,CAAA;AAG9C,OAAO,KAAK,KAAK,MAAM,MAAM,cAAc,CAAA;AAE3C,gFAAgF;AAChF,wBAAgB,MAAM,CACpB,OAAO,EAAE,GAAG,CAAC,OAAO,EACpB,KAAK,EAAE,SAAS,MAAM,CAAC,IAAI,EAAE,EAC7B,OAAO,GAAE,MAAM,CAAC,OAAY,GAC3B,SAAS,GAAG,SAAS,CA6avB;AAED,oDAAoD;AACpD,KAAK,WAAW,GAAG;IACjB,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B,CAAA;AAED,sEAAsE;AACtE,KAAK,SAAS,GAAG;IACf,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC1C,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,wEAAwE;AACxE,KAAK,SAAS,GAAG;IACf,gFAAgF;IAChF,IAAI,EAAE,MAAM,WAAW,CAAC,MAAM,CAAC,CAAA;IAC/B;;;;OAIG;IACH,WAAW,EAAE,MAAM;QACjB,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAA;QACzC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAC9C,CAAA;IACD,0DAA0D;IAC1D,KAAK,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,GAAG,IAAI,GAAG,SAAS,KAAK,IAAI,CAAA;IACpE,uDAAuD;IACvD,IAAI,EAAE,MAAM,SAAS,WAAW,EAAE,CAAA;CACnC,CAAA;AAED,0CAA0C;AAC1C,MAAM,CAAC,OAAO,WAAW,MAAM,CAAC;IAC9B,8EAA8E;IAC9E,KAAK,OAAO,GAAG;QACb,+EAA+E;QAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;KACvC,CAAA;CACF"}