zyzz 0.0.0 → 0.0.2

package/src/runtime/Appearance.ts

@@ -0,0 +1,155 @@
+/** Serializes root appearance restoration and controls the live root selection from compiled scope names. @module */
+import * as Scheme from '../internal/Scheme.js'
+
+/**
+ * Binds an HTML-safe script factory to compiled named theme classes.
+ * The factory is server-safe; only its returned JavaScript accesses the DOM.
+ * A saved scheme swaps the stylesheet scheme class and sets the inline `color-scheme`;
+ * a saved `null` scheme removes both so a cleared selection survives reloads.
+ * @param entries - Catalog names paired with compiled scope classes.
+ * @param options - Storage key shared with the configuration's root controls.
+ * @returns A pure script factory that never reads or writes browser state itself.
+ */
+export function create(
+  entries: readonly (readonly [string, string])[],
+  options: create.Options = {},
+): () => string {
+  return () => {
+    const catalog = serialize(entries)
+    const key = serialize(options.storageKey ?? 'zyzz')
+    const schemes = serialize(Object.entries(Scheme.classes))
+
+    return `(()=>{try{const value=JSON.parse(localStorage.getItem(${key})||"null");if(!value||typeof value!=="object"||Array.isArray(value))return;const root=document.documentElement;const catalog=new Map(${catalog});if(Object.hasOwn(value,"theme")&&typeof value.theme==="string"&&catalog.has(value.theme)){root.classList.remove(...catalog.values());root.classList.add(catalog.get(value.theme))}const schemes=new Map(${schemes});if(Object.hasOwn(value,"colorScheme")){if(value.colorScheme===null){root.classList.remove(...schemes.values());root.style.removeProperty("color-scheme")}else if(schemes.has(value.colorScheme)){root.classList.remove(...schemes.values());root.classList.add(schemes.get(value.colorScheme));root.style.colorScheme=value.colorScheme}}}catch{}})();`
+  }
+}
+
+/** Script factory settings. */
+export declare namespace create {
+  /** Configuration-level initialization settings. */
+  type Options = {
+    /** localStorage key shared with root controls; defaults to zyzz. */
+    readonly storageKey?: string | undefined
+  }
+}
+
+/**
+ * Binds root selection controls to compiled named theme classes.
+ * Creation touches no browser state; `get` and `set` read and write
+ * `document.documentElement` and the record the initialization script restores.
+ * @param entries - Catalog names paired with compiled scope classes.
+ * @param options - Default theme reported without a root class and the storage key.
+ * @returns Controls reading the applied root selection and applying saved changes.
+ * @throws {TypeError} If a named catalog receives no default or one outside its entries.
+ */
+export function root<const name extends string>(
+  entries: readonly (readonly [name, string])[],
+  options: root.Options<name> = {},
+): Root<name> {
+  const catalog = new Map<string, string>(entries)
+  const key = options.storageKey ?? 'zyzz'
+  const schemes = Object.entries(Scheme.classes) as [Scheme.Name, string][]
+
+  // Named catalogs always report a theme, so the fallback must be one of them.
+  if (
+    catalog.size &&
+    (options.defaultTheme === undefined || !catalog.has(options.defaultTheme))
+  )
+    throw new TypeError('defaultTheme must name a catalog theme.')
+
+  function get(): Selection<name> {
+    const classes = document.documentElement.classList
+    const theme =
+      [...catalog].find(([, className]) => classes.contains(className))?.[0] ??
+      options.defaultTheme
+    const colorScheme = schemes.find(([, className]) =>
+      classes.contains(className),
+    )?.[0]
+
+    return {
+      ...(theme === undefined ? {} : { theme }),
+      ...(colorScheme === undefined ? {} : { colorScheme }),
+    } as Selection<name>
+  }
+
+  function set(selection: Partial<Selection<name>>) {
+    const element = document.documentElement
+    const next = { ...get(), ...selection } as {
+      colorScheme?: Scheme.Name | undefined
+      theme?: string | undefined
+    }
+    const scopeClass =
+      next.theme === undefined ? undefined : catalog.get(next.theme)
+
+    // Rejected input leaves the document and the saved record untouched.
+    if (next.theme !== undefined && scopeClass === undefined)
+      throw new TypeError('Invalid theme selection.')
+
+    if (
+      next.colorScheme !== undefined &&
+      !Object.hasOwn(Scheme.classes, next.colorScheme)
+    )
+      throw new TypeError('Invalid theme selection.')
+
+    element.classList.remove(
+      ...catalog.values(),
+      ...schemes.map(([, className]) => className),
+    )
+
+    if (scopeClass !== undefined) element.classList.add(scopeClass)
+
+    if (next.colorScheme !== undefined) {
+      element.classList.add(Scheme.classes[next.colorScheme])
+      element.style.colorScheme = next.colorScheme
+    } else element.style.removeProperty('color-scheme')
+
+    // The record mirrors the applied root, so a cleared scheme saves as null
+    // and the script removes a server-rendered scheme on the next load.
+    const record = {
+      ...(next.theme === undefined ? {} : { theme: next.theme }),
+      colorScheme: next.colorScheme ?? null,
+    }
+
+    try {
+      localStorage.setItem(key, JSON.stringify(record))
+    } catch {
+      // Blocked storage keeps the selection for this document only.
+    }
+  }
+
+  return { get, set }
+}
+
+/** Root control contracts. */
+export declare namespace root {
+  /** Catalog defaults and storage settings. */
+  type Options<name extends string = string> = {
+    /** Theme reported by `get` when the root carries no catalog class; required with a named catalog. */
+    readonly defaultTheme?: NoInfer<name> | undefined
+    /** localStorage key shared with the initialization script; defaults to zyzz. */
+    readonly storageKey?: string | undefined
+  }
+}
+
+/** Live root selection controls. */
+export type Root<name extends string> = {
+  /** Reads the theme and scheme classes the root carries. */
+  readonly get: () => Selection<name>
+  /** Applies fields over the current selection and saves the result. */
+  readonly set: (selection: Partial<Selection<name>>) => void
+}
+
+/** A catalog theme with an optional scheme; an omitted scheme inherits. Token-free and single-theme configurations select only a scheme. */
+export type Selection<name extends string> = [name] extends [never]
+  ? { readonly colorScheme?: Scheme.Name | undefined }
+  : {
+      readonly colorScheme?: Scheme.Name | undefined
+      readonly theme: name
+    }
+
+function serialize(value: unknown): string {
+  return JSON.stringify(value).replace(
+    /[<>&\u2028\u2029]/g,
+    (character) =>
+      `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`,
+  )
+}

