zyzz 0.0.0 → 0.0.2

package/src/runtime/NativeContext.ts

@@ -0,0 +1,74 @@
+/** Defers precompiled native selection until a React render supplies its context. @module */
+import type * as Native from './Native.js'
+
+const binding = Symbol('zyzz.native.context')
+
+/** Render-local theme and resolved appearance. */
+export type Context = {
+  /** Resolved system appearance or an explicit override. */
+  readonly colorScheme: 'dark' | 'light'
+  /** Named compiled theme; omission uses each configuration default. */
+  readonly theme?: string | undefined
+}
+
+type Callable = (input: never) => Native.Props<object>
+type Tables = Readonly<
+  Record<string, Readonly<Record<'dark' | 'light', Callable>>>
+>
+
+/** Retains compiled alternatives without selecting a device context at module evaluation. */
+export function create<const tables extends Tables>(
+  tables: tables,
+  defaultTheme: keyof tables & string,
+): tables[keyof tables]['light'] {
+  const fallback =
+    Object.keys(tables).length === 1 && defaultTheme === 'default'
+      ? tables.default
+      : undefined
+
+  function select(context: Context, input?: never) {
+    const theme = context.theme ?? defaultTheme
+    const table = tables[theme] ?? fallback
+    if (!table) throw new Error(`Unknown native theme: ${theme}.`)
+    return table[context.colorScheme](input!).style
+  }
+  function props(input?: never) {
+    return {
+      style: {
+        [binding]: (context: Context) => select(context, input),
+      },
+    }
+  }
+  const defaults = props()
+  Object.freeze(defaults.style)
+  Object.freeze(defaults)
+  const callable = (input?: never) =>
+    input === undefined ? defaults : props(input)
+  Object.defineProperty(callable, binding, {
+    value: select,
+  })
+  return callable as tables[keyof tables]['light']
+}
+
+/** Resolves generated bindings and arrays while preserving caller-owned native objects. */
+export function resolve(
+  value: unknown,
+  context: Context | undefined,
+  input?: unknown,
+): unknown {
+  if (Array.isArray(value)) return value.map((entry) => resolve(entry, context))
+  if (
+    value &&
+    (typeof value === 'object' || typeof value === 'function') &&
+    binding in value
+  ) {
+    if (!context)
+      throw new Error('Compiled native styles require a Zyzz Provider.')
+    const select = value[binding]
+    if (typeof select === 'function')
+      return resolve(select(context, input), context)
+  }
+  if (typeof value === 'function')
+    return (...args: unknown[]) => resolve(value(...args), context)
+  return value
+}

package/src/runtime/NativeDynamic.ts

