zyzz 0.0.3 → 0.0.5

package/src/{Theme.ts → internal/Theme.ts}

@@ -2,17 +2,18 @@
  * Defines typed token contracts and compatible immutable theme overrides.
  * @module
  */
-import { MissingTransformError, style } from './styleFunction.js'
-import * as Authoring from './internal/Authoring.js'
-import * as Identity from './internal/Identity.js'
-import { variants } from './variants.js'
-import type * as Binding from './internal/Binding.js'
-import type * as Literal from './internal/Literal.js'
-import * as Query from './internal/Query.js'
-import * as Token from './internal/Token.js'
-import * as Typography from './internal/Typography.js'
-import type * as Value from './internal/Value.js'
-import type * as Style from './Style.js'
+import { MissingTransformError, style } from '../styleFunction.js'
+import * as Authoring from './Authoring.js'
+import * as Identity from './Identity.js'
+import { variants } from '../variants.js'
+import type * as Binding from './Binding.js'
+import type * as Literal from './Literal.js'
+import * as Query from './Query.js'
+import * as Token from './Token.js'
+import * as Typography from './Typography.js'
+import type * as Value from './Value.js'
+import type * as Style from '../Style.js'
+import * as Condition from './Condition.js'
 
 /** Complete color-scheme pair or a shared color. */
 export type Color =
@@ -96,7 +97,7 @@ export type Definition<
   /** Token-aware single-element recipe authoring. */
   readonly variants: boundVariants
   /** Web variable references; source templates retain their identity and fallback. */
-  readonly vars: Token.Variables<References<tokens>>
+  readonly vars: Token.Vars<References<tokens>>
 }
 
 /**
@@ -128,6 +129,8 @@ export function extend<
     data.contract,
     data.values,
     data.queries,
+    undefined,
+    data.paths,
   ) as unknown as Definition<tokens, boundStyle, boundVariants>
 }
 
@@ -218,6 +221,7 @@ type ReferenceTree<
 type Scalar<group> = group extends
   | 'spacing'
   | 'borderRadius'
+  | 'borderWidth'
   | 'margin'
   | 'padding'
   ? Literal.Length
@@ -242,6 +246,10 @@ export type Tokens = {
   readonly borderColor?: Palette<Color> | undefined
   /** Nonnegative corner radii. */
   readonly borderRadius?: Palette<Literal.Length> | undefined
+  /** Nonnegative widths for physical and logical border declarations. */
+  readonly borderWidth?:
+    | Palette<Exclude<Literal.Length, `${number}%`>>
+    | undefined
   /** Compile-time viewport width thresholds. */
   readonly breakpoints?: Readonly<Record<string, Query.Length>> | undefined
   /** Shared colors available to every supported color property. */