package/src/runtime/Composition.ts

@@ -0,0 +1,87 @@
+/** Merges bindings and attributes over a compiler-resolved ordered CSS group. @module */
+import type { style } from '../styleFunction.js'
+
+/** Private ownership retained in generated initialization data, never DOM props. */
+export type Owner = {
+  /** Recipe attributes replaced together for repeated applications. */
+  readonly attributes: readonly string[]
+  /** Stable authoring definition identity. */
+  readonly identity: string
+  /** Private callback slots replaced together for repeated applications. */
+  readonly slots: readonly string[]
+}
+
+/** Binds a fixed composition class to runtime styling inputs without generating rules. */
+type Entry =
+  | (style.Props & { readonly [key: `data-${string}`]: string | undefined })
+  | false
+  | null
+  | undefined
+
+/**
+ * Binds compiled classes and ownership metadata to a props-merging callable.
+ * @param options - Fixed classes, conditional cases, and ordered input owners.
+ * @returns A callable that merges application props without mutating its inputs.
+ * Initialization allocates class lookup sets; calls allocate fresh props and emit no CSS.
+ */
+export function create(options: create.Options) {
+  const inputs = options.inputs.map((input) => ({
+    ...input,
+    classes: new Set(input.className.split(/\s+/).filter(Boolean)),
+  }))
+
+  return (...entries: readonly Entry[]) => {
+    let mask = 0
+    for (const [index, input] of inputs.entries())
+      if (input.condition !== undefined && entries[index])
+        mask |= 1 << input.condition
+    const className = options.cases?.[mask] ?? options.className
+    const result: style.Props & Record<string, unknown> = {
+      className,
+    }
+    const external: string[] = []
+    const style: Record<string, string | number | undefined> = {}
+    for (const [index, entry] of entries.entries()) {
+      if (!entry) continue
+      const input = inputs[index]!
+      for (const owner of input.owners) {
+        for (const attribute of owner.attributes) delete result[attribute]
+        for (const slot of owner.slots) delete style[slot]
+      }
+      for (const name of entry.className.split(/\s+/))
+        if (name && !input.classes.has(name)) external.push(name)
+      for (const [name, value] of Object.entries(entry))
+        if (name.startsWith('data-')) result[name] = value
+      for (const [name, value] of Object.entries(entry.style ?? {})) {
+        // Reinsert overwritten keys so inline shorthand/longhand ordering follows arguments.
+        delete style[name]
+        style[name] = value
+      }
+    }
+    return {
+      ...result,
+      className: [className, ...external].filter(Boolean).join(' '),
+      ...(Object.keys(style).length ? { style } : {}),
+    }
+  }
+}
+
+/** Fixed composition initialization inputs. */
+export declare namespace create {
+  /** Compiler-selected rules and ownership for each application. */
+  type Options = {
+    /** Optional precompiled class lists indexed by argument-presence mask. */
+    readonly cases?: readonly string[] | undefined
+    /** Complete precompiled composition class list. */
+    readonly className: string
+    /** Ordered application class lists and private ownership. */
+    readonly inputs: readonly {
+      /** Generated classes superseded by the composition class. */
+      readonly className: string
+      /** Presence bit assigned to a conditional argument. */
+      readonly condition?: number | undefined
+      /** Original definitions whose bindings and attributes this application owns. */
+      readonly owners: readonly Owner[]
+    }[]
+  }
+}