@@ -0,0 +1,246 @@
+/** Applies compiled native binding instructions to runtime scalar payloads. @module */
+import * as Scalar from '../react-native/internal/Scalar.js'
+import type * as StyleSheet from '../react-native/StyleSheet.js'
+import * as Native from './Native.js'
+import type * as Recipe from './Recipe.js'
+
+/** A generated callable with required application payloads and native overrides. */
+export type Callable<input> = <
+  const overrides extends object = StyleSheet.NativeStyle,
+>(
+  input: input & {
+    /** Caller-owned overrides applied after generated values. */
+    readonly style?: StyleSheet.StyleProp<overrides> | undefined
+  },
+) => Native.Props<StyleSheet.NativeStyle | overrides>
+
+/** A native variant callable whose omitted input applies declared defaults. */
+export type RecipeCallable<input> = <
+  const overrides extends object = StyleSheet.NativeStyle,
+>(
+  input?: input & {
+    /** Caller-owned overrides applied after selected variant values. */
+    readonly style?: StyleSheet.StyleProp<overrides> | undefined
+  },
+) => Native.Props<StyleSheet.NativeStyle | overrides>
+
+/** Adapts a published web callable's payload to native styling overrides. */
+export type From<fn> = fn extends (...args: infer args) => unknown
+  ? [] extends args
+    ? RecipeCallable<
+        Omit<NonNullable<args[0]>, 'style' | 'className' | 'variables'>
+      >
+    : Callable<Omit<NonNullable<args[0]>, 'style' | 'className' | 'variables'>>
+  : never
+
+/** Ordered static and dynamic assignments selected by finite recipe choices. */
+export type Program = {
+  /** Required top-level input fields mapped to internal slot names. */
+  readonly slots: Readonly<Record<string, string>>
+  /** Base, variant, and compound rules in authored order. */
+  readonly rules: readonly {
+    readonly matches: readonly (readonly [string, readonly string[]])[]
+    readonly steps: readonly (
+      | { readonly style: string }
+      | {
+          readonly property: keyof typeof Scalar.properties
+          readonly parts: readonly (
+            | string
+            | number
+            | { readonly slot: string }
+          )[]
+        }
+    )[]
+  }[]
+}
+
+/** Binds generated instructions without running authoring callbacks or generating CSS. */
+export function create(
+  options: create.Options,
+): Callable<Record<string, unknown>> {
+  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)
+  }
+  for (const style of Object.values(options.styles)) freeze(style)
+
+  return (input = {}) => {
+    const bindings: Record<string, string | number> = Object.create(null)
+    const selected: Record<string, string | null | undefined> =
+      Object.create(null)
+    for (const key of Object.keys(input))
+      if (
+        key !== 'style' &&
+        !Object.hasOwn(options.axes, key) &&
+        !Object.hasOwn(options.program.slots, key)
+      )
+        throw new Native.SelectionError(`Unknown native recipe input: ${key}.`)
+
+    function bind(slots: Readonly<Record<string, string>>, values: unknown) {
+      if (!values || typeof values !== 'object' || Array.isArray(values))
+        throw new Native.SelectionError(
+          'Native payloads require scalar fields.',
+        )
+      const record = values as Record<string, unknown>
+      for (const [field, slot] of Object.entries(slots)) {
+        const value = Object.hasOwn(record, field) ? record[field] : undefined
+        if (
+          (typeof value !== 'number' && typeof value !== 'string') ||
+          (typeof value === 'number' && !Number.isFinite(value))
+        )
+          throw new Native.SelectionError(
+            `Missing or invalid native payload: ${field}.`,
+          )
+        bindings[slot] = value
+      }
+    }
+    bind(options.program.slots, input)
+    for (const [axis, choices] of Object.entries(options.axes)) {
+      let value = Object.hasOwn(input, axis) ? input[axis] : undefined
+      if (value === undefined) {
+        value = options.defaults[axis]
+        if (value != null && Object.hasOwn(options.defaultPayloads ?? {}, axis))
+          value = { [String(value)]: options.defaultPayloads![axis] }
+      }
+      if (value == null) {
+        selected[axis] = value
+        continue
+      }
+      let payload: unknown
+      if (typeof value === 'object' && !Array.isArray(value)) {
+        const entries = Object.entries(value)
+        if (entries.length !== 1)
+          throw new Native.SelectionError(
+            'Native payloads require exactly one choice.',
+          )
+        ;[value, payload] = entries[0]!
+      }
+      if (
+        (typeof value !== 'string' && typeof value !== 'boolean') ||
+        !choices.includes(String(value))
+      )
+        throw new Native.SelectionError(
+          `Unknown native recipe choice for ${axis}.`,
+        )
+      const choice = String(value)
+      selected[axis] = choice
+      const definition = options.payloads?.find(
+        (entry) => entry.axis === axis && entry.choice === choice,
+      )
+      if (definition) bind(definition.slots[0]!, payload)
+      else if (payload !== undefined)
+        throw new Native.SelectionError(
+          `Static native choice does not accept a payload: ${axis}.`,
+        )
+    }
+
+    const output: Record<string, unknown> = {}
+    let lineHeight: string | number | undefined
+    for (const rule of options.program.rules) {
+      if (
+        !rule.matches.every(
+          ([axis, choices]) =>
+            selected[axis] != null && choices.includes(selected[axis]!),
+        )
+      )
+        continue
+      for (const step of rule.steps) {
+        if ('style' in step) {
+          const style = options.styles[step.style]
+          if (!style)
+            throw new Native.SelectionError(
+              'Native binding program is missing a static style.',
+            )
+          Object.assign(output, style)
+          if (style.lineHeight !== undefined) lineHeight = undefined
+          continue
+        }
+        const values = step.parts.map((part) =>
+          typeof part === 'object' ? bindings[part.slot] : part,
+        )
+        if (values.some((value) => value === undefined))
+          throw new Native.SelectionError(
+            'Native binding program references an unbound slot.',
+          )
+        const value = values.length === 1 ? values[0]! : values.join('')
+        const { property } = step
+        if (property === 'lineHeight') {
+          lineHeight = value
+          continue
+        }
+        const converted = Scalar.convert(
+          Scalar.properties[property],
+          value,
+          options,
+          [property],
+        )
+        if (property === 'padding' || property === 'margin') {
+          const parts =
+            typeof value === 'string' ? value.trim().split(/\s+/) : [value]
+          const [top, right = top, bottom = top, left = right] = parts.map(
+            (part) =>
+              Scalar.length(part, options, property === 'margin', [property]),
+          )
+          Object.assign(output, {
+            [`${property}Top`]: top,
+            [`${property}Right`]: right,
+            [`${property}Bottom`]: bottom,
+            [`${property}Left`]: left,
+          })
+        } else if (property === 'borderColor' || property === 'borderWidth') {
+          for (const side of ['Top', 'Right', 'Bottom', 'Left'])
+            output[
+              `border${side}${property === 'borderColor' ? 'Color' : 'Width'}`
+            ] = converted
+        } else if (property === 'borderRadius') {
+          for (const corner of [
+            'TopLeft',
+            'TopRight',
+            'BottomRight',
+            'BottomLeft',
+          ])
+            output[`border${corner}Radius`] = converted
+        } else if (property === 'gap') {
+          output.columnGap = converted
+          output.rowGap = converted
+        } else output[property] = converted
+      }
+    }
+    if (lineHeight !== undefined) {
+      if (typeof lineHeight === 'number') {
+        if (
+          !Number.isFinite(lineHeight) ||
+          lineHeight < 0 ||
+          typeof output.fontSize !== 'number'
+        )
+          throw new Native.SelectionError(
+            'Numeric lineHeight requires an explicit fontSize and a nonnegative finite multiplier.',
+          )
+        output.lineHeight = lineHeight * output.fontSize
+        if (!Number.isFinite(output.lineHeight))
+          throw new Native.SelectionError(
+            'Converted lineHeight must be finite.',
+          )
+      } else
+        output.lineHeight = Scalar.length(lineHeight, options, false, [
+          'lineHeight',
+        ])
+    }
+    const style = output as StyleSheet.NativeStyle
+    return { style: input.style ? [style, input.style] : style }
+  }
+}
+
+/** Compiler-owned metadata consumed by native dynamic application. */
+export declare namespace create {
+  /** Selected static data and ordered runtime bindings. */
+  type Options = Recipe.Definition &
+    Scalar.Options & {
+      /** Binding instructions containing no executable authoring code. */
+      readonly program: Program
+      /** Static fragments for one theme and color scheme. */
+      readonly styles: Readonly<Record<string, StyleSheet.NativeStyle>>
+    }
+}

