zyzz 0.0.3 → 0.0.5

package/src/Config.ts

@@ -1,691 +1,49 @@
-/**
- * Normalizes explicit configuration into isolated typed authoring contracts.
- * @module
- */
-import * as Appearance from './runtime/Appearance.js'
-import * as Authoring from './internal/Authoring.js'
-import * as Html from './runtime/CompositionHtml.js'
-import * as Identity from './internal/Identity.js'
-import type * as Binding from './internal/Binding.js'
-import type * as Condition from './internal/Condition.js'
-import type * as Literal from './internal/Literal.js'
-import type { style } from './styleFunction.js'
-import { variants } from './variants.js'
-import * as Scheme from './internal/Scheme.js'
-import * as Shorthands from './internal/Shorthands.js'
-import type * as Style from './Style.js'
-import * as Theme from './Theme.js'
-import * as Token from './internal/Token.js'
-
-/** Creates token-free authoring without a configuration file or global state. */
-export function create(): create.ReturnType<{}>
-/**
- * Binds inline or reusable themes to an isolated configuration contract.
- * Named themes require an explicit default and identical token paths/domains.
- * Bound helpers reference extracted CSS; this factory emits no CSS rules.
- * @throws {InvalidError} If options, themes, defaults, or layer names are invalid.
- */
-export function create<const options extends create.Options>(
-  options: options & NoInfer<Validated<options>>,
-): create.ReturnType<options>
-export function create(options: create.Options = {}): unknown {
-  const input = record(options)
-
-  for (const key of Object.keys(input))
-    if (
-      ![
-        'cssOutput',
-        'id',
-        'defaultTheme',
-        'layers',
-        'output',
-        'shorthands',
-        'storageKey',
-        'theme',
-        'themes',
-      ].includes(key)
-    )
-      throw new InvalidError(`Unknown configuration option: ${key}`)
-
-  if (
-    input.storageKey !== undefined &&
-    (typeof input.storageKey !== 'string' || !input.storageKey)
-  )
-    throw new InvalidError('storageKey must be a nonempty string.')
-
-  // Validated above; the record type erases the literal narrowing.
-  const storageKey = input.storageKey as string | undefined
-
-  if (
-    input.output !== undefined &&
-    input.output !== 'html' &&
-    input.output !== 'react'
-  )
-    throw new InvalidError('output must be html or react.')
-
-  if (
-    input.cssOutput !== undefined &&
-    input.cssOutput !== 'atomic' &&
-    input.cssOutput !== 'grouped'
-  )
-    throw new InvalidError('cssOutput must be atomic or grouped.')
-
-  if (input.theme !== undefined && input.themes !== undefined)
-    throw new InvalidError('Use either theme or themes, not both.')
-
-  if (input.layers !== undefined) {
-    if (!Array.isArray(input.layers))
-      throw new InvalidError('layers must be an array.')
-
-    const seen = new Set<string>()
-
-    for (const layer of input.layers) {
-      if (
-        typeof layer !== 'string' ||
-        !/^(?:--|-?[_a-zA-Z])[\w-]*(?:\.(?:--|-?[_a-zA-Z])[\w-]*)*$/.test(
-          layer,
-        ) ||
-        layer
-          .split('.')
-          .some((part) =>
-            [
-              'default',
-              'inherit',
-              'initial',
-              'revert',
-              'revert-layer',
-              'unset',
-            ].includes(part.toLowerCase()),
-          )
-      )
-        throw new InvalidError(
-          'Layer names must be plain CSS identifiers, optionally dotted.',
-        )
-
-      if (seen.has(layer)) throw new InvalidError(`Duplicate layer: ${layer}`)
-
-      seen.add(layer)
-    }
-  }
-
-  const shorthands = (() => {
-    if (input.shorthands === undefined) return undefined
-
-    try {
-      return Shorthands.read(input.shorthands)
-    } catch (error) {
-      throw new InvalidError((error as Error).message)
-    }
-  })()
-
-  const contract = Object.freeze({
-    cssOutput:
-      (input.cssOutput as 'atomic' | 'grouped' | undefined) ?? 'atomic',
-    ...(shorthands ? { shorthands } : {}),
-    ...(typeof input.id === 'string'
-      ? {
-          [Token.identity]: Identity.requireId(input.id, 'Config.create'),
-          [Token.complete]: true,
-        }
-      : {}),
-  })
-  function boundStyle(theme?: Theme.Definition) {
-    return (styles?: unknown, options: style.DefinitionOptions = {}) => {
-      if (
-        theme &&
-        Object.keys(theme[Token.definition].values).length &&
-        !contract[Token.identity]
+/** Binds shared vars, property mappings, and scoped alternatives to authoring. @module */
+import type * as Shorthands from './internal/Shorthands.js'
+import * as Configuration from './internal/Configuration.js'
+
+export { InvalidError } from './internal/Configuration.js'
+export type {
+  Body,
+  StyleFactory,
+  VariableConfig,
+  VariableOptions,
+  VariableScope,
+} from './internal/Configuration.js'
+
+/** Creates isolated authoring with optional vars and named alternatives. */
+export function create<const options extends create.Options = {}>(
+  options: options &
+    NoInfer<
+      options extends Configuration.VariableOptions
+        ? Configuration.VariableValidation<options>
+        : Record<Exclude<keyof options, keyof create.Options>, never> &
+            (options extends { shorthands: infer map extends Shorthands.Map }
+              ? { shorthands: Shorthands.Validated<map> }
+              : {})
+    > = {} as never,
+): create.ReturnType<options> {
+  for (const key of ['theme', 'themes', 'defaultTheme'])
+    if (Object.hasOwn(options, key))
+      throw new Configuration.InvalidError(
+        `Use vars and defaultVars instead of ${key}.`,
       )
-        Identity.requireId(undefined, 'Config.create')
-      return Authoring.create(styles, {
-        ...options,
-        theme,
-        output: input.output as style.Output | undefined,
-      })
-    }
-  }
-  function boundVariants(
-    definition: Record<string, unknown>,
-    options: style.DefinitionOptions = {},
-  ) {
-    return Authoring.variants(definition, {
-      ...options,
-      output: input.output as style.Output | undefined,
-    })
-  }
-  function handle(theme: Theme.Definition, name: string) {
-    const original = Token.bind(theme, contract)
-    const className = () =>
-      `z_theme-${Identity.requireId(typeof input.id === 'string' ? input.id : undefined, 'Config.create')}-${name.replace(/[^a-zA-Z0-9-]/g, (character) => `_${character.charCodeAt(0).toString(16)}_`)}`
-    const select = (options: { colorScheme?: string } = {}) => {
-      const scheme = options.colorScheme
-      const selection =
-        scheme !== undefined && Object.hasOwn(Scheme.classes, scheme)
-          ? ` ${Scheme.classes[scheme as Scheme.Name]}`
-          : ''
-      const result = {
-        className: `${className()}${selection}`,
-        ...(scheme ? { style: { colorScheme: scheme } } : {}),
-      }
-      return input.output === 'html' ? Html.from(result) : result
-    }
-    const descriptors = Object.getOwnPropertyDescriptors(original)
-    delete (descriptors as Record<string, unknown>).className
-    delete (descriptors as Record<string, unknown>).style
-    delete (descriptors as Record<string, unknown>).variants
-    Object.defineProperties(select, descriptors)
-    Object.defineProperty(select, 'className', {
-      get: className,
-      configurable: true,
-    })
-    Object.assign(select, {
-      style: boundStyle(original),
-      variants: boundVariants,
-    })
-    return select
-  }
-
-  if (input.themes !== undefined) {
-    const catalog = record(input.themes)
-    if (
-      typeof input.defaultTheme !== 'string' ||
-      !Object.hasOwn(catalog, input.defaultTheme)
-    )
-      throw new InvalidError('defaultTheme must name a theme in the catalog.')
-
-    const defaultTheme = input.defaultTheme
-    const definitions = Object.fromEntries(
-      Object.entries(catalog).map(([name, value]) => {
-        if (!name) throw new InvalidError('Theme names must be nonempty.')
-
-        return [name, definition(value)]
-      }),
-    )
-
-    const base = definitions[input.defaultTheme]!
-    const paths = Object.keys(base[Token.definition].values).sort()
-
-    function queries(theme: Theme.Definition) {
-      const data = theme[Token.definition].queries
-
-      return JSON.stringify({
-        breakpoints: Object.keys(data?.breakpoints ?? {}).sort(),
-        containers: Object.keys(data?.containers ?? {}).sort(),
-        containerNames: [...(data?.containerNames ?? [])].sort(),
-      })
-    }
-
-    for (const [name, value] of Object.entries(definitions)) {
-      const candidate = Object.keys(value[Token.definition].values).sort()
-      if (
-        queries(base) !== queries(value) ||
-        paths.length !== candidate.length ||
-        paths.some((path, index) => path !== candidate[index])
-      )
-        throw new InvalidError(
-          `Theme ${JSON.stringify(name)} must have the default theme's complete token paths and domains.`,
-        )
-    }
-
-    const bound = Object.fromEntries(
-      Object.entries(definitions).map(([name, value]) => [
-        name,
-        handle(value, name),
-      ]),
-    )
-
-    const select = (options: { theme: string; colorScheme?: string }) =>
-      (bound[options.theme] as (options: { colorScheme?: string }) => unknown)(
-        options,
-      )
-
-    Object.defineProperties(select, Object.getOwnPropertyDescriptors(bound))
-
-    const entries = () =>
-      Object.entries(bound).map(([name, value]): readonly [string, string] => [
-        name,
-        (value as unknown as Theme.Definition).className,
-      ])
-
-    // Class names require an identity, so the compiler's collection pass must
-    // not read them; root controls resolve their entries on first use.
-    const appearance = ((): Appearance.Root<string> => {
-      let root: Appearance.Root<string> | undefined
-      const resolve = () =>
-        (root ??= Appearance.root(entries(), { defaultTheme, storageKey }))
-
-      return {
-        get: () => resolve().get(),
-        set: (selection) => resolve().set(selection),
-      }
-    })()
-
-    return Object.freeze({
-      appearance,
-      script: () => Appearance.create(entries(), { storageKey })(),
-      style: boundStyle(
-        bound[input.defaultTheme] as unknown as Theme.Definition,
-      ),
-      theme: bound[input.defaultTheme],
-      themes: Object.freeze(select),
-      variants: boundVariants,
-    })
-  }
-
-  if (input.defaultTheme !== undefined)
-    throw new InvalidError('defaultTheme requires a named themes catalog.')
-
-  if (input.theme !== undefined) {
-    const theme = handle(definition(input.theme), 'theme')
-    return Object.freeze({
-      appearance: Appearance.root([], { storageKey }),
-      script: Appearance.create([], { storageKey }),
-      style: boundStyle(theme as unknown as Theme.Definition),
-      theme,
-      variants: boundVariants,
-    })
-  }
-
-  const theme = shorthands ? Token.bind(Theme.define({}), contract) : undefined
-  return Object.freeze({
-    appearance: Appearance.root([], { storageKey }),
-    script: Appearance.create([], { storageKey }),
-    style: boundStyle(theme),
-    variants: boundVariants,
-  })
+  return Configuration.create(
+    options as Configuration.VariableOptions,
+  ) as create.ReturnType<options>
 }
 
-/** Configuration inputs and inferred results. */
+/** Configuration input and inferred helpers. */
 export declare namespace create {
-  /** Optional layer names and mutually exclusive theme modes. */
-  type Options = {
-    /** CSS representation inherited by bound helpers; atomic by default. */
-    readonly cssOutput?: 'atomic' | 'grouped' | undefined
-    /** Stable theme identity required without source rewriting. */
-    readonly id?: string | undefined
-    /** Explicit ordered property aliases; none are installed by default. */
-    readonly shorthands?: Shorthands.Map | undefined
-    /** Renderer props format; React is the default. */
-    readonly output?: style.Output | undefined
-    /** Ordered plain or dotted CSS layer names; emission follows source integration. */
-    readonly layers?: readonly string[] | undefined
-    /** localStorage key shared by `script()` and `appearance`; zyzz by default. */
-    readonly storageKey?: string | undefined
-  } & (
-    | {
-        /** Single inline or reusable theme. */ readonly theme: Input
-        /** Named mode is excluded. */ readonly themes?: never
-        /** Only named catalogs use defaults. */ readonly defaultTheme?: never
-      }
-    | {
-        /** Explicit catalog key. */ readonly defaultTheme: string
-        /** Single mode is excluded. */ readonly theme?: never
-        /** Complete named theme alternatives. */ readonly themes: Readonly<
-          Record<string, Input>
-        >
-      }
-    | {
-        /** Only named catalogs use defaults. */ readonly defaultTheme?: never
-        /** Omit themes for token-free authoring. */ readonly theme?: never
-        /** Omit themes for token-free authoring. */ readonly themes?: never
-      }
-  )
-
-  /** Bound authoring and the handles corresponding to the selected theme mode. */
-  type ReturnType<options extends Options = Options> = {
-    /** Reads and persists the root theme and scheme selection on the document element. */
-    readonly appearance: Appearance.Root<
-      options extends { themes: infer catalog } ? keyof catalog & string : never
-    >
-    /** Generates synchronous HTML-safe root preference restoration. */
-    readonly script: () => string
-    /** Inferred callable authoring; execution requires a source transform. */
-    readonly style: StyleFactory<
-      Tokens<options>,
-      options extends { layers: readonly (infer name extends string)[] }
-        ? name
-        : never,
-      options extends { output: infer output extends style.Output }
-        ? output
-        : 'react',
-      Mappings<options>
-    >
-    /** Theme-, layer-, and mapping-aware recipe authoring. */
-    readonly variants: variants.Bound<
-      Tokens<options>,
-      options extends { output: infer output extends style.Output }
-        ? output
-        : 'react',
-      options extends { layers: readonly (infer name extends string)[] }
-        ? name
-        : never,
-      Mappings<options>
-    >
-  } & (options extends { theme: infer input }
-    ? {
-        /** Isolated single-theme contract. */ readonly theme: Handle<
-          ExtractTokens<input>,
-          Mappings<options>,
-          options extends { output: infer output extends style.Output }
-            ? output
-            : 'react'
+  /** Variable sets and optional authoring settings. */
+  type Options =
+    | Configuration.VariableOptions
+    | Omit<Configuration.VariableOptions, 'vars' | 'defaultVars' | 'mappings'>
+  /** Typed helpers selected by the supplied variable contract. */
+  type ReturnType<options extends Options = Options> =
+    options extends Configuration.VariableOptions
+      ? Configuration.VariableConfig<options>
+      : Configuration.create.ReturnType<
+          Extract<options, Configuration.create.Options>
         >
-      }
-    : options extends { themes: infer catalog }
-      ? {
-          /** Shared default token and variable contract. */ readonly theme: Handle<
-            Tokens<options>,
-            Mappings<options>,
-            options extends { output: infer output extends style.Output }
-              ? output
-              : 'react'
-          >
-          /** Selects a compiled named scope; catalog members retain compatibility. */ readonly themes: (<
-            const selection extends {
-              readonly colorScheme?: 'dark' | 'light' | 'light dark' | undefined
-              readonly theme: keyof catalog & string
-            },
-          >(
-            options: selection &
-              Record<Exclude<keyof selection, 'theme' | 'colorScheme'>, never>,
-          ) => style.Props<
-            options extends { output: infer output extends style.Output }
-              ? output
-              : 'react'
-          >) & {
-            readonly [name in keyof catalog]: Handle<
-              ExtractTokens<catalog[name]>,
-              Mappings<options>,
-              options extends { output: infer output extends style.Output }
-                ? output
-                : 'react'
-            >
-          }
-        }
-      : {})
-}
-
-type Mappings<options> = options extends {
-  shorthands: infer map extends Shorthands.Map
-}
-  ? string extends keyof map
-    ? {}
-    : map
-  : {}
-
-/** Theme handle retaining configured shorthands and renderer output in emitted declarations. */
-export type Handle<
-  tokens extends Theme.Tokens,
-  mappings extends Shorthands.Map,
-  output extends style.Output,
-> = Omit<Theme.Definition<tokens>, 'style' | 'variants'> & {
-  /** Style factory bound to this handle. */
-  readonly style: StyleFactory<tokens, never, output, mappings>
-  /** Variant factory bound to this handle. */
-  readonly variants: variants.Bound<tokens, output, never, mappings>
-}
-
-/** Configured style factory with a portable name for library declaration emission. */
-export type StyleFactory<
-  tokens extends Theme.Tokens,
-  layers extends string,
-  output extends style.Output,
-  mappings extends Shorthands.Map,
-> = {
-  (): style.ReturnType<output>
-  <
-    const values extends Record<string, string | number>,
-    const styles extends Record<string, unknown>,
-    const callback extends (...args: never[]) => unknown,
-  >(
-    styles: callback &
-      ((
-        values: values,
-      ) => styles &
-        NoInfer<
-          Body<styles, tokens, layers, mappings> & Binding.Checked<styles>
-        >) &
-      CompletionProperties<tokens, NoInfer<styles>>,
-    ...options: Parameters<callback> extends [Record<string, string | number>]
-      ? values extends Binding.Inputs<values>
-        ? [options?: style.DefinitionOptions]
-        : [invalid: never, unavailable: never]
-      : [invalid: never, unavailable: never]
-  ): style.Dynamic<values, output>
-  <const styles extends Record<string, unknown>>(
-    styles: styles &
-      NoInfer<Body<styles, tokens, layers, mappings>> &
-      CompletionProperties<tokens>,
-    options?: style.DefinitionOptions,
-  ): style.ReturnType<output>
-}
-
-type Keys<styles> = styles extends unknown ? keyof styles : never
-
-/** Keeps completion hints separate from inferred declaration validation. */
-type CompletionProperties<tokens, styles = Record<string, unknown>> = {
-  readonly [property in keyof Literal.Properties & keyof styles]?:
-    | (string extends Literal.Properties[property]
-        ? never
-        : Literal.Properties[property])
-    | Token.Names<tokens, property>
-    | (string & {})
-    | number
-    | object
-}
-
-/** Checked declaration body shared by configured styles and recipe choices. */
-export type Body<
-  styles,
-  tokens extends Theme.Tokens,
-  layers extends string,
-  mappings extends Shorthands.Map,
-  targets extends boolean = true,
-> = Record<
-  Exclude<
-    Keys<styles>,
-    | keyof mappings
-    | 'selectors'
-    | 'targets'
-    | 'typography'
-    | 'variables'
-    | keyof Style.DeclarationProperties
-    | Exclude<Condition.Keys<tokens, Keys<styles>>, `@layer${string}`>
-    | '@layer'
-    | `@layer ${layers}`
-  >,
-  never
-> &
-  (styles extends unknown
-    ? {
-        [key in keyof styles]: key extends 'targets'
-          ? targets extends false
-            ? never
-            : styles[key] extends undefined
-              ? undefined
-              : {
-                  [target in keyof styles[key]]: target extends 'web'
-                    ?
-                        | Body<
-                            NonNullable<styles[key][target]>,
-                            tokens,
-                            layers,
-                            mappings,
-                            false
-                          >
-                        | Extract<styles[key][target], undefined>
-                    : Style.Accepted<
-                        { targets: Pick<styles[key], target> },
-                        tokens
-                      >['targets'][target]
-                }
-          : key extends 'selectors'
-            ? styles[key] extends Record<string, unknown>
-              ? {
-                  [selector in keyof styles[key]]: styles[key][selector] extends Record<
-                    string,
-                    unknown
-                  >
-                    ? Body<
-                        styles[key][selector],
-                        tokens,
-                        layers,
-                        mappings,
-                        targets
-                      >
-                    : never
-                }
-              : never
-            : key extends
-                  | Exclude<Condition.Keys<tokens, key>, `@layer${string}`>
-                  | '@layer'
-                  | `@layer ${layers}`
-              ? styles[key] extends Record<string, unknown>
-                ? Body<styles[key], tokens, layers, mappings, targets>
-                : never
-              : key extends keyof mappings
-                ? {
-                    [target in mappings[key][number]]: styles[key] extends Style.Accepted<
-                      Record<target, styles[key]>,
-                      tokens
-                    >[target] &
-                      Binding.Checked<Record<target, styles[key]>>[target]
-                      ? never
-                      : target
-                  }[mappings[key][number]] extends never
-                  ? styles[key]
-                  : never
-                : Style.Accepted<Pick<styles, key>, tokens>[key]
-      }
-    : never)
-
-function definition(value: unknown): Theme.Definition {
-  try {
-    if (
-      value &&
-      typeof value === 'object' &&
-      Object.getOwnPropertyDescriptor(value, Token.definition)?.value
-    )
-      return value as Theme.Definition
-
-    return Theme.define(record(value) as Theme.Tokens)
-  } catch (error) {
-    if (error instanceof InvalidError) throw error
-
-    throw new InvalidError((error as Error).message)
-  }
-}
-
-type ExtractTokens<input> =
-  input extends Theme.Definition<infer tokens>
-    ? tokens
-    : input extends Theme.Tokens
-      ? input
-      : never
-
-type Input = Theme.Definition | Theme.Tokens
-
-/** Invalid options or incompatible named themes. */
-export class InvalidError extends Error {
-  /** Creates a configuration diagnostic without generating styles. */
-  constructor(message: string) {
-    super(message)
-  }
-  /** Stable namespaced error identifier. */
-  override name = 'Config.InvalidError'
-}
-
-function record(value: unknown): Record<string, unknown> {
-  if (
-    !value ||
-    typeof value !== 'object' ||
-    Array.isArray(value) ||
-    ![null, Object.prototype].includes(Object.getPrototypeOf(value))
-  )
-    throw new InvalidError('Expected a plain configuration record.')
-
-  const result: Record<string, unknown> = Object.create(null)
-
-  for (const [key, descriptor] of Object.entries(
-    Object.getOwnPropertyDescriptors(value),
-  )) {
-    if (!('value' in descriptor))
-      throw new InvalidError('Configuration records cannot contain accessors.')
-
-    result[key] = descriptor.value
-  }
-
-  return result
 }
-
-type Tokens<options> = options extends { theme: infer input }
-  ? ExtractTokens<input>
-  : options extends { themes: infer catalog; defaultTheme: infer key }
-    ? key extends keyof catalog
-      ? ExtractTokens<catalog[key]>
-      : never
-    : {}
-
-type ValidInput<input> = input extends Theme.Definition
-  ? input
-  : input extends Theme.Tokens
-    ? Parameters<typeof Theme.define<input>>[0]
-    : never
-
-type Match<input, base> = base extends
-  | string
-  | number
-  | { light: string; dark: string }
-  ? input
-  : {
-      [key in keyof input | keyof base]: key extends keyof input
-        ? key extends keyof base
-          ? key extends 'containerNames'
-            ? input[key] extends readonly string[]
-              ? base[key] extends readonly string[]
-                ?
-                    | Exclude<input[key][number], base[key][number]>
-                    | Exclude<
-                        base[key][number],
-                        input[key][number]
-                      > extends never
-                  ? input[key]
-                  : never
-                : never
-              : never
-            : Match<input[key], base[key]>
-          : never
-        : never
-    }
-
-type Validated<options> = Record<
-  Exclude<keyof options, keyof create.Options>,
-  never
-> &
-  (options extends { shorthands: infer mappings extends Shorthands.Map }
-    ? { shorthands: Shorthands.Validated<mappings> }
-    : {}) &
-  (options extends { theme: infer input }
-    ? { theme: ValidInput<input> }
-    : options extends { themes: infer catalog; defaultTheme: infer key }
-      ? {
-          defaultTheme: keyof catalog
-          themes: {
-            [name in keyof catalog]: ValidInput<catalog[name]> &
-              (key extends keyof catalog
-                ? catalog[name] extends Theme.Definition
-                  ? Theme.Definition<
-                      ExtractTokens<catalog[name]> &
-                        Match<
-                          ExtractTokens<catalog[name]>,
-                          ExtractTokens<catalog[key]>
-                        >
-                    >
-                  : Match<
-                      ExtractTokens<catalog[name]>,
-                      ExtractTokens<catalog[key]>
-                    >
-                : never)
-          }
-        }
-      : {})