package/src/runtime/CompositionHtml.ts

@@ -0,0 +1,38 @@
+/** Retains canonical inputs only for HTML applications used by compiled composition. @module */
+import type { style } from '../styleFunction.js'
+import * as Composition from './Composition.js'
+import * as Html from './Html.js'
+
+// A package may have distinct runtime copies in dependency optimization or SSR.
+// This versioned protocol key preserves canonical props across those module graphs.
+const input = Symbol.for('zyzz.composition.input.v1')
+type Props = style.Props & {
+  readonly [name: `data-${string}`]: string | undefined
+}
+type Prepared = Html.Attributes & { readonly [input]: Props }
+
+/** Binds a generated React-shaped callable to composable HTML attributes. */
+export function bind<const args extends readonly unknown[]>(
+  fn: (...args: args) => Props | Html.Attributes,
+) {
+  // Generated callers bind the underlying callable with HTML output disabled.
+  return (...args: args) => from(fn(...args) as Props)
+}
+
+/** Merges canonical props and serializes HTML once, without parsing style strings. */
+export function create(options: Composition.create.Options) {
+  const compose = Composition.create(options)
+  return (
+    ...entries: readonly (Html.Attributes | false | null | undefined)[]
+  ) =>
+    from(
+      compose(
+        ...entries.map((entry) => (entry ? (entry as Prepared)[input] : entry)),
+      ),
+    )
+}
+
+/** Converts props while retaining nonenumerable inputs for a surrounding composition. */
+export function from(props: Props): Html.Attributes {
+  return Object.defineProperty(Html.from(props), input, { value: props })
+}

package/src/runtime/ConditionalRecipe.ts