package/src/runtime/PayloadRecipe.ts

@@ -0,0 +1,96 @@
+/** Binds scoped recipe payloads to precompiled per-condition variable slots. @module */
+import type { style } from '../styleFunction.js'
+import * as Html from './Html.js'
+import type * as Recipe from './Recipe.js'
+
+/** Creates a serializer over an already compiled recipe selection function. */
+export function create(options: create.Options) {
+  const axes = Object.keys(options.axes)
+  const catalog = new Map(
+    axes.map((axis) => [
+      axis,
+      new Map(
+        options.payloads
+          .filter((payload) => payload.axis === axis)
+          .map((payload) => [payload.choice, payload.slots]),
+      ),
+    ]),
+  )
+
+  return (input: Record<string, unknown> & style.Options = {}) => {
+    const bindings: Record<string, string | number> = {}
+    const normalized: Record<string, unknown> = { ...input }
+
+    function select(value: unknown, axis: string, context: number) {
+      if (value === null || typeof value !== 'object') return value
+
+      const choice = Object.keys(value)[0]!
+      const values = (value as Record<string, Record<string, string | number>>)[
+        choice
+      ]!
+      const slots = catalog.get(axis)!.get(choice)![context]!
+      for (const [field, name] of Object.entries(slots)) {
+        const value = values[field]!
+        bindings[name] = value === '' ? ' ' : value
+      }
+
+      return choice
+    }
+
+    for (const axis of axes) {
+      const value = Object.hasOwn(input, axis) ? input[axis] : undefined
+      const fallback =
+        options.defaultPayloads && Object.hasOwn(options.defaultPayloads, axis)
+          ? options.defaultPayloads[axis]
+          : undefined
+      normalized[axis] = select(
+        value === undefined && fallback
+          ? { [options.defaults[axis]!]: fallback }
+          : value,
+        axis,
+        0,
+      )
+    }
+
+    const conditions = input.conditions as
+      | Record<string, Record<string, unknown> | undefined>
+      | undefined
+    if (conditions) {
+      const selections: Record<string, Record<string, unknown>> = Object.create(
+        null,
+      )
+      for (const [index, name] of (options.conditions ?? []).entries()) {
+        const values = Object.hasOwn(conditions, name)
+          ? conditions[name]
+          : undefined
+        if (!values) continue
+
+        const selected: Record<string, unknown> = {}
+        for (const axis of axes)
+          if (Object.hasOwn(values, axis))
+            selected[axis] = select(values[axis], axis, index + 1)
+        selections[name] = selected
+      }
+      normalized.conditions = selections
+    }
+
+    const props = options.select(normalized) as style.Props
+    const result = Object.keys(bindings).length
+      ? { ...props, style: { ...props.style, ...bindings } }
+      : props
+    return options.html ? Html.from(result) : result
+  }
+}
+
+/** Fixed payload serializer inputs. */
+export declare namespace create {
+  /** Validated compiler metadata and a selection-only delegate. */
+  type Options = Recipe.Definition & {
+    /** Final output uses native HTML attributes when enabled. */
+    readonly html?: boolean | undefined
+    /** Dynamic choices present in this recipe. */
+    readonly payloads: readonly Recipe.Payload[]
+    /** Precompiled selector returning React-shaped props. */
+    readonly select: ReturnType<typeof Recipe.create>
+  }
+}

