zyzz 0.0.0 → 0.0.3

package/src/internal/Numeric.ts

@@ -0,0 +1,77 @@
+/** Refines CSS numeric token spellings entirely within TypeScript. @module */
+type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
+
+type Digits<
+  text extends string,
+  prefix extends string = '',
+> = text extends `${infer first}${infer rest}`
+  ? first extends Digit
+    ? Digits<rest, `${prefix}${first}`>
+    : readonly [prefix, text]
+  : readonly [prefix, '']
+
+type Exponent<
+  text extends string,
+  integer extends boolean,
+> = text extends `${'e' | 'E'}${infer rest}`
+  ? Digits<Sign<rest>> extends readonly [
+      infer digits extends string,
+      infer unit extends string,
+    ]
+    ? digits extends ''
+      ? readonly [text, integer]
+      : readonly [unit, false]
+    : never
+  : readonly [text, integer]
+
+type Sign<text extends string> = text extends `${'+' | '-'}${infer rest}`
+  ? rest
+  : text
+
+type Zeros<text extends string> = text extends ''
+  ? true
+  : text extends `${'0' | '.'}${infer rest}`
+    ? Zeros<rest>
+    : false
+
+/** Checks a complete CSS number or integer token without allowing JavaScript radix syntax. */
+export type Checked<
+  value extends string | number,
+  integer extends boolean = false,
+> = `${number}` extends `${value}`
+  ? value
+  : [Parse<`${value}`>] extends [never]
+    ? never
+    : Parse<`${value}`> extends readonly ['', infer whole extends boolean]
+      ? integer extends true
+        ? whole extends true
+          ? value
+          : never
+        : value
+      : never
+
+/** Returns the unconsumed unit and whether the number has integer token syntax. */
+export type Parse<text extends string> =
+  Digits<Sign<text>> extends readonly [
+    infer digits extends string,
+    infer rest extends string,
+  ]
+    ? rest extends `.${infer fraction}`
+      ? Digits<fraction> extends readonly [
+          infer decimal extends string,
+          infer unit extends string,
+        ]
+        ? decimal extends ''
+          ? never
+          : Exponent<unit, false>
+        : never
+      : digits extends ''
+        ? never
+        : Exponent<rest, true>
+    : never
+
+/** Identifies signed zero mantissas for nonnegative and positive range constraints. */
+export type Zero<value extends string | number> =
+  Sign<`${value}`> extends `${infer mantissa}${'e' | 'E'}${string}`
+    ? Zeros<mantissa>
+    : Zeros<Sign<`${value}`>>

package/src/internal/Query.ts