@@ -0,0 +1,70 @@
+/** Serializes conditional recipe instructions without evaluating queries. @module */
+import type { style } from '../styleFunction.js'
+import * as Html from './Html.js'
+import * as Recipe from './Recipe.js'
+
+/** Shared compiler/runtime spelling for a conditional selection attribute. */
+export function attribute(options: attribute.Options): `data-${string}` {
+  return `data-zyzz-condition-${options.condition}-${options.axis}`
+}
+
+/** Conditional attribute identity. */
+export declare namespace attribute {
+  /** Statically assigned axis and condition index. */
+  type Options = {
+    /** Declared axis name. */
+    readonly axis: string
+    /** Index in authored condition order. */
+    readonly condition: number
+  }
+}
+
+/** Binds conditional instructions while leaving query evaluation entirely to CSS. */
+export function create(options: create.Options) {
+  const base = Recipe.create({ ...options, html: false })
+  const conditions = options.conditions.map((name, condition) => ({
+    name,
+    axes: Object.keys(options.axes).map((axis) => ({
+      axis,
+      attribute: attribute({ axis, condition }),
+    })),
+  }))
+
+  return (input: Record<string, unknown> & style.Options = {}) => {
+    // The base was explicitly bound to React-shaped props above; HTML
+    // serialization occurs once, after all conditional attributes are added.
+    const result = base(input) as style.Props & Record<`data-${string}`, string>
+    const selected = input.conditions as
+      | Record<
+          string,
+          Record<string, string | boolean | null | undefined> | undefined
+        >
+      | undefined
+    for (const condition of conditions) {
+      const selections =
+        selected && Object.hasOwn(selected, condition.name)
+          ? selected[condition.name]
+          : undefined
+      if (!selections) continue
+
+      for (const { axis, attribute } of condition.axes) {
+        const value = Object.hasOwn(selections, axis)
+          ? selections[axis]
+          : undefined
+        if (value !== undefined)
+          result[attribute] = value === null ? 'n' : `s${value}`
+      }
+    }
+
+    return options.html ? Html.from(result) : result
+  }
+}
+
+/** Conditional recipe initialization inputs. */
+export declare namespace create {
+  /** Static recipe metadata with a declared condition order. */
+  type Options = Recipe.create.Options & {
+    /** Names whose overrides are serialized by the returned callable. */
+    readonly conditions: readonly string[]
+  }
+}

package/src/runtime/Dynamic.ts

@@ -0,0 +1,51 @@
+/** Assigns fixed private variables for compiled dynamic styles. @module */
+import type { style } from '../styleFunction.js'
+
+/** Binds required runtime scalars to fixed private variables and merges styling overrides. */
+export function create(
+  options: create.Options,
+): style.Dynamic<Record<string, string | number>> {
+  const { className } = options
+  const slots = Object.entries(options.slots)
+
+  return ((input: Record<string, string | number> & style.Options) => {
+    const values = slots.map(([key]) => {
+      const value = input[key]!
+
+      return value === '' ? ' ' : value
+    })
+    const external = input.className
+    const style = { ...input.variables, ...input.style }
+
+    for (let index = 0; index < slots.length; index++)
+      style[slots[index]![1].name] = values[index]!
+
+    return {
+      className:
+        className && external
+          ? `${className} ${external}`
+          : external || className,
+      style,
+    }
+  }) as style.Dynamic<Record<string, string | number>>
+}
+
+/** Contracts for compiler-generated dynamic callables. */
+export declare namespace create {
+  /** Fixed class and private slot assignments supplied by compilation. */
+  type Options = {
+    /** Complete generated class list. */
+    readonly className: string
+    /** Required scalar slots keyed by input name. */
+    readonly slots: Readonly<
+      Record<
+        string,
+        {
+          readonly name: `--${string}`
+          readonly type: string
+          readonly zero?: boolean
+        }
+      >
+    >
+  }
+}

package/src/runtime/Html.ts