package/src/runtime/Props.ts

@@ -0,0 +1,33 @@
+/**
+ * Binds compiled classes to typed className and inline-style overrides.
+ * @module
+ */
+import type { style } from '../styleFunction.js'
+
+/**
+ * Binds compiled classes to the web styling override contract.
+ * Returns fresh props; without variable assignments, inline styles retain their identity.
+ * Never generates rules or changes the supplied overrides.
+ * @returns A callable accepting className, style, and variables.
+ */
+export function create({ className }: create.Options): style.ReturnType {
+  return ((overrides?: style.Options) => {
+    if (!overrides) return { className }
+
+    const { className: external, style, variables } = overrides
+    const inline = variables ? { ...variables, ...style } : style
+    const merged =
+      className && external ? `${className} ${external}` : external || className
+
+    return inline ? { className: merged, style: inline } : { className: merged }
+  }) as style.ReturnType
+}
+
+/** Contracts for generated static web callables. */
+export declare namespace create {
+  /** Compiled class binding. */
+  type Options = {
+    /** Complete generated class list. */
+    readonly className: string
+  }
+}

package/src/runtime/Recipe.ts

@@ -0,0 +1,74 @@
+/** Selects finite precompiled recipe alternatives without generating rules. @module */
+import type { style } from '../styleFunction.js'
+import * as Html from './Html.js'
+import * as Props from './Props.js'
+
+/** Compiler-owned static recipe metadata. */
+export type Definition = {
+  /** Ordered axis names and their finite choices. */
+  readonly axes: Readonly<Record<string, readonly string[]>>
+  /** Ordered named conditions; only CSS evaluates their queries. */
+  readonly conditions?: readonly string[] | undefined
+  /** Normalized default selections. */
+  readonly defaults: Readonly<Record<string, string | null>>
+  /** Complete scalar defaults for selected dynamic choices. */
+  readonly defaultPayloads?:
+    | { readonly [axis: string]: { readonly [field: string]: string | number } }
+    | undefined
+  /** Dynamic choices and separate base/conditional input slots. */
+  readonly payloads?: readonly Payload[] | undefined
+}
+
+/** Fixed input bindings for one dynamic choice. */
+export type Payload = {
+  /** Owning selection axis. */
+  readonly axis: string
+  /** Choice name used for selectors and compound matching. */
+  readonly choice: string
+  /** Base slots followed by slots for each condition in declaration order. */
+  readonly slots: readonly { readonly [field: string]: `--${string}` }[]
+}
+
+/**
+ * Binds an unconditional recipe class to selection attributes and styling overrides.
+ * Type checking and compilation validate authoring; this path only selects data.
+ * @param options - Precompiled classes, defaults, axes, and renderer output.
+ * @returns A selection callable producing fresh props without retaining inputs.
+ */
+export function create(options: create.Options) {
+  const props = Props.create({ className: options.className })
+  const axes = Object.keys(options.axes)
+
+  return (input: Record<string, unknown> & style.Options = {}) => {
+    const overrides: style.Options = input
+    const result: style.Props & Record<`data-${string}`, string> = {
+      ...props(overrides),
+    }
+
+    for (const axis of axes) {
+      const selected = Object.hasOwn(input, axis) ? input[axis] : undefined
+      const value = (
+        selected === undefined
+          ? Object.hasOwn(options.defaults, axis)
+            ? options.defaults[axis]
+            : undefined
+          : selected
+      ) as string | boolean | null | undefined
+      if (value !== null && value !== undefined)
+        result[`data-${axis}`] = String(value)
+    }
+
+    return options.html ? Html.from(result) : result
+  }
+}
+
+/** Generated recipe initialization inputs. */
+export declare namespace create {
+  /** Fixed metadata retained by the compiled callable. */
+  type Options = Pick<Definition, 'axes' | 'defaults'> & {
+    /** Complete compiled class list. */
+    readonly className: string
+    /** Whether to return native HTML attributes. */
+    readonly html?: boolean | undefined
+  }
+}