@@ -288,6 +296,7 @@ function build(
   base?: Readonly<Record<string, Token.Value>>,
   baseQueries?: Query.Metadata,
   scope?: string,
+  basePaths?: Readonly<Record<string, readonly string[]>>,
 ) {
   const values: Record<string, Token.Value> = Object.assign(
     Object.create(null),
@@ -306,6 +315,9 @@ function build(
     ) as Record<string, string>,
   }
 
+  const paths: Record<string, readonly string[]> = { ...basePaths }
+  const conditions: (readonly string[])[] = []
+
   let hasQueries = !!baseQueries
   const active = new Set<object>()
 
@@ -315,6 +327,8 @@ function build(
     path: readonly string[],
   ) {
     const key = path.join('.')
+    if (path.some((part) => part.startsWith('@')))
+      paths[key] = Object.freeze([...path])
     const scalar = typeof value === 'string' || typeof value === 'number'
     if (group === 'typography' && scalar)
       throw new InvalidError(
@@ -374,6 +388,24 @@ function build(
 
     for (const [name, child] of entries!) {
       const next = [...path, name]
+      if (group === 'typography' && name.startsWith('@')) {
+        if (!Typography.condition(name))
+          throw new InvalidError(
+            next,
+            'Typography conditions must be media or container queries.',
+          )
+        conditions.push(next)
+      }
+      if (
+        group === 'typography' &&
+        path.some((part) => part.startsWith('@')) &&
+        !Typography.condition(name) &&
+        !Typography.properties.includes(name as Typography.Property)
+      )
+        throw new InvalidError(
+          next,
+          'Typography query blocks accept only typography fields and queries.',
+        )
       if (
         base &&
         !Object.keys(base).some(
@@ -482,6 +514,7 @@ function build(
         'backgroundColor',
         'borderColor',
         'borderRadius',
+        'borderWidth',
         'color',
         'margin',
         'padding',
@@ -510,7 +543,8 @@ function build(
     for (const [name, value] of entries) {
       if (
         group === 'typography' &&
-        Typography.properties.includes(name as Typography.Property)
+        (Typography.properties.includes(name as Typography.Property) ||
+          name.startsWith('@'))
       )
         throw new InvalidError(
           [group, name],
@@ -520,12 +554,20 @@ function build(
     }
   }
 
+  for (const path of conditions) {
+    try {
+      Condition.normalize(Query.resolve(path.at(-1)!, queries))
+    } catch (error) {
+      throw new InvalidError(path, (error as Error).message)
+    }
+  }
+
   type Tree = { [key: string]: Tree | Token.Reference }
 
   const tokens: Tree = Object.create(null)
 
   for (const [path, value] of Object.entries(values)) {
-    const parts = path.split('.')
+    const parts = paths[path] ?? path.split('.')
     let tree = tokens
 
     for (const part of parts.slice(0, -1))
@@ -577,6 +619,7 @@ function build(
       {
         value: Object.freeze({
           contract,
+          ...(Object.keys(paths).length ? { paths: Object.freeze(paths) } : {}),
           values: Object.freeze(values),
           ...(hasQueries
             ? {
@@ -627,7 +670,8 @@ function record(
     if (
       typeof key !== 'string' ||
       !key ||
-      key.includes('.') ||
+      (key.includes('.') &&
+        !(path[0] === 'typography' && Typography.condition(key))) ||
       !descriptor.enumerable ||
       !('value' in descriptor)
     )
@@ -694,7 +738,7 @@ type ValidPalette<palette, group> = palette extends undefined
       [key in keyof palette]: key extends `${string}!${string}`
         ? never
         : group extends 'typography'
-          ? key extends Typography.Property
+          ? key extends Typography.Property | `@${string}`
             ? never
             : ValidTree<palette[key], group>
           : ValidTree<palette[key], group>
@@ -767,11 +811,22 @@ type ValidTree<tree, group> = tree extends string | number
         [key in keyof tree]: key extends `${string}!${string}`
           ? never
           : group extends 'typography'
-            ? key extends Typography.Property
-              ? tree[key] extends string | number
-                ? ValidTree<tree[key], key>
+            ? key extends `@${string}`
+              ? key extends Typography.Condition
+                ? ValidTree<tree[key], group> &
+                    Record<
+                      Exclude<
+                        keyof tree[key],
+                        Typography.Property | Typography.Condition
+                      >,
+                      never
+                    >
                 : never
-              : ValidTree<tree[key], group>
+              : key extends Typography.Property
+                ? tree[key] extends string | number
+                  ? ValidTree<tree[key], key>
+                  : never
+                : ValidTree<tree[key], group>
             : ValidTree<tree[key], group>
       }
     : group extends 'color' | 'backgroundColor' | 'borderColor' | 'textColor'

package/src/internal/Token.ts

@@ -2,19 +2,28 @@
  * Carries portable theme references and enforces their property domains.
  * @module
  */
-import type * as Binding from './Binding.js'
+import * as Binding from './Binding.js'
 import type * as Query from './Query.js'
 import type * as Shorthands from './Shorthands.js'
-import type * as Theme from '../Theme.js'
+import type * as Theme from './Theme.js'
+import type * as ValueSyntax from './Value.js'
+import type * as VariableSets from '../Vars.js'
 import * as Literal from './Literal.js'
+import * as VariableData from './VariableSets.js'
 
 /** Checks a reference's property domain. */
 export function accepts(
   group: Group,
   property: keyof Literal.Properties,
 ): boolean {
+  if (property.startsWith('--')) return true
+  if (group === 'number' || group === 'string') return false
   if (group === 'color') return Literal.rule(property)?.kind === 'color'
   if (group === 'borderColor') return /^border.*Color$/.test(property)
+  if (group === 'borderWidth')
+    return /^border(?:Block|Inline)?(?:Start|End|Top|Right|Bottom|Left)?Width$/.test(
+      property,
+    )
   if (group === 'borderRadius') return /^border.*Radius$/.test(property)
   if (group === 'textColor') return property === 'color'
 
@@ -57,6 +66,50 @@ export function accepts(
   return group === property
 }
 
+/** Checks explicit variable values independently of shorthand category mappings. */
+export function acceptsReference(
+  reference: Reference,
+  property: keyof Literal.Properties,
+): boolean {
+  if (!reference.contract.variableSet) return accepts(reference.group, property)
+  if (property.startsWith('--')) return true
+  function check(value: Value): boolean {
+    if (is(value)) return acceptsReference(value, property)
+    if (typeof value === 'object') return Object.values(value).every(check)
+    if (typeof value === 'number') {
+      const rule = Literal.rule(property)
+      if (rule?.kind === 'number')
+        return (
+          value >= rule.min &&
+          value <= rule.max &&
+          (!rule.integer || Number.isInteger(value))
+        )
+      return value === 0 && Binding.accepts('length', property)
+    }
+    if (reference.group === 'color') return Binding.accepts('color', property)
+    if (reference.group === 'spacing')
+      return (
+        (Literal.rule(property)?.kind === 'compound' &&
+          accepts('spacing', property)) ||
+        Binding.accepts(
+          value.endsWith('%')
+            ? value.startsWith('-')
+              ? 'signedPercentage'
+              : 'percentage'
+            : value.startsWith('-')
+              ? 'signedLength'
+              : 'length',
+          property,
+        )
+      )
+    return (
+      Literal.isLiteral(property, value) ||
+      Literal.rule(property)?.kind === 'compound'
+    )
+  }
+  return check(reference.value)
+}
+
 /** Rebinds validated scalar references to a explicitly owned contract identity. */
 export function bind<tokens extends Theme.Tokens>(
   original: Theme.Definition<tokens>,
@@ -64,6 +117,9 @@ export function bind<tokens extends Theme.Tokens>(
 ): Theme.Definition<tokens> {
   type Tree = { [key: string]: Reference | Tree }
 
+  const metadata = original[definition]
+  const values = VariableData.rebind(metadata, contract)
+
   function rebind(tree: Theme.References<Theme.Tokens>): Tree {
     return Object.freeze(
       Object.fromEntries(
@@ -74,7 +130,7 @@ export function bind<tokens extends Theme.Tokens>(
                 contract,
                 group: value.group,
                 path: value.path,
-                value: value.value,
+                value: values[value.path]!,
               })
             : rebind(value as Theme.References<Theme.Tokens>),
         ]),
@@ -96,7 +152,7 @@ export function bind<tokens extends Theme.Tokens>(
         vars: variables(tokens),
       },
       definition,
-      { value: Object.freeze({ ...original[definition], contract }) },
+      { value: Object.freeze({ ...metadata, contract, values }) },
     ),
   ) as Theme.Definition<tokens>
 }
@@ -106,8 +162,14 @@ export const complete = Symbol('zyzz.contract.complete')
 
 /** Opaque data shared by a definition and its compatible extensions. */
 export type Contract = {
+  /** Whether values belong to independent variables rather than fixed theme categories. */
+  readonly variableSet?: boolean | undefined
+  /** Configuration-local category-to-property mappings. */
+  readonly mappings?: VariableSets.Mappings | false | undefined
   /** Web emission mode retained by configuration-bound theme handles. */
   readonly cssOutput?: 'atomic' | 'grouped' | undefined
+  /** Fallback layer for declarations without an explicit layer. */
+  readonly defaultLayer?: string | undefined
   /** Configuration-local property aliases, inherited by bound handles. */
   readonly shorthands?: Shorthands.Map | undefined
   readonly [complete]?: boolean | undefined
@@ -153,23 +215,24 @@ export function compose(
 export const web = Symbol('zyzz.web.variable')
 
 /** Web reference with the original token domain. */
-export type Variable<group extends Group = Group> = Reference<group> & {
-  readonly [web]: true
-}
+export type Variable<group extends Group = Group> = `var(--${string})` &
+  Reference<group> & {
+    readonly [web]: true
+  }
 
 /** Replaces portable scalar leaves with web-only references. */
-export type Variables<tree> =
+export type Vars<tree> =
   tree extends Reference<infer group>
     ? Variable<group>
-    : { readonly [key in keyof tree]: Variables<tree[key]> }
+    : { readonly [key in keyof tree]: Vars<tree[key]> }
 
 /** Creates web-only reference leaves without changing contract identities. */
-export function variables<tree>(tree: tree): Variables<tree> {
+export function variables<tree>(tree: tree): Vars<tree> {
   if (is(tree))
     return Object.freeze({
       ...tree,
       [web]: true as const,
-    }) as unknown as Variables<tree>
+    }) as unknown as Vars<tree>
 
   return Object.freeze(
     Object.fromEntries(
@@ -178,7 +241,7 @@ export function variables<tree>(tree: tree): Variables<tree> {
         variables(value),
       ]),
     ),
-  ) as Variables<tree>
+  ) as Vars<tree>
 }
 
 /** Internal definition metadata; never enumerable consumer output. */
@@ -186,9 +249,12 @@ export const definition = Symbol('zyzz.theme')
 
 /** Supported scalar token groups. */
 export type Group =
+  | 'number'
+  | 'string'
   | 'backgroundColor'
   | 'borderColor'
   | 'borderRadius'
+  | 'borderWidth'
   | 'color'
   | 'margin'
   | 'padding'
@@ -223,19 +289,53 @@ export function is(value: unknown): value is Reference {
 
 /** Immutable theme data carried directly by each definition. */
 export type Metadata = {
+  /** Original segments for typography paths containing query punctuation. */
+  readonly paths?: Readonly<Record<string, readonly string[]>> | undefined
   readonly queries?: Query.Metadata | undefined
   readonly contract: Contract
   readonly values: Readonly<Record<string, Value>>
 }
 
-/** Inferred shorthand names whose leaves belong to a property's domain. */
-export type Names<tokens, property extends keyof Literal.Properties> = {
-  [group in Extract<keyof tokens, Group>]: property extends Properties<group>
-    ? Paths<NonNullable<tokens[group]>>
-    : never
-}[Extract<keyof tokens, Group>]
+/** Literal domain carried by explicit variable references during type checking. */
+export const scalar = Symbol('zyzz.variable.scalar')
 
-type Paths<tree> = [tree] extends [never]
+/** Inferred shorthand names whose leaves belong to a property domain. */
+export type Names<
+  tokens,
+  property extends keyof Literal.Properties,
+> = tokens extends {
+  readonly '~vars': { values: infer values; mappings: infer mappings }
+}
+  ? mappings extends false
+    ? Paths<
+        Omit<values, 'breakpoints' | 'containers' | 'containerNames'>,
+        property
+      >
+    : {
+        [category in keyof values]: category extends keyof mappings
+          ? mappings[category] extends readonly unknown[]
+            ? property extends mappings[category][number]
+              ? Paths<values[category], property>
+              : never
+            : never
+          : category extends Group
+            ? property extends Properties<category>
+              ? Paths<values[category], property>
+              : never
+            : never
+      }[keyof values]
+  : {
+      [group in Extract<
+        keyof tokens,
+        Group
+      >]: property extends Properties<group>
+        ? Paths<NonNullable<tokens[group]>>
+        : never
+    }[Extract<keyof tokens, Group>]
+
+type Paths<tree, property extends keyof Literal.Properties = never> = [
+  tree,
+] extends [never]
   ? never
   : string extends keyof tree
     ? string
@@ -243,72 +343,95 @@ type Paths<tree> = [tree] extends [never]
         [key in Extract<keyof tree, number | string>]: NonNullable<
           tree[key]
         > extends Value
-          ?
-              | key
-              | `${key}`
-              | (key extends `${infer numericKey extends number}`
-                  ? `${numericKey}` extends key
-                    ? numericKey
-                    : never
-                  : never)
-          : `${key}.${Paths<NonNullable<tree[key]>>}`
+          ? [property] extends [never]
+            ? PathKey<key>
+            : VariableSets.Scalar<
+                  NonNullable<tree[key]>
+                > extends Literal.Properties[property] &
+                  ValueSyntax.Checked<
+                    Record<
+                      property,
+                      VariableSets.Scalar<NonNullable<tree[key]>>
+                    >
+                  >[property]
+              ? PathKey<key>
+              : never
+          : `${key}.${Paths<NonNullable<tree[key]>, property>}`
       }[Extract<keyof tree, number | string>]
 
+type PathKey<key extends number | string> =
+  | key
+  | `${key}`
+  | (key extends `${infer numericKey extends number}`
+      ? `${numericKey}` extends key
+        ? numericKey
+        : never
+      : never)
+
 /** Property domains accepted by each token group. */
-export type Properties<group extends Group> = group extends 'margin' | 'padding'
-  ? Exclude<
-      Extract<keyof Literal.Properties, `${group}${string}`>,
-      'marginTrim'
-    >
-  : group extends 'spacing'
-    ? Extract<
-        keyof Literal.Properties,
-        | `blockSize`
-        | `bottom`
-        | `columnGap`
-        | `flexBasis`
-        | `gap`
-        | `height`
-        | `inlineSize`
-        | `inset${string}`
-        | `left`
-        | Exclude<
-            Extract<keyof Literal.Properties, `margin${string}`>,
-            'marginTrim'
-          >
-        | `maxBlockSize`
-        | `maxHeight`
-        | `maxInlineSize`
-        | `maxWidth`
-        | `minBlockSize`
-        | `minHeight`
-        | `minInlineSize`
-        | `minWidth`
-        | `padding${string}`
-        | `right`
-        | `rowGap`
-        | `scrollPadding${string}`
-        | `textDecorationThickness`
-        | `textIndent`
-        | `textUnderlineOffset`
-        | `top`
-        | `width`
+export type Properties<group extends Group> = `--${string}` | Property<group>
+
+type Property<group extends Group> = group extends 'number' | 'string'
+  ? never
+  : group extends 'margin' | 'padding'
+    ? Exclude<
+        Extract<keyof Literal.Properties, `${group}${string}`>,
+        'marginTrim'
       >
-    : group extends 'textColor'
-      ? 'color'
-      : group extends 'color'
-        ? {
-            [property in keyof typeof Literal.rules]: (typeof Literal.rules)[property] extends {
-              kind: 'color'
-            }
-              ? property
-              : never
-          }[keyof typeof Literal.rules]
-        : group extends 'borderColor'
-          ? Extract<keyof Literal.Properties, `border${string}Color`>
-          : group extends 'borderRadius'
-            ? Extract<keyof Literal.Properties, `border${string}Radius`>
-            : group
+    : group extends 'spacing'
+      ? Extract<
+          keyof Literal.Properties,
+          | `blockSize`
+          | `bottom`
+          | `columnGap`
+          | `flexBasis`
+          | `gap`
+          | `height`
+          | `inlineSize`
+          | `inset${string}`
+          | `left`
+          | Exclude<
+              Extract<keyof Literal.Properties, `margin${string}`>,
+              'marginTrim'
+            >
+          | `maxBlockSize`
+          | `maxHeight`
+          | `maxInlineSize`
+          | `maxWidth`
+          | `minBlockSize`
+          | `minHeight`
+          | `minInlineSize`
+          | `minWidth`
+          | `padding${string}`
+          | `right`
+          | `rowGap`
+          | `scrollPadding${string}`
+          | `textDecorationThickness`
+          | `textIndent`
+          | `textUnderlineOffset`
+          | `top`
+          | `width`
+        >
+      : group extends 'textColor'
+        ? 'color'
+        : group extends 'color'
+          ? {
+              [property in keyof typeof Literal.rules]: (typeof Literal.rules)[property] extends {
+                kind: 'color'
+              }
+                ? property
+                : never
+            }[keyof typeof Literal.rules]
+          : group extends 'borderColor'
+            ? Extract<keyof Literal.Properties, `border${string}Color`>
+            : group extends 'borderWidth'
+              ? Exclude<
+                  Extract<keyof Literal.Properties, `border${string}Width`>,
+                  'borderImageWidth'
+                >
+              : group extends 'borderRadius'
+                ? Extract<keyof Literal.Properties, `border${string}Radius`>
+                : group
 
 /** Immutable portable reference retaining its defining fallback. */
 export type Reference<group extends Group = Group> = {
@@ -333,11 +456,11 @@ export function resolve(value: unknown, options: resolve.Options): unknown {
     ?.value as Metadata | undefined
   if (!data) throw new Error('Expected a theme definition.')
 
-  // Specific groups precede shared colors regardless of authored group order.
-  for (const group of [
+  const groups = [
     'backgroundColor',
     'borderColor',
     'borderRadius',
+    'borderWidth',
     'margin',
     'padding',
     'spacing',
@@ -348,7 +471,49 @@ export function resolve(value: unknown, options: resolve.Options): unknown {
     'lineHeight',
     'textColor',
     'color',
-  ] as const) {
+  ] as const
+
+  if (data.contract.variableSet) {
+    for (const [path, entry] of Object.entries(data.values).sort(
+      ([left], [right]) =>
+        groups.indexOf(left.split('.')[0] as (typeof groups)[number]) -
+        groups.indexOf(right.split('.')[0] as (typeof groups)[number]),
+    )) {
+      const [category, ...parts] = path.split('.')
+      const mappings = data.contract.mappings
+      const mapped = mappings === false ? undefined : mappings?.[category!]
+      if (
+        mappings === false
+          ? path !== String(value)
+          : parts.join('.') !== String(value) ||
+            !(mapped
+              ? mapped.includes(options.property)
+              : accepts(category as Group, options.property))
+      )
+        continue
+      return create({
+        contract: data.contract,
+        group: (() => {
+          let leaf: unknown = Object.getOwnPropertyDescriptor(
+            options.theme,
+            'tokens',
+          )?.value
+          for (const key of path.split('.'))
+            leaf =
+              leaf && typeof leaf === 'object'
+                ? Object.getOwnPropertyDescriptor(leaf, key)?.value
+                : undefined
+          return is(leaf) ? leaf.group : (category as Group)
+        })(),
+        path,
+        value: entry,
+      })
+    }
+    return value
+  }
+
+  // Specific groups precede shared colors regardless of authored group order.
+  for (const group of groups) {
     if (!accepts(group, options.property)) continue
 
     const path = `${group}.${value}`
@@ -377,4 +542,12 @@ export declare namespace resolve {
 export type Value =
   | number
   | string
-  | { readonly dark: string; readonly light: string }
+  | Reference
+  | { readonly dark: Value; readonly light: Value }
+  | Conditions
+
+/** Ordered conditional values with an unconditional fallback. */
+export type Conditions = {
+  readonly default: Value
+  readonly [query: `@media ${string}`]: Value
+}