@@ -0,0 +1,91 @@
+/** Converts compiled styling props to DOM attributes and HTML text. @module */
+import type { style } from '../styleFunction.js'
+import * as Props from './Props.js'
+
+/** DOM attributes ready for a framework spread or setAttribute. */
+export type Attributes = {
+  /** Compiled and external classes. */
+  readonly class: string
+  /** Serialized CSS declarations; renderers own HTML escaping. */
+  readonly style?: string | undefined
+} & { readonly [name: `data-${string}`]: string | undefined }
+
+/**
+ * Converts compiled styling props without generating CSS rules or mutating inputs.
+ * Values retain explicit CSS units. Custom properties retain their spelling.
+ * @param props - Applied style or theme props, including owned data attributes.
+ * @returns Unescaped DOM attribute values; never insert them into HTML directly.
+ */
+export function from(
+  props: style.Props & {
+    readonly [name: `data-${string}`]: string | undefined
+  },
+): Attributes {
+  const result: {
+    class: string
+    style?: string
+    [name: `data-${string}`]: string | undefined
+  } = { class: props.className }
+
+  if (props.style !== undefined) {
+    const declarations: string[] = []
+
+    for (const [property, value] of Object.entries(props.style)) {
+      if (value === undefined || value === null) continue
+
+      const name = property.startsWith('--')
+        ? property
+        : property
+            .replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)
+            .replace(/^ms-/, '-ms-')
+
+      declarations.push(`${name}:${value}`)
+    }
+
+    result.style = declarations.join(';')
+  }
+
+  for (const [name, value] of Object.entries(props))
+    if (name.startsWith('data-'))
+      result[name as `data-${string}`] = value as string | undefined
+
+  return result
+}
+
+/**
+ * Serializes styling attributes for insertion inside an HTML opening tag.
+ * @param attributes - DOM attributes returned by from.
+ * @returns Space-separated attributes with quoted, HTML-escaped values.
+ */
+export function serialize(attributes: Attributes): string {
+  return Object.entries(attributes)
+    .filter(([, value]) => value !== undefined)
+    .map(([name, value]) => `${escape(name)}="${escape(value!)}"`)
+    .join(' ')
+}
+
+function escape(value: string): string {
+  return value.replace(/[&<>"'\s]/g, (character) => {
+    if (character === '&') return '&amp;'
+    if (character === '<') return '&lt;'
+    if (character === '>') return '&gt;'
+    if (character === '"') return '&quot;'
+    if (character === "'") return '&#39;'
+
+    return `&#${character.charCodeAt(0)};`
+  })
+}
+
+/** Binds compiler-generated props to native HTML attributes. */
+export function bind<input>(
+  fn: (input: input) => style.Props,
+): (input: input) => style.Props<'html'> {
+  return (input) => from(fn(input))
+}
+
+/** Creates a static HTML style callable without CSS generation. */
+export function create(
+  options: Props.create.Options,
+): style.ReturnType<'html'> {
+  return bind(Props.create(options)) as style.ReturnType<'html'>
+}

package/src/runtime/Native.ts