package/src/runtime/Selection.ts

@@ -0,0 +1,82 @@
+/** Selects compiler-owned theme classes without evaluating authoring code. @module */
+import * as Scheme from '../internal/Scheme.js'
+
+/**
+ * Creates a validated selector with the compatible named theme catalog.
+ * A selected scheme adds its stylesheet class beside the scope class and an inline `color-scheme`.
+ * @param entries Compatible theme names paired with compiler-owned scope classes.
+ * @param html Whether selection returns HTML class/serialized-style props. Defaults to false (React className/object-style props).
+ * @returns A callable selector with catalog members exposing their scope class names.
+ * @throws {TypeError} When selection names, schemes, or option keys are invalid.
+ */
+export function create<
+  const entries extends readonly (readonly [string, string])[],
+  const html extends boolean = false,
+>(entries: entries, html?: html): create.ReturnType<entries[number][0], html>
+export function create(
+  entries: readonly (readonly [string, string])[],
+  html = false,
+) {
+  const catalog = Object.fromEntries(entries)
+
+  const select = (input: { theme: string; colorScheme?: string }) => {
+    if (
+      !input ||
+      typeof input !== 'object' ||
+      Array.isArray(input) ||
+      !Object.hasOwn(input, 'theme') ||
+      typeof input.theme !== 'string' ||
+      !Object.hasOwn(catalog, input.theme) ||
+      Object.keys(input).some(
+        (key) => key !== 'theme' && key !== 'colorScheme',
+      ) ||
+      (input.colorScheme !== undefined &&
+        !['light', 'dark', 'light dark'].includes(input.colorScheme))
+    )
+      throw new TypeError('Invalid theme selection.')
+
+    const scheme = input.colorScheme as Scheme.Name | undefined
+
+    return {
+      [html ? 'class' : 'className']: scheme
+        ? `${catalog[input.theme]} ${Scheme.classes[scheme]}`
+        : catalog[input.theme],
+      ...(scheme
+        ? {
+            style: html ? `color-scheme:${scheme}` : { colorScheme: scheme },
+          }
+        : {}),
+    }
+  }
+
+  return Object.defineProperties(
+    select,
+    Object.getOwnPropertyDescriptors(
+      Object.fromEntries(
+        entries.map(([name, className]) => [name, { className }]),
+      ),
+    ),
+  ) as unknown as create.ReturnType<string, boolean>
+}
+
+/** Typed compiler-owned selection and compatible catalog members. */
+export declare namespace create {
+  type ReturnType<name extends string, html extends boolean = false> = {
+    <
+      const input extends {
+        readonly theme: name
+        readonly colorScheme?: 'light' | 'dark' | 'light dark' | undefined
+      },
+    >(
+      input: input &
+        Record<Exclude<keyof input, 'theme' | 'colorScheme'>, never>,
+    ): html extends true
+      ? { readonly class: string; readonly style?: string | undefined }
+      : {
+          readonly className: string
+          readonly style?:
+            | { readonly colorScheme: 'light' | 'dark' | 'light dark' }
+            | undefined
+        }
+  } & { readonly [key in name]: { readonly className: string } }
+}

