zyzz 0.0.2 → 0.0.5

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
+}

package/src/internal/Typography.ts

@@ -0,0 +1,106 @@
+/** Describes nested typography sets and their property-aware token paths. @module */
+import type * as Literal from './Literal.js'
+import * as Token from './Token.js'
+
+/** Responsive query blocks accepted within a typography set. */
+export type Condition = `@media ${string}` | `@container ${string}`
+
+/** Recognizes responsive blocks without accepting selectors or unrelated at-rules. */
+export function condition(key: string): key is Condition {
+  return /^@(media|container)\s+\S/.test(key)
+}
+
+/** Expands one named set into portable field references and ordered query blocks. */
+export function entries(
+  theme: object | undefined,
+  name: unknown,
+  explicit: ReadonlySet<string> = new Set(),
+  important = false,
+): readonly (readonly [string, unknown])[] {
+  if (
+    !theme ||
+    typeof name !== 'string' ||
+    name.split('.').some((part) => part.startsWith('@'))
+  )
+    return []
+  let tree: unknown = Object.getOwnPropertyDescriptor(theme, 'tokens')?.value
+  for (const part of ['typography', ...name.split('.')]) {
+    if (!tree || typeof tree !== 'object') return []
+    tree = Object.getOwnPropertyDescriptor(tree, part)?.value
+  }
+  function expand(value: unknown): readonly (readonly [string, unknown])[] {
+    if (!value || typeof value !== 'object') return []
+    return Object.entries(value).flatMap(
+      ([key, child]): (readonly [string, unknown])[] => {
+        if (
+          properties.includes(key as Property) &&
+          Token.is(child) &&
+          !explicit.has(key)
+        )
+          return [
+            [key, important ? Token.compose([child, ' !important']) : child],
+          ]
+        if (condition(key)) {
+          const nested = expand(child)
+          return nested.length ? [[key, Object.fromEntries(nested)]] : []
+        }
+        return []
+      },
+    )
+  }
+  return expand(tree)
+}
+
+/** Lists expanded fields and queries in source-map traversal order. */
+export function keys(
+  theme: object | undefined,
+  name: unknown,
+  explicit: ReadonlySet<string>,
+): readonly string[] {
+  function collect(values: readonly (readonly [string, unknown])[]): string[] {
+    return values.flatMap(([key, value]) =>
+      condition(key)
+        ? [key, ...collect(Object.entries(value as object))]
+        : [key],
+    )
+  }
+  return collect(entries(theme, name, explicit))
+}
+
+/** Names of sets containing at least one typography declaration. */
+export type Names<tokens> = tokens extends { typography: infer tree }
+  ? Paths<tree>
+  : never
+
+type Paths<tree> = string extends keyof tree
+  ? string
+  : {
+      [key in Exclude<
+        Extract<keyof tree, string | number>,
+        Property | Condition
+      >]:
+        | (Extract<keyof tree[key], Property | Condition> extends never
+            ? never
+            : `${key}`)
+        | `${key}.${Paths<tree[key]>}`
+    }[Exclude<Extract<keyof tree, string | number>, Property | Condition>]
+
+/** Scalar properties applied by a typography set. */
+export const properties = [
+  'fontFamily',
+  'fontSize',
+  'fontWeight',
+  'letterSpacing',
+  'lineHeight',
+] as const
+
+/** Property domain retained by each field in a set. */
+export type Property = (typeof properties)[number]
+
+/** A set may supply any of the five typography properties. */
+export type Set = Pick<Literal.Properties, Property> & {
+  readonly [key in Condition]?: Set
+}
+
+/** Nested names may contain sets and additional named variants. */
+export type Sets = { readonly [name: string]: Set | Sets }

package/src/internal/Value.ts

@@ -22,37 +22,56 @@ export type Atom<value> =
  */
 export type Accepted<style, properties> = {
   [property in keyof style]: property extends keyof properties
-    ? style[property] extends Binding.Reference
-      ? Binding.Reference<style[property]['type']> extends Exclude<
-          properties[property],
-          undefined
-        >
-        ? style[property]
+    ? style[property] extends { readonly [Token.scalar]: infer scalar }
+      ? property extends keyof Literal.Properties
+        ? [scalar] extends [Literal.Properties[property]]
+          ? style[property] & Checked<Record<property, scalar>>[property]
+          : never
         : never
-      : FunctionValue.Is<style[property]> extends true
-        ? FunctionValue.Accepted<
-            style[property],
-            Exclude<properties[property], undefined>,
-            property
-          >
-        : Exclude<style[property], undefined> extends Exclude<
-              properties[property],
-              undefined
-            >
-          ? Exclude<style[property], undefined>
-          : property extends keyof Literal.Properties
-            ? style[property] extends string | readonly (number | string)[]
-              ? Fold<style[property]> extends Input<
-                  | Lowercase<Extract<Literal.Properties[property], string>>
-                  | Extract<Literal.Properties[property], number>
+      : References<style[property], Exclude<properties[property], undefined>> &
+          (style[property] extends Binding.Reference
+            ? Binding.Reference<style[property]['type']> extends Exclude<
+                properties[property],
+                undefined
+              >
+              ? style[property]
+              : never
+            : FunctionValue.Is<style[property]> extends true
+              ? FunctionValue.Accepted<
+                  style[property],
+                  Exclude<properties[property], undefined>,
+                  property
                 >
-                ? style[property]
-                : Exclude<properties[property], undefined>
-              : Exclude<properties[property], undefined>
-            : Exclude<properties[property], undefined>
+              : Exclude<style[property], undefined> extends Exclude<
+                    properties[property],
+                    undefined
+                  >
+                ? Exclude<style[property], undefined>
+                : property extends keyof Literal.Properties
+                  ? style[property] extends
+                      | string
+                      | readonly (number | string)[]
+                    ? Fold<style[property]> extends Input<
+                        | Lowercase<
+                            Extract<Literal.Properties[property], string>
+                          >
+                        | Extract<Literal.Properties[property], number>
+                      >
+                      ? style[property]
+                      : Exclude<properties[property], undefined>
+                    : Exclude<properties[property], undefined>
+                  : Exclude<properties[property], undefined>)
     : never
 }
 
+type References<value, allowed> = value extends Token.Reference
+  ? value extends Extract<allowed, Token.Reference>
+    ? unknown
+    : never
+  : value extends readonly unknown[]
+    ? { [key in keyof value]: References<value[key], allowed> }
+    : unknown
+
 type Fold<value> = value extends string
   ? Lexical.Fold<Canonical<Spaces<Normalized<Lexical.Normalized<value>>>>>
   : value extends readonly unknown[]