@@ -0,0 +1,144 @@
+/** Selects precompiled native props and composes caller-owned native style values. @module */
+import type * as StyleSheet from '../react-native/StyleSheet.js'
+
+type Choices<values extends readonly string[]> =
+  values[number] extends infer value
+    ? value extends 'true'
+      ? true
+      : value extends 'false'
+        ? false
+        : value
+    : never
+
+/** Inferred finite inputs for a generated native recipe callable. */
+export type Callable<
+  axes extends Readonly<Record<string, readonly string[]>>,
+  style extends object = StyleSheet.NativeStyle,
+> = <const overrides extends object = never>(
+  input?: {
+    readonly [axis in keyof axes]?: Choices<axes[axis]> | null | undefined
+  } & {
+    /** Caller-owned native overrides, applied after the selected table entry. */
+    readonly style?: StyleSheet.StyleProp<overrides> | undefined
+  },
+) => Props<style | overrides>
+
+type EntryStyle<entry> = entry extends Props<infer style> ? style : never
+
+/**
+ * Combines applied native props in order without flattening caller-owned values.
+ * @param entries - Applied props or falsy conditional entries.
+ * @returns Native style props preserving nested arrays and object identity.
+ */
+export function compose<
+  const entries extends readonly (Props<object> | false | null | undefined)[],
+>(...entries: entries): Props<EntryStyle<entries[number]>> {
+  for (const entry of entries)
+    if (
+      entry &&
+      (!Object.hasOwn(entry, 'style') ||
+        Object.keys(entry).some((key) => key !== 'style'))
+    )
+      throw new SelectionError(
+        'Native composition requires native style props.',
+      )
+  const styles = entries
+    .filter(
+      (entry): entry is Extract<entries[number], Props<object>> => !!entry,
+    )
+    .map((entry) => entry.style)
+  return { style: styles.length === 1 ? styles[0] : styles } as Props<
+    EntryStyle<entries[number]>
+  >
+}
+
+/**
+ * Binds a finite native table to defaults and optional styling overrides.
+ * @param options - Compiler-owned axes, defaults, and a selected theme/scheme table.
+ * @returns A callable that only looks up static data and composes native overrides.
+ * @throws {SelectionError} For undeclared axes, choices, or missing table entries.
+ */
+export function create<
+  const axes extends Readonly<Record<string, readonly string[]>>,
+  const styles extends Readonly<Record<string, StyleSheet.NativeStyle>>,
+>(options: create.Options<axes, styles>): Callable<axes, styles[keyof styles]> {
+  const axes = Object.entries(options.axes)
+  for (const style of Object.values(options.styles)) freeze(style)
+  const staticStyle =
+    axes.length === 0 ? options.styles['0' as keyof styles] : undefined
+  const staticProps = staticStyle
+    ? Object.freeze({ style: staticStyle })
+    : undefined
+  return (input) => {
+    if (input === undefined && staticProps) return staticProps
+    if (input === undefined) input = {}
+    for (const key of Object.keys(input))
+      if (key !== 'style' && !Object.hasOwn(options.axes, key))
+        throw new SelectionError(`Unknown native recipe input: ${key}.`)
+    let index = 0
+    let stride = 1
+    const values: Readonly<Record<string, unknown>> = input
+    for (const [axis, choices] of axes) {
+      const supplied = Object.hasOwn(values, axis) ? values[axis] : undefined
+      const selected =
+        supplied === undefined
+          ? Object.hasOwn(options.defaults, axis)
+            ? options.defaults[axis]
+            : undefined
+          : supplied
+      const choice =
+        selected === null || selected === undefined
+          ? choices.length
+          : typeof selected === 'string' || typeof selected === 'boolean'
+            ? choices.indexOf(String(selected))
+            : -1
+      if (choice < 0)
+        throw new SelectionError(`Unknown native recipe choice for ${axis}.`)
+      index += choice * stride
+      stride *= choices.length + 1
+    }
+    const style = options.styles[String(index) as keyof styles]
+    if (!style)
+      throw new SelectionError('Native recipe table is missing a selection.')
+    return { style: input.style ? [style, input.style] : style }
+  }
+}
+
+/** Inputs emitted by the native compiler. */
+export declare namespace create {
+  /** Finite metadata and precompiled objects, with no device-state lookup. */
+  type Options<
+    axes extends Readonly<Record<string, readonly string[]>> = Readonly<
+      Record<string, readonly string[]>
+    >,
+    styles extends Readonly<Record<string, StyleSheet.NativeStyle>> = Readonly<
+      Record<string, StyleSheet.NativeStyle>
+    >,
+  > = {
+    /** Ordered finite choice names. */
+    readonly axes: axes
+    /** Default selections. Null suppresses an axis. */
+    readonly defaults: Readonly<Record<string, string | null>>
+    /** One theme/scheme table indexed by finite selections. */
+    readonly styles: styles
+  }
+}
+
+/** Props returned by compiled native definitions and native composition. */
+export type Props<style extends object = StyleSheet.NativeStyle> = {
+  /** Native style values ready for an ordinary component's style prop. */
+  readonly style: StyleSheet.StyleProp<style>
+}
+
+/** An application selected an unknown finite native variant. */
+export class SelectionError extends Error {
+  /** Stable namespaced diagnostic name. */
+  override name = 'Native.SelectionError'
+}
+
+function freeze(value: object): void {
+  if (Object.isFrozen(value)) return
+  for (const child of Object.values(value))
+    if (child && typeof child === 'object') freeze(child)
+  Object.freeze(value)
+}