package/src/runtime/Variable.ts

@@ -0,0 +1,15 @@
+/** Binds one compiler-assigned custom property to inline assignments. @module */
+import type * as Binding from '../internal/Binding.js'
+import type { variable } from '../variable.js'
+
+/** Creates an immutable reference with no CSS generation or value validation. */
+export function create<kind extends Binding.Domain>(
+  slot: Binding.Reference<kind>,
+): variable.Reference<kind> {
+  const { name } = slot
+  return Object.freeze({
+    ...slot,
+    [Symbol.toPrimitive]: () => name,
+    set: (value: Binding.Value<kind>) => Object.freeze({ [name]: value }),
+  }) as unknown as variable.Reference<kind>
+}

package/src/runtime/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Exposes the isolated helpers required by compiled callable styles.
+ * @module
+ */
+/** Server-safe root appearance initialization script generation. */
+export * as Appearance from './Appearance.js'
+
+/** Binding composition over statically resolved ordered groups. */
+export * as Composition from './Composition.js'
+
+/** Canonical HTML inputs retained only for compiled composition. */
+export * as CompositionHtml from './CompositionHtml.js'
+
+/** Conditional instructions isolated from unconditional recipes. */
+export * as ConditionalRecipe from './ConditionalRecipe.js'
+
+/** Runtime scalar binding isolated from static props. */
+export * as Dynamic from './Dynamic.js'
+
+/** Compiler-owned HTML attribute binding. */
+export * as Html from './Html.js'
+
+/** Static native selection and ordinary style-prop composition. */
+export * as Native from './Native.js'
+
+/** Render-local selection of compiled native alternatives. */
+export * as NativeContext from './NativeContext.js'
+
+/** Ordered native scalar bindings for generated dynamic callables. */
+export * as NativeDynamic from './NativeDynamic.js'
+
+/** Scoped recipe inputs bound to fixed variable slots. */
+export * as PayloadRecipe from './PayloadRecipe.js'
+
+/** Runtime props binding without parsing, compilation, or theme data. */
+export * as Props from './Props.js'
+
+/** Precompiled recipe selection and attribute serialization. */
+export * as Recipe from './Recipe.js'
+
+/** Validated selection of compiler-owned theme catalogs. */
+export * as Selection from './Selection.js'
+
+/** Compiler-generated variable contracts with typed assignments. */
+export * as Variable from './Variable.js'