zyzz 0.0.2 → 0.0.5

package/src/internal/Shorthands.ts

@@ -34,6 +34,7 @@ export function read(value: unknown): Map {
               'style',
               'theme',
               'themes',
+              'typography',
               'script',
               'variants',
               '__proto__',
@@ -98,6 +99,7 @@ export type Validated<mappings extends Map> = {
         | 'style'
         | 'theme'
         | 'themes'
+        | 'typography'
         | 'script'
         | 'variants'
         | '__proto__'

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

@@ -2,16 +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 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 =
@@ -51,7 +53,7 @@ export type StyleFactory<tokens extends Tokens> = {
 }
 
 /**
- * Defines scalar tokens without metadata, defaults, or environment access.
+ * Defines scalar tokens and typography sets without defaults or environment access.
  * Colors currently use the supported literal color grammar; spacing and radius
  * values use nonnegative literal lengths or zero. Nested palettes are supported.
  * @throws {InvalidError} If groups, paths, values, or data records are invalid.
@@ -95,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>>
 }
 
 /**
@@ -127,6 +129,8 @@ export function extend<
     data.contract,
     data.values,
     data.queries,
+    undefined,
+    data.paths,
   ) as unknown as Definition<tokens, boundStyle, boundVariants>
 }
 
@@ -166,7 +170,16 @@ type OverrideTree<tree, group> = tree extends string | number
   ? Scalar<group>
   : tree extends { readonly dark: string; readonly light: string }
     ? Color
-    : { readonly [key in keyof tree]?: OverrideTree<tree[key], group> }
+    : {
+        readonly [key in keyof tree]?: OverrideTree<
+          tree[key],
+          group extends 'typography'
+            ? key extends Typography.Property
+              ? key
+              : group
+            : group
+        >
+      }
 
 /** Nested palette or scale data. */
 export type Palette<leaf> = { readonly [key: string]: leaf | Palette<leaf> }
@@ -177,22 +190,38 @@ export type Reference<group extends Token.Group = Token.Group> =
 
 /** The inferred tree replaces scalar values and scheme pairs with references. */
 export type References<tokens> = {
-  readonly [group in keyof tokens as group extends Token.Group
+  readonly [group in keyof tokens as group extends Token.Group | 'typography'
     ? group
-    : never]: ReferenceTree<tokens[group], Extract<group, Token.Group>>
+    : never]: ReferenceTree<
+    tokens[group],
+    Extract<group, Token.Group | 'typography'>
+  >
 }
 
-type ReferenceTree<tree, group extends Token.Group> = tree extends
+type ReferenceTree<
+  tree,
+  group extends Token.Group | 'typography',
+> = tree extends
   | string
   | number
   | { readonly dark: string; readonly light: string }
-  ? Reference<group>
-  : { readonly [key in keyof tree]: ReferenceTree<tree[key], group> }
+  ? Reference<Extract<group, Token.Group>>
+  : {
+      readonly [key in keyof tree]: ReferenceTree<
+        tree[key],
+        group extends 'typography'
+          ? key extends Typography.Property
+            ? key
+            : group
+          : group
+      >
+    }
 
 /** Supported scalar groups; composite presets and query metadata follow separately. */
 type Scalar<group> = group extends
   | 'spacing'
   | 'borderRadius'
+  | 'borderWidth'
   | 'margin'
   | 'padding'
   ? Literal.Length
@@ -217,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. */
@@ -253,6 +286,8 @@ export type Tokens = {
   readonly spacing?: Palette<Literal.Length> | undefined
   /** Colors available to text declarations. */
   readonly textColor?: Palette<Color> | undefined
+  /** Named sets of font family, size, weight, letter spacing, and line height. */
+  readonly typography?: Typography.Sets | undefined
 }
 
 function build(
@@ -261,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),
@@ -279,12 +315,26 @@ 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>()
 
-  function visit(value: unknown, group: Token.Group, path: readonly string[]) {
+  function visit(
+    value: unknown,
+    group: Token.Group | 'typography',
+    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(
+        path,
+        'Expected a typography set or a nested set group.',
+      )
     const entries = scalar ? undefined : record(value, path)
     const pair =
       ['color', 'backgroundColor', 'borderColor', 'textColor'].includes(
@@ -338,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(
@@ -347,7 +415,18 @@ function build(
       )
         throw new InvalidError(next, 'Extensions cannot add token paths.')
 
-      visit(child, group, next)
+      const property =
+        group === 'typography' &&
+        Typography.properties.includes(name as Typography.Property)
+          ? (name as Typography.Property)
+          : undefined
+      if (property && typeof child !== 'string' && typeof child !== 'number')
+        throw new InvalidError(
+          next,
+          'Typography properties require scalar values.',
+        )
+
+      visit(child, property ?? group, next)
     }
 
     active.delete(value as object)
@@ -435,6 +514,7 @@ function build(
         'backgroundColor',
         'borderColor',
         'borderRadius',
+        'borderWidth',
         'color',
         'margin',
         'padding',
@@ -445,6 +525,7 @@ function build(
         'letterSpacing',
         'lineHeight',
         'textColor',
+        'typography',
       ].includes(group)
     )
       throw new InvalidError([group], 'Unsupported token group.')
@@ -459,8 +540,26 @@ function build(
     if (!entries.length && !base)
       throw new InvalidError([group], 'Token palettes cannot be empty.')
 
-    for (const [name, value] of entries)
-      visit(value, group as Token.Group, [group, name])
+    for (const [name, value] of entries) {
+      if (
+        group === 'typography' &&
+        (Typography.properties.includes(name as Typography.Property) ||
+          name.startsWith('@'))
+      )
+        throw new InvalidError(
+          [group, name],
+          'Typography properties require a named set.',
+        )
+      visit(value, group as Token.Group | 'typography', [group, name])
+    }
+  }
+
+  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 }
@@ -468,7 +567,7 @@ function build(
   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))
@@ -476,7 +575,9 @@ function build(
 
     tree[parts.at(-1)!] = Token.create({
       contract,
-      group: parts[0] as Token.Group,
+      group: (parts[0] === 'typography'
+        ? parts.at(-1)
+        : parts[0]) as Token.Group,
       path,
       value,
     })
@@ -518,6 +619,7 @@ function build(
       {
         value: Object.freeze({
           contract,
+          ...(Object.keys(paths).length ? { paths: Object.freeze(paths) } : {}),
           values: Object.freeze(values),
           ...(hasQueries
             ? {
@@ -568,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)
     )
@@ -634,7 +737,11 @@ type ValidPalette<palette, group> = palette extends undefined
   : {
       [key in keyof palette]: key extends `${string}!${string}`
         ? never
-        : ValidTree<palette[key], group>
+        : group extends 'typography'
+          ? key extends Typography.Property | `@${string}`
+            ? never
+            : ValidTree<palette[key], group>
+          : ValidTree<palette[key], group>
     }
 
 type WeightDigits<
@@ -671,27 +778,29 @@ type Weight<value> = value extends number
   : value
 
 type ValidTree<tree, group> = tree extends string | number
-  ? tree extends Scalar<group>
-    ? group extends 'breakpoints' | 'containers'
-      ? tree extends `-${string}`
-        ? never
-        : Literal.Checked<tree>
-      : group extends keyof Literal.Properties
-        ? Literal.Checked<tree> &
-            Value.Checked<Record<group, tree>>[group] &
-            (group extends 'fontWeight' ? Weight<tree> : unknown) &
-            (tree extends string
-              ? Lowercase<tree> extends
-                  | 'inherit'
-                  | 'initial'
-                  | 'unset'
-                  | 'revert'
-                  | 'revert-layer'
-                ? never
-                : unknown
-              : unknown)
-        : Literal.Checked<tree>
-    : never
+  ? group extends 'typography'
+    ? never
+    : tree extends Scalar<group>
+      ? group extends 'breakpoints' | 'containers'
+        ? tree extends `-${string}`
+          ? never
+          : Literal.Checked<tree>
+        : group extends keyof Literal.Properties
+          ? Literal.Checked<tree> &
+              Value.Checked<Record<group, tree>>[group] &
+              (group extends 'fontWeight' ? Weight<tree> : unknown) &
+              (tree extends string
+                ? Lowercase<tree> extends
+                    | 'inherit'
+                    | 'initial'
+                    | 'unset'
+                    | 'revert'
+                    | 'revert-layer'
+                  ? never
+                  : unknown
+                : unknown)
+          : Literal.Checked<tree>
+      : never
   : Extract<
         keyof tree,
         group extends 'color' | 'backgroundColor' | 'borderColor' | 'textColor'
@@ -701,7 +810,24 @@ type ValidTree<tree, group> = tree extends string | number
     ? {
         [key in keyof tree]: key extends `${string}!${string}`
           ? never
-          : ValidTree<tree[key], group>
+          : group extends 'typography'
+            ? key extends `@${string}`
+              ? key extends Typography.Condition
+                ? ValidTree<tree[key], group> &
+                    Record<
+                      Exclude<
+                        keyof tree[key],
+                        Typography.Property | Typography.Condition
+                      >,
+                      never
+                    >
+                : never
+              : 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'
       ? {