@@ -0,0 +1,87 @@
+/** Carries compile-time query metadata separately from declaration variables. @module */
+import * as Literal from './Literal.js'
+
+/** Named thresholds and eligible container identities. */
+export type Metadata = {
+  readonly breakpoints: Readonly<Record<string, string>>
+  readonly containerNames: readonly string[]
+  readonly containers: Readonly<Record<string, string>>
+}
+
+/** Supported fixed nonnegative threshold lengths. */
+export type Length = Exclude<Literal.Length, `${number}%` | number | '0'>
+
+/** Checks threshold structure without converting relative CSS units. */
+export function threshold(value: unknown): value is string {
+  if (typeof value !== 'string') return false
+
+  const match = /^([+]?(?:\d*\.\d+|\d+)(?:[eE][+-]?\d+)?)([a-z]+)$/i.exec(value)
+
+  return (
+    !!match &&
+    Number.isFinite(Number(match[1])) &&
+    Literal.lengthUnits.some(
+      (unit) => unit.toLowerCase() === match[2]!.toLowerCase(),
+    ) &&
+    match[2] !== '%'
+  )
+}
+
+/** Resolves exact named width comparisons and ranges; raw conditions pass through. */
+export function resolve(key: string, metadata: Metadata): string {
+  const match = /^@(media|container)[ \t\n\r\f]+([\s\S]+)$/.exec(
+    key.replace(/\/\*[^]*?\*\//g, ' '),
+  )
+  if (!match) return key
+
+  const kind = match[1]!
+  const text = match[2]!.trim()
+  if (
+    text.includes('(') ||
+    (kind === 'media' &&
+      /^(?:(?:only|not)\s+)?(?:all|print|screen)(?:\s|,|$)/i.test(text))
+  )
+    return key
+  const pieces = text.split(/[ \t\n\r\f]+/)
+
+  const name =
+    kind === 'container' && pieces.length === 2 ? pieces.shift() : undefined
+  if (name && !metadata.containerNames.includes(name))
+    throw new Error('Unknown container name.')
+
+  if (pieces.length !== 1) throw new Error('Malformed query alias.')
+
+  const alias = pieces[0]!
+  const values = kind === 'media' ? metadata.breakpoints : metadata.containers
+
+  const read = (name: string) => {
+    const value = Object.hasOwn(values, name) ? values[name] : undefined
+    if (value === undefined) throw new Error('Unknown query threshold.')
+
+    return value
+  }
+
+  const condition = (() => {
+    if (alias.includes('..')) {
+      const range = alias.split('..')
+      if (range.length !== 2) throw new Error('Malformed query range.')
+
+      const lower = read(range[0]!)
+      const upper = read(range[1]!)
+      const unit = (value: string) =>
+        value
+          .replace(/^[+]?(?:\d*\.\d+|\d+)(?:[eE][+-]?\d+)?/, '')
+          .toLowerCase()
+      if (unit(lower) === unit(upper) && parseFloat(lower) >= parseFloat(upper))
+        throw new Error('Query range must increase.')
+
+      return `${lower} <= width < ${upper}`
+    }
+
+    if (alias.startsWith('<')) return `width < ${read(alias.slice(1))}`
+
+    return `width >= ${read(alias.startsWith('>=') ? alias.slice(2) : alias)}`
+  })()
+
+  return `@${kind} ${name ? `${name} ` : ''}(${condition})`
+}

package/src/internal/Recipe.ts

@@ -0,0 +1,17 @@
+/** Retains ordered finite recipe alternatives independently of an output target. @module */
+import type * as Style from '../Style.js'
+
+/** Static recipe data shared by source extraction and target compilers. */
+export type Definition<value = Style.Definition> = {
+  /** Ordered axes and their finite choice names. */
+  readonly axes: Readonly<Record<string, readonly string[]>>
+  /** Default choices, with null suppressing an axis. */
+  readonly defaults: Readonly<Record<string, string | null>>
+  /** Base, choices, and compounds in application order. */
+  readonly rules: readonly {
+    /** Required choices by axis. An empty list always matches. */
+    readonly matches: readonly (readonly [string, readonly string[]])[]
+    /** Target-independent declarations or their compiled value. */
+    readonly value: value
+  }[]
+}

package/src/internal/RuleReference.ts

@@ -0,0 +1,102 @@
+/** Distinguishes compiler-owned CSS identities from unrelated declaration domains. @module */
+declare const reference: unique symbol
+/** Supported named stylesheet identity domains. */
+export type Kind =
+  | 'colorProfile'
+  | 'counterStyle'
+  | 'cssFunction'
+  | 'customMedia'
+  | 'fontPaletteValues'
+  | 'positionTry'
+/** A fixed CSS name whose domain remains visible to authoring types. */
+export type Reference<kind extends Kind> = (kind extends 'counterStyle'
+  ? string
+  : `--${string}`) & {
+  readonly [reference]: kind
+}
+/** Rejects named references outside their property's CSS identity domain. */
+export type Check<value, property> = typeof reference extends keyof value
+  ? value[typeof reference] extends Domain<property>
+    ? unknown
+    : never
+  : value extends readonly unknown[]
+    ? { [index in keyof value]: Check<value[index], property> }
+    : unknown
+
+type Domain<property> = property extends `--${string}`
+  ? Kind
+  : property extends 'fallback' | 'listStyle' | 'listStyleType' | 'speakAs'
+    ? 'counterStyle'
+    : property extends 'fontPalette'
+      ? 'fontPaletteValues'
+      : property extends 'positionTry' | 'positionTryFallbacks'
+        ? 'positionTry'
+        : never
+/** Checks domain-sensitive descriptor members without widening literals. */
+export type Checked<value> = { [key in keyof value]: Check<value[key], key> }
+
+/** Checks the domain of a compiler-owned identity at untyped source boundaries. */
+export function accepts(kind: Kind, property: string): boolean {
+  if (kind === 'cssFunction') return true
+  if (kind === 'customMedia') return false
+  if (property.startsWith('--')) return true
+  if (kind === 'counterStyle')
+    return [
+      'fallback',
+      'listStyle',
+      'listStyleType',
+      'speakAs',
+      'system',
+    ].includes(property)
+  if (kind === 'fontPaletteValues') return property === 'fontPalette'
+  if (kind === 'positionTry')
+    return ['positionTry', 'positionTryFallbacks'].includes(property)
+  return false
+}
+
+/** Permits profile identities only as the color-space argument of color(). */
+export function acceptsExpression(
+  kind: Kind,
+  property: string,
+  prefix: string,
+): boolean {
+  if (kind === 'colorProfile') {
+    const text = prefix.replace(/\/\*[\s\S]*?\*\//g, ' ')
+    const groups: { name: string; start: number }[] = []
+    let quote = ''
+    for (let index = 0; index < text.length; index++) {
+      const char = text[index]!
+      if (char === '\\') {
+        index++
+        continue
+      }
+      if (quote) {
+        if (char === quote) quote = ''
+        continue
+      }
+      if (char === '"' || char === "'") {
+        quote = char
+        continue
+      }
+      if (char === '(')
+        groups.push({
+          name:
+            text
+              .slice(0, index)
+              .match(/[\w-]+$/)?.[0]
+              ?.toLowerCase() ?? '',
+          start: index + 1,
+        })
+      else if (char === ')') groups.pop()
+    }
+
+    const group = groups.at(-1)
+    if (quote || group?.name !== 'color') return false
+    const body = text.slice(group.start)
+    if (!body.trim()) return true
+
+    return /^\s*from\s+(?:#[\da-f]+|[-\w]+(?:\([\s\S]*\))?)\s+$/i.test(body)
+  }
+
+  return accepts(kind, property)
+}

package/src/internal/Scheme.ts

@@ -0,0 +1,20 @@
+/** Names the stylesheet classes that select a color scheme beside a theme scope. @module */
+
+/** Supported scheme selections. */
+export type Name = 'dark' | 'light' | 'light dark'
+
+/**
+ * Compiled class per scheme. Carrying `color-scheme` in stylesheet rules lets
+ * Lightning CSS initialize its lowered `light-dark()` helpers when a downstream
+ * bundler targets browsers without native support; inline styles cannot.
+ */
+export const classes: Readonly<Record<Name, string>> = Object.freeze({
+  dark: 'z_scheme-dark',
+  light: 'z_scheme-light',
+  'light dark': 'z_scheme-light-dark',
+})
+
+/** Selection rules emitted once beside each stylesheet's theme scopes. */
+export const css = (Object.keys(classes) as Name[])
+  .map((scheme) => `.${classes[scheme]}{color-scheme:${scheme};}`)
+  .join('\n')

package/src/internal/Shorthands.ts

@@ -0,0 +1,122 @@
+/** Validates ordered configuration property aliases without interpreting CSS values. @module */
+import * as Literal from './Literal.js'
+
+/** Explicit aliases, each expanding in its declared target order. */
+export type Map = Readonly<Record<string, readonly [Property, ...Property[]]>>
+/** Standard properties accepted as alias targets. */
+export type Property = Exclude<keyof Literal.Properties, `--${string}`>
+
+/** Copies validated configuration data; throws for invalid aliases or targets. */
+export function read(value: unknown): Map {
+  if (
+    !value ||
+    typeof value !== 'object' ||
+    Array.isArray(value) ||
+    (Object.getPrototypeOf(value) !== null &&
+      Object.getPrototypeOf(value) !== Object.prototype)
+  )
+    throw new Error('shorthands must be a property mapping record.')
+
+  const entries = Object.entries(Object.getOwnPropertyDescriptors(value))
+
+  return Object.freeze(
+    Object.setPrototypeOf(
+      Object.fromEntries(
+        entries.map(([name, descriptor]) => {
+          if (
+            !name ||
+            name.startsWith(':') ||
+            name.startsWith('@') ||
+            name.startsWith('--') ||
+            name.includes('&') ||
+            Object.hasOwn(Literal.rules, name) ||
+            [
+              'style',
+              'theme',
+              'themes',
+              'typography',
+              'script',
+              'variants',
+              '__proto__',
+            ].includes(name)
+          )
+            throw new Error(`Invalid shorthand name: ${name}`)
+
+          const targets: unknown = descriptor.value
+          if (
+            !('value' in descriptor) ||
+            !Array.isArray(targets) ||
+            !targets.length
+          )
+            throw new Error(
+              `Shorthand ${name} requires a nonempty property tuple.`,
+            )
+
+          const result: Property[] = []
+
+          for (let index = 0; index < targets.length; index++) {
+            const target: unknown = Object.getOwnPropertyDescriptor(
+              targets,
+              String(index),
+            )?.value
+            if (
+              typeof target !== 'string' ||
+              !Object.hasOwn(Literal.rules, target) ||
+              result.includes(target as Property)
+            )
+              throw new Error(
+                `Shorthand ${name} requires unique standard properties.`,
+              )
+
+            result.push(target as Property)
+          }
+
+          return [name, Object.freeze(result)]
+        }),
+      ),
+      null,
+    ),
+  ) as Map
+}
+
+/** Canonicalizes alias names while preserving each ordered target tuple. */
+export function signature(value: unknown): string {
+  return JSON.stringify(
+    Object.entries(read(value === undefined ? {} : value)).sort(([a], [b]) =>
+      a < b ? -1 : a > b ? 1 : 0,
+    ),
+  )
+}
+
+/** Rejects duplicate targets and names reserved by the authoring surface. */
+export type Validated<mappings extends Map> = {
+  [key in keyof mappings]: key extends string
+    ? key extends
+        | keyof Literal.Properties
+        | `:${string}`
+        | `@${string}`
+        | `${string}&${string}`
+        | 'style'
+        | 'theme'
+        | 'themes'
+        | 'typography'
+        | 'script'
+        | 'variants'
+        | '__proto__'
+        | ''
+      ? never
+      : Unique<mappings[key]>
+    : never
+}
+
+type Unique<
+  targets extends readonly Property[],
+  seen extends Property = never,
+> = targets extends readonly [
+  infer target extends Property,
+  ...infer rest extends readonly Property[],
+]
+  ? target extends seen
+    ? never
+    : Unique<rest, seen | target>
+  : unknown

package/src/internal/Targets.ts

@@ -0,0 +1,162 @@
+/** Copies static target data without retaining or freezing caller-owned objects. @module */
+import type * as Native from './NativeProperties.js'
+import type * as Style from '../Style.js'
+
+/** Type-only authoring data retained for destination component compatibility. */
+export declare const authored: unique symbol
+
+/** Per-style destination domains, computed only when a compiler consumes them. */
+export type Domains<input> = [input] extends [never]
+  ? unknown
+  : {
+      [key in keyof input]: {
+        android: Overflow<input[key], 'android'>
+        ios: Overflow<input[key], 'ios'>
+        native: Overflow<input[key], undefined>
+      }
+    }
+
+/** Retains the selected overflow domain, which differs between Image and View. */
+export type Overflow<input, platform> = Merge<
+  Value<input>,
+  Merge<
+    Value<Branch<input, 'native'>>,
+    platform extends 'ios' | 'android'
+      ? Value<Branch<input, platform>>
+      : undefined
+  >
+>
+type Branch<input, key extends PropertyKey> = input extends {
+  readonly targets?: infer targets
+}
+  ? key extends keyof NonNullable<targets>
+    ? NonNullable<targets>[key]
+    : never
+  : never
+type Value<input> = [input] extends [never]
+  ? undefined
+  : 'overflow' extends keyof NonNullable<input>
+    ? NonNullable<input>['overflow']
+    : undefined
+type Merge<before, after> =
+  | Exclude<after, undefined>
+  | (undefined extends after ? before : never)
+
+/** Checks nested native literal keys without accepting host-owned values. */
+export type Checked<input, expected> = expected extends unknown
+  ? input extends expected
+    ? input extends readonly unknown[]
+      ? expected extends readonly (infer value)[]
+        ? readonly Checked<input[number], value>[]
+        : never
+      : input extends object
+        ? {
+            [key in keyof input]: key extends keyof expected
+              ? Checked<input[key], expected[key]>
+              : never
+          }
+        : input
+    : never
+  : never
+
+/** Checks only authored native properties against their destination domains. */
+export type Declarations<input> = input extends undefined
+  ? undefined
+  : input extends (...args: never[]) => unknown
+    ? never
+    : input extends object
+      ? {
+          [key in keyof input]: key extends keyof Native.Properties
+            ? Checked<input[key], Native.Properties[key]>
+            : never
+        }
+      : never
+
+/** Retained compiler data for native and platform-specific declarations. */
+export type NativeBranches = {
+  /** Android overrides applied after the common native branch. */
+  readonly android?: Native.Properties | undefined
+  /** iOS overrides applied after the common native branch. */
+  readonly ios?: Native.Properties | undefined
+  /** Declarations using native value semantics. */
+  readonly native?: Native.Properties | undefined
+}
+
+/** Copies only finite primitives, dense arrays, and plain enumerable data records. */
+export function copy(
+  value: unknown,
+  path: readonly string[] = [],
+  depth = 0,
+): unknown {
+  if (depth > 64)
+    throw new Error(`Target nesting exceeds 64 levels at ${path.join('.')}.`)
+  if (
+    value === undefined ||
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'boolean'
+  )
+    return value
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (!value || typeof value !== 'object')
+    throw new Error(`Expected static native data at ${path.join('.')}.`)
+  const array = Array.isArray(value)
+  const prototype = Object.getPrototypeOf(value)
+  if (!array && prototype !== null && prototype !== Object.prototype) {
+    const constructor = Object.getOwnPropertyDescriptor(
+      prototype,
+      'constructor',
+    )?.value
+    if (
+      Object.getPrototypeOf(prototype) !== null ||
+      typeof constructor !== 'function' ||
+      Function.prototype.toString.call(constructor) !==
+        Function.prototype.toString.call(Object)
+    )
+      throw new Error(
+        `Host-owned objects are not static target data at ${path.join('.')}.`,
+      )
+  }
+  const output: Record<string, unknown> = Object.create(null)
+  for (const key of Reflect.ownKeys(value)) {
+    if (array && key === 'length') continue
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)!
+    if (
+      typeof key !== 'string' ||
+      !descriptor.enumerable ||
+      !('value' in descriptor)
+    )
+      throw new Error(
+        `Target data must not contain accessors or symbols at ${path.join('.')}.`,
+      )
+    if (!array && descriptor.value === undefined) continue
+    output[key] = copy(descriptor.value, [...path, key], depth + 1)
+  }
+  if (!array) return Object.freeze(output)
+  if (
+    Object.keys(output).length !== value.length ||
+    Object.keys(output).some((key, index) => key !== String(index))
+  )
+    throw new Error(
+      `Target arrays must contain dense data entries at ${path.join('.')}.`,
+    )
+  return Object.freeze(Object.values(output))
+}
+
+/** Selects web overrides without passing native declarations to the CSS compiler. */
+export function web<name extends string>(
+  style: Style.NamedStyle<name>,
+): Style.NamedStyle<name> {
+  const rules = style.rules?.map((rule) => ({
+    ...rule,
+    style: web(rule.style),
+  }))
+  const { targets, ...body } = style
+  const shared = rules ? { ...body, rules } : body
+  if (!targets?.web) return shared
+  return {
+    ...shared,
+    declarations: [],
+    rules: [{ style: shared }, { style: web(targets.web) }],
+  }
+}