zyzz 0.0.2 → 0.0.5

package/src/Style.ts

@@ -2,13 +2,16 @@
  * Copies typed style declarations into immutable, ordered, target-independent data.
  * @module
  */
+import * as VariableSets from './internal/VariableSets.js'
+import type * as Vars from './Vars.js'
 import * as Condition from './internal/Condition.js'
 import * as Query from './internal/Query.js'
 import * as Binding from './internal/Binding.js'
 import type * as Literal from './internal/Literal.js'
 import * as Token from './internal/Token.js'
+import * as Typography from './internal/Typography.js'
 import * as Value from './internal/Value.js'
-import type * as Theme from './Theme.js'
+import type * as Theme from './internal/Theme.js'
 import * as Targets from './internal/Targets.js'
 
 /** Validates only authored keys, recursively retaining nested token inference. */
@@ -24,7 +27,8 @@ export type Accepted<
     | Condition.Keys<tokens, Keys<style>>
     | 'selectors'
     | 'targets'
-    | 'variables'
+    | 'typography'
+    | 'vars'
   >,
   never
 > &
@@ -45,38 +49,46 @@ export type Accepted<
                     : never
                 }
               : never
-            : key extends 'variables'
+            : key extends 'vars'
               ? style[key] extends Record<string, unknown>
                 ? {
                     [name in keyof style[key]]: style[key][name] extends
                       | number
                       | string
                       ? Literal.Checked<style[key][name]>
-                      : never
+                      : literal extends true
+                        ? never
+                        : style[key][name] extends Token.Reference
+                          ? style[key][name]
+                          : never
                   }
                 : never
-              : key extends keyof Literal.Properties
-                ? Value.Accepted<
-                    Pick<style, key>,
-                    literal extends true
-                      ? LiteralDeclarations
-                      : DeclarationProperties<tokens>
-                  >[key] &
-                    Value.Checked<Pick<style, key>, tokens>[key]
-                : key extends Condition.Keys<tokens, key>
-                  ? [style[key]] extends [undefined]
-                    ? never
-                    : NonNullable<style[key]> extends Record<string, unknown>
-                      ?
-                          | Accepted<
-                              NonNullable<style[key]>,
-                              tokens,
-                              literal,
-                              targets
-                            >
-                          | Extract<style[key], undefined>
-                      : never
-                  : never
+              : key extends 'typography'
+                ? literal extends true
+                  ? never
+                  : Value.Atom<Typography.Names<tokens>>
+                : key extends keyof Literal.Properties
+                  ? Value.Accepted<
+                      Pick<style, key>,
+                      literal extends true
+                        ? LiteralDeclarations
+                        : DeclarationProperties<tokens>
+                    >[key] &
+                      Value.Checked<Pick<style, key>, tokens>[key]
+                  : key extends Condition.Keys<tokens, key>
+                    ? [style[key]] extends [undefined]
+                      ? never
+                      : NonNullable<style[key]> extends Record<string, unknown>
+                        ?
+                            | Accepted<
+                                NonNullable<style[key]>,
+                                tokens,
+                                literal,
+                                targets
+                              >
+                            | Extract<style[key], undefined>
+                        : never
+                    : never
       }
     : never)
 
@@ -162,6 +174,22 @@ export type Declaration = {
  * @returns Immutable definitions retaining the inferred style-name union.
  * @throws {InvalidError} If the input structure cannot represent ordered declarations.
  */
+export function define<
+  const values extends Vars.Values,
+  const styles extends Record<string, unknown>,
+>(
+  styles: styles &
+    NoInfer<Exact<styles, Vars.Mapped<values, {}>>> & {
+      [key in keyof styles]: WithoutRelationships<styles[key]>
+    },
+  options: {
+    readonly vars: Vars.Definition<values>
+    readonly locations?: readonly SourceLocation[]
+  },
+): Definition<
+  `${Extract<keyof styles, string | number>}`,
+  Targets.Domains<styles>
+>
 export function define<
   const styles extends Record<string, unknown>,
   const tokens extends Theme.Tokens,
@@ -189,6 +217,11 @@ export function define(
   styles: Record<string, unknown>,
   options: define.Options = {},
 ): Definition {
+  const theme =
+    options.vars &&
+    (typeof Reflect.get(options.vars, 'style') === 'function'
+      ? (options.vars as Theme.Definition)
+      : VariableSets.theme(options.vars as Vars.Definition))
   if ((options[nesting] ?? 0) > 128)
     throw new InvalidError([
       {
@@ -293,7 +326,7 @@ export function define(
     if (name.length === 0)
       report('invalid_structure', [name], 'Style names must not be empty.')
 
-    const mappings = options.theme?.[Token.definition].contract.shorthands
+    const mappings = theme?.[Token.definition].contract.shorthands
     const authored = entries(style, [name]).filter(
       ([key, value]) => key !== 'targets' || value !== undefined,
     )
@@ -364,21 +397,61 @@ export function define(
       continue
     }
 
-    const properties = authored.flatMap(([property, input]) =>
-      (mappings?.[property] ?? [property]).map(
-        (target) => [target, input, property] as const,
-      ),
+    const properties = authored.flatMap(
+      ([property, input]): readonly (readonly [string, unknown, string])[] => {
+        if (property !== 'typography')
+          return (mappings?.[property] ?? [property]).map(
+            (target) => [target, input, property] as const,
+          )
+
+        const parsed = Value.parse(input, 'fontFamily')
+        if (parsed && 'invalid' in parsed) {
+          report(
+            'invalid_value',
+            [name, property],
+            'Importance requires the suffix " !important".',
+          )
+          return []
+        }
+
+        const path = parsed?.value ?? input
+        const entries = Typography.entries(theme, path)
+        if (!entries.length) {
+          report(
+            'invalid_value',
+            [name, property],
+            'Expected a named typography set from the bound theme.',
+          )
+          return []
+        }
+
+        // Explicit declarations in this block override the corresponding preset fields.
+        const explicit = new Set(
+          authored.flatMap(([property]) => mappings?.[property] ?? [property]),
+        )
+        return Typography.entries(theme, path, explicit, parsed?.important).map(
+          ([field, value]) => [field, value, property] as const,
+        )
+      },
     )
 
     if (properties.some(([key]) => Condition.is(key))) {
       const rules: Rule[] = []
 
-      for (const [key, input] of authored) {
+      const blocks = authored.flatMap(([key, input]) =>
+        key === 'typography'
+          ? properties
+              .filter(([, , original]) => original === key)
+              .map(([property, value]) => [property, value] as const)
+          : [[key, input] as const],
+      )
+
+      for (const [key, input] of blocks) {
         try {
           const condition = Condition.is(key)
             ? Query.resolve(
                 key,
-                options.theme?.[Token.definition].queries ?? {
+                theme?.[Token.definition].queries ?? {
                   breakpoints: {},
                   containers: {},
                   containerNames: [],
@@ -535,7 +608,7 @@ export function define(
         const scalar = parsed ? parsed.value : entry
 
         const resolved = (() => {
-          if (!options.theme) return scalar
+          if (!theme) return scalar
 
           if (typeof scalar !== 'string' && typeof scalar !== 'number')
             return scalar
@@ -545,7 +618,7 @@ export function define(
 
           const resolved = Token.resolve(scalar, {
             property: key,
-            theme: options.theme,
+            theme,
           })
 
           if (Token.is(resolved)) {
@@ -559,6 +632,19 @@ export function define(
           return resolved
         })()
 
+        if (
+          Token.is(resolved) &&
+          resolved.contract.variableSet &&
+          !Token.acceptsReference(resolved, key)
+        ) {
+          report(
+            'invalid_value',
+            [name, authoredProperty],
+            'Variable value is incompatible with this property.',
+          )
+          continue
+        }
+
         const value = parsed && resolved === '0' ? 0 : resolved
 
         declarations.push(
@@ -583,9 +669,48 @@ export function define(
 
   if (diagnostics.length) throw new InvalidError(diagnostics)
 
+  const defaultLayer = theme?.[Token.definition].contract.defaultLayer
+  // Apply defaults after validation to retain authored diagnostic paths and explicit layer nesting.
+  function layered(style: NamedStyle): NamedStyle {
+    const { targets, ...body } = style
+    const rules = (() => {
+      if (style.rules)
+        return style.rules.map((rule) =>
+          rule.condition === '@layer' || rule.condition?.startsWith('@layer ')
+            ? rule
+            : Object.freeze({ ...rule, style: layered(rule.style) }),
+        )
+
+      if (!style.declarations.length) return []
+
+      return [
+        Object.freeze({
+          condition: `@layer ${defaultLayer}`,
+          style: Object.freeze(body),
+        }),
+      ]
+    })()
+
+    return Object.freeze({
+      ...body,
+      declarations: style.rules ? style.declarations : Object.freeze([]),
+      rules: Object.freeze(rules),
+      ...(targets
+        ? {
+            targets: Object.freeze({
+              ...targets,
+              ...(targets.web ? { web: layered(targets.web) } : {}),
+            }),
+          }
+        : {}),
+    })
+  }
+
   // Validated names are precisely the input's enumerable string keys.
   return Object.freeze({
-    styles: Object.freeze(output),
+    styles: Object.freeze(
+      defaultLayer && !options[nesting] ? output.map(layered) : output,
+    ),
   })
 }
 
@@ -601,11 +726,11 @@ export declare namespace define {
   } & ([tokens] extends [never]
     ? {
         /** Optional themes do not enable shorthand inference. */
-        readonly theme?: Theme.Definition | undefined
+        readonly vars?: Theme.Definition | Vars.Definition | undefined
       }
     : {
         /** Shorthand inference requires a defined token contract. */
-        readonly theme: Theme.Definition<tokens>
+        readonly vars: Theme.Definition<tokens>
       })
 }
 
@@ -691,7 +816,7 @@ export type DeclarationProperties<tokens extends Theme.Tokens = {}> = {
     | Value.Atom<Token.Names<tokens, property>>
     | {
         [group in Token.Group]: property extends Token.Properties<group>
-          ? Token.Reference<group>
+          ? Value.Atom<Token.Reference<group> | Token.Variable<group>>
           : never
       }[Token.Group]
   >
@@ -707,6 +832,8 @@ export type Properties<
   readonly targets?:
     | (targets extends true ? TargetBranches<tokens> : never)
     | undefined
+  /** Applies a named typography set. Explicit fields in the same block take precedence. */
+  readonly typography?: Value.Atom<Typography.Names<tokens>>
 }
 
 /** Nested literal declarations retain exact keys at every depth. */
@@ -739,7 +866,7 @@ type WithoutRelationships<value> = value extends readonly unknown[]
   ? unknown
   : value extends object
     ? {
-        [key in keyof value]: key extends symbol | 'selectors' | 'variables'
+        [key in keyof value]: key extends symbol | 'selectors' | 'vars'
           ? never
           : key extends keyof Literal.Properties
             ? unknown

package/src/Vars.ts

@@ -0,0 +1,299 @@
+/** Defines immutable variable sets and compatible scoped overrides. @module */
+import type * as Typography from './internal/Typography.js'
+import type * as Theme from './internal/Theme.js'
+import * as Identity from './internal/Identity.js'
+import type * as Literal from './internal/Literal.js'
+import * as Token from './internal/Token.js'
+import * as VariableSets from './internal/VariableSets.js'
+import type { style } from './styleFunction.js'
+
+/** Portable scalar reference with its accepted value domain. */
+export type Reference<group extends Token.Group = Token.Group> =
+  Token.Reference<group>
+
+const shape = Symbol('zyzz.variables.shape')
+
+/** A scalar, a color-scheme pair, or ordered media overrides with a required default. */
+export type Value =
+  | string
+  | number
+  | Token.Reference
+  | {
+      readonly light: string | Token.Reference
+      readonly dark: string | Token.Reference
+    }
+  | ({ readonly default: Value } & {
+      readonly [query: `@media ${string}`]: Value
+    })
+
+/** Nested categories and variable paths. */
+export type Values = {
+  readonly [key: string]: Value | Values | readonly string[]
+}
+
+/** Immutable references retaining their shared set contract. */
+export type Definition<values extends Values = Values> = (Values extends values
+  ? {}
+  : References<values>) & {
+  /** Authored value shape retained for inference. */
+  readonly [shape]: values
+  /** Compiler-owned identity and values. */
+  readonly [Token.definition]: Token.Metadata
+}
+
+/** Reference tree preserving the domain of each scalar leaf. */
+export type References<values, root extends boolean = true> = {
+  readonly [key in Exclude<
+    keyof values,
+    root extends true ? 'breakpoints' | 'containers' | 'containerNames' : never
+  >]: values[key] extends Value
+    ? Token.Reference<Domain<Scalar<values[key]>>> & {
+        readonly [Token.scalar]: Scalar<values[key]>
+      }
+    : References<values[key], false>
+}
+
+/** Resolves the scalar types represented by all conditional branches. */
+export type Scalar<value> = Value extends value
+  ? string | number
+  : value extends { readonly [Token.scalar]: infer scalar }
+    ? scalar
+    : value extends readonly string[]
+      ? value
+      : value extends Token.Reference<infer group>
+        ? group extends 'color'
+          ? Literal.Color
+          : group extends 'spacing'
+            ? Literal.Length
+            : group extends 'number'
+              ? number
+              : string
+        : value extends { default: unknown }
+          ? Scalar<value[keyof value]>
+          : value extends { light: infer light; dark: infer dark }
+            ? Scalar<light | dark>
+            : value
+
+/** Scalar domain shared by compatible set alternatives. */
+export type Domain<value> = [value] extends [Literal.Color]
+  ? 'color'
+  : [value] extends [Literal.Length]
+    ? 'spacing'
+    : [value] extends [number]
+      ? 'number'
+      : 'string'
+
+/** Creates typed references without emitting CSS or reading the environment. */
+export function define<const values extends Values>(
+  values: values & NoInfer<Validated<values, false, true>>,
+  options?: style.DefinitionOptions,
+): Definition<values>
+/** Deeply merges derived leaves, rejecting duplicate paths and leaf/category conflicts. */
+export function define<
+  const values extends Values,
+  const derived extends Values,
+>(
+  values: values & NoInfer<Validated<values, false, true>>,
+  derive: ((vars: References<values>) => derived) &
+    NoInfer<(vars: References<values>) => Validated<derived, false, true>>,
+  options?: style.DefinitionOptions,
+): Definition<Merge<values, derived>>
+export function define(
+  values: Values,
+  derive: style.DefinitionOptions | ((vars: References<Values>) => Values) = {},
+  options: style.DefinitionOptions = {},
+): Definition {
+  if (typeof derive !== 'function') options = derive
+
+  const contract = Object.freeze({
+    variableSet: true,
+    ...(options.id === undefined
+      ? {}
+      : {
+          [Token.identity]: Identity.requireId(options.id, 'Vars.define'),
+          [Token.complete]: true,
+        }),
+  })
+  const base = VariableSets.build(values, contract)
+  if (typeof derive !== 'function') return base
+
+  const merged = VariableSets.merge(values, derive(base as References<Values>))
+  return VariableSets.build(merged, contract)
+}
+
+type Merge<base, derived> = {
+  readonly [key in keyof base | keyof derived]: key extends keyof derived
+    ? key extends keyof base
+      ? Merge<base[key], derived[key]>
+      : derived[key]
+    : key extends keyof base
+      ? base[key]
+      : never
+}
+
+/** Replaces existing leaves while preserving paths, domains, and reference identity. */
+export function extend<const values extends Values>(
+  variables: Definition<values>,
+  overrides: Overrides<values>,
+): Definition<values> {
+  const metadata = Object.getOwnPropertyDescriptor(variables, Token.definition)
+    ?.value as Token.Metadata | undefined
+  if (!metadata?.contract.variableSet)
+    throw new InvalidError([], 'Expected a variable set.')
+  return VariableSets.build(
+    overrides,
+    metadata.contract,
+    metadata.values,
+    metadata.queries,
+    metadata.paths,
+  ) as Definition<values>
+}
+
+/** Partial compatible overrides. Conditional leaves are replaced in full. */
+export type Overrides<values> = {
+  readonly [key in keyof values]?: values[key] extends Value
+    ? Conditional<Compatible<Scalar<values[key]>>>
+    : Overrides<values[key]>
+}
+
+type Conditional<scalar> =
+  | scalar
+  | {
+      readonly default: Conditional<scalar>
+      readonly [query: `@media ${string}`]: Conditional<scalar>
+    }
+type Compatible<scalar> = [scalar] extends [Literal.Color]
+  ?
+      | Literal.Color
+      | Token.Reference<'color'>
+      | {
+          readonly light: Literal.Color | Token.Reference<'color'>
+          readonly dark: Literal.Color | Token.Reference<'color'>
+        }
+  : [scalar] extends [Literal.Length]
+    ? Literal.Length | Token.Reference<'spacing'>
+    : [scalar] extends [number]
+      ? number | Token.Reference<'number'>
+      : string | Token.Reference<'string'>
+
+/** Category names mapped to the CSS properties that accept their shorthand tokens. */
+export type Mappings = Readonly<
+  Record<string, readonly (keyof Literal.Properties)[]>
+>
+
+/** Type carrier for configured shorthand lookup. */
+export type Mapped<values, mappings> = (Pick<
+  values,
+  keyof values &
+    ('breakpoints' | 'containers' | 'containerNames' | 'typography')
+> extends infer metadata extends Theme.Tokens
+  ? metadata
+  : {}) & {
+  readonly color?: undefined
+  readonly '~vars': {
+    readonly values: values
+    readonly mappings: mappings
+  }
+}
+
+/** Reads the values declared by a reusable definition or inline set. */
+export type Extract<input> = input extends { readonly [shape]: infer values }
+  ? values
+  : input
+
+/** Invalid variable data with the offending path. */
+export class InvalidError extends Error {
+  /** Creates a diagnostic for invalid data at the supplied path. */
+  constructor(
+    readonly path: readonly string[],
+    message: string,
+  ) {
+    super(`${JSON.stringify(path)}: ${message}`)
+  }
+  /** Stable diagnostic name. */
+  override name = 'Vars.InvalidError'
+}
+
+type Validated<
+  value,
+  typography extends boolean = false,
+  root extends boolean = false,
+> = Values extends value
+  ? value
+  : value extends readonly string[]
+    ? never
+    : value extends Token.Reference
+      ? value
+      : value extends string | number
+        ? Literal.Checked<value>
+        : root extends true
+          ? {
+              readonly [key in keyof value]: key extends 'containerNames'
+                ? value[key] extends readonly string[]
+                  ? value[key]
+                  : never
+                : key extends
+                      | `${string}.${string}`
+                      | `${string}!${string}`
+                      | `@${string}`
+                      | ''
+                  ? never
+                  : Validated<
+                      value[key],
+                      key extends 'typography' ? true : false
+                    >
+            }
+          : value extends { default: infer base }
+            ? Conditional<Compatible<Scalar<base>>> &
+                Record<
+                  Exclude<keyof value, 'default' | `@media ${string}`>,
+                  never
+                >
+            : value extends { light: unknown; dark: unknown }
+              ? Pair<value>
+              : keyof value extends 'light' | 'dark'
+                ? Pair<value>
+                : {
+                    readonly [key in keyof value]: key extends
+                      | `${string}.${string}`
+                      | `${string}!${string}`
+                      | `@${string}`
+                      | ''
+                      ? typography extends true
+                        ? key extends Typography.Condition
+                          ? Validated<value[key], true>
+                          : never
+                        : never
+                      : Validated<
+                          value[key],
+                          key extends 'typography' ? true : typography
+                        >
+                  }
+
+/** Applies a compatible variable set and optional color scheme to a scope. */
+export type Selector<
+  name extends string,
+  output extends style.Output = 'react',
+> = {
+  <
+    const selection extends {
+      readonly set?: name | undefined
+      readonly colorScheme?: 'light' | 'dark' | 'light dark' | undefined
+    } = {},
+  >(
+    options?: selection &
+      Record<Exclude<keyof selection, 'set' | 'colorScheme'>, never>,
+  ): style.Props<output>
+}
+
+type Pair<value> = {
+  readonly light: Literal.Color | Token.Reference<'color'>
+  readonly dark: Literal.Color | Token.Reference<'color'>
+} & Record<Exclude<keyof value, 'light' | 'dark'>, never>
+
+/** Configured references and a selector for compatible scopes. */
+export type Bound<
+  values extends Values,
+  name extends string = never,
+  output extends style.Output = 'react',
+> = Definition<values> & Selector<name, output>