zyzz 0.0.0 → 0.0.2

package/src/compiler/internal/Descriptors.ts

@@ -0,0 +1,238 @@
+/** Validates descriptor grammars independently of the output parser's error recovery. @module */
+import * as Lightning from 'lightningcss'
+import * as Tree from 'css-tree'
+
+/** Checks one authored descriptor before it can introduce another CSS declaration. */
+export function check(options: check.Options): void {
+  const name = options.name.replace(
+    /[A-Z]/g,
+    (letter) => `-${letter.toLowerCase()}`,
+  )
+  const result = Tree.lexer.matchAtruleDescriptor(
+    options.rule,
+    name,
+    options.value,
+  )
+  if (result.error)
+    throw new Error(`Invalid @${options.rule} ${name}: ${result.error.message}`)
+  if (
+    options.rule === 'page' &&
+    ['bleed', 'size'].includes(name) &&
+    /(?:calc|min|max|clamp)\(/i.test(options.value)
+  )
+    Lightning.transform({
+      filename: 'page.css',
+      code: new TextEncoder().encode(
+        `@property --page-length {syntax: "<length>${name === 'size' ? '+' : ''}"; inherits: false; initial-value: ${options.value};}`,
+      ),
+    })
+}
+
+/** Checks a native custom-media query before statement serialization. */
+export function media(query: string): void {
+  const result = Tree.lexer.matchAtrulePrelude('media', query)
+  if (result.error)
+    throw new Error(`Invalid custom-media query: ${result.error.message}`)
+}
+
+/** Authored descriptor grammar input. */
+export declare namespace check {
+  type Options = {
+    readonly name: string
+    readonly rule: string
+    readonly value: string
+  }
+}
+
+/** Reviews every declaration in standard named descriptor rules. */
+export function validate(source: string): void {
+  const sheet = Tree.parse(source)
+  Tree.walk(sheet, {
+    visit: 'Atrule',
+    enter(rule) {
+      const name = rule.name.toLowerCase()
+      if (name === 'document') {
+        if (!rule.block || !rule.prelude)
+          throw new Error(
+            'Document rules require matching functions and a block.',
+          )
+        const result = Tree.lexer.matchAtrulePrelude(
+          'document',
+          Tree.generate(rule.prelude),
+        )
+        if (result.error)
+          throw new Error(
+            `Invalid document matching functions: ${result.error.message}`,
+          )
+        return
+      }
+      if (name === 'custom-media') {
+        if (rule.block || !rule.prelude)
+          throw new Error(
+            'Custom-media requires a name and query without a block.',
+          )
+        const prelude = Tree.generate(rule.prelude)
+        let first: { type: number; start: number; end: number } | undefined
+        Tree.tokenize(prelude, (type, start, end) => {
+          if (
+            !first &&
+            type !== Tree.tokenTypes.WhiteSpace &&
+            type !== Tree.tokenTypes.Comment
+          )
+            first = { type, start, end }
+        })
+        const name = first
+          ? Tree.ident.decode(prelude.slice(first.start, first.end))
+          : ''
+        if (
+          first?.type !== Tree.tokenTypes.Ident ||
+          !name.startsWith('--') ||
+          name.length <= 2
+        )
+          throw new Error('Custom-media requires a dashed name and query.')
+        media(prelude.slice(first.end).trim())
+        return
+      }
+      if (name === 'page') {
+        const prelude = rule.prelude ? Tree.generate(rule.prelude) : ''
+        const result = Tree.lexer.matchAtrulePrelude('page', prelude)
+        if (result.error)
+          throw new Error(`Invalid page selector: ${result.error.message}`)
+        if (!rule.block) throw new Error('Page rules require a block.')
+        rule.block.children.forEach((declaration) => {
+          if (declaration.type !== 'Declaration') return
+          if (
+            ['bleed', 'marks', 'page-orientation', 'size'].includes(
+              declaration.property,
+            )
+          )
+            check({
+              rule: 'page',
+              name: declaration.property,
+              value: Tree.generate(declaration.value),
+            })
+        })
+        return
+      }
+      if (!['counter-style', 'font-face', 'font-palette-values'].includes(name))
+        return
+      if (!rule.block) throw new Error(`Expected @${name} descriptors.`)
+      const prelude = rule.prelude ? Tree.generate(rule.prelude) : ''
+      const match = Tree.lexer.matchAtrulePrelude(name, prelude)
+      if (match.error)
+        throw new Error(`Invalid @${name} prelude: ${match.error.message}`)
+      const declarations = new Map<string, Tree.Value>()
+      rule.block.children.forEach((declaration) => {
+        if (declaration.type !== 'Declaration' || declaration.important)
+          throw new Error(`Expected non-important @${name} descriptors.`)
+        const value = Tree.generate(declaration.value)
+        const parsed = Tree.parse(value, { context: 'value' }) as Tree.Value
+        const result = Tree.lexer.matchAtruleDescriptor(
+          name,
+          declaration.property,
+          parsed,
+        )
+        if (result.error)
+          throw new Error(
+            `Invalid @${name} ${declaration.property}: ${result.error.message}`,
+          )
+        declarations.set(declaration.property.toLowerCase(), parsed)
+        if (name === 'font-face') {
+          const key = declaration.property.toLowerCase()
+          parsed.children.forEach((node) => {
+            if (
+              node.type === 'Percentage' &&
+              [
+                'size-adjust',
+                'ascent-override',
+                'descent-override',
+                'line-gap-override',
+                'font-stretch',
+              ].includes(key) &&
+              Number(node.value) < 0
+            )
+              throw new Error(`@font-face ${key} cannot be negative.`)
+            if (
+              key === 'font-weight' &&
+              node.type === 'Number' &&
+              (Number(node.value) < 1 || Number(node.value) > 1000)
+            )
+              throw new Error('Font weight must be between 1 and 1000.')
+          })
+        }
+
+        if (
+          name === 'font-palette-values' &&
+          declaration.property === 'override-colors'
+        )
+          Tree.walk(parsed, (node) => {
+            if (
+              result
+                .getTrace(node)
+                ?.some(
+                  (syntax) =>
+                    'type' in syntax &&
+                    'name' in syntax &&
+                    typeof syntax.name === 'string' &&
+                    ((syntax.type === 'Keyword' &&
+                      syntax.name.toLowerCase() === 'currentcolor') ||
+                      (syntax.type === 'Type' &&
+                        [
+                          'system-color',
+                          'light-dark()',
+                          'light-dark-color',
+                          'contrast-color()',
+                          'device-cmyk()',
+                        ].includes(syntax.name))),
+                )
+            )
+              throw new Error('Palette overrides require absolute colors.')
+          })
+      })
+      if (name === 'counter-style') {
+        const systemNode = declarations.get('system')?.children.first
+        const system =
+          systemNode?.type === 'Identifier'
+            ? Tree.ident.decode(systemNode.name).toLowerCase()
+            : 'symbolic'
+        const symbols = declarations.get('symbols')?.children.size ?? 0
+        if (system === 'numeric' || system === 'alphabetic') {
+          if (symbols < 2)
+            throw new Error(
+              'Numeric and alphabetic counters require at least two symbols.',
+            )
+        } else if (system === 'additive') {
+          if (!declarations.has('additive-symbols'))
+            throw new Error('Additive counters require additive symbols.')
+        } else if (system !== 'extends' && !symbols)
+          throw new Error('Counter systems require at least one symbol.')
+        const additive = declarations.get('additive-symbols')
+        if (additive) {
+          let previous = Infinity
+          additive.children.forEach((node) => {
+            if (node.type !== 'Number') return
+            const weight = Number(node.value)
+            if (weight >= previous)
+              throw new Error('Additive symbol weights must strictly descend.')
+            previous = weight
+          })
+        }
+        const range = declarations.get('range')
+        if (range) {
+          const bounds: number[] = []
+          range.children.forEach((node) => {
+            if (node.type === 'Number') bounds.push(Number(node.value))
+            else if (
+              node.type === 'Identifier' &&
+              Tree.ident.decode(node.name).toLowerCase() === 'infinite'
+            )
+              bounds.push(bounds.length % 2 ? Infinity : -Infinity)
+          })
+          for (let index = 0; index < bounds.length; index += 2)
+            if (bounds[index]! > bounds[index + 1]!)
+              throw new Error('Counter ranges must have increasing bounds.')
+        }
+      }
+    },
+  })
+}

package/src/compiler/internal/Dynamic.ts

@@ -0,0 +1,266 @@
+/** Extracts typed callback slots and static object bodies without invoking callbacks. @module */
+import type * as Ast from '@oxc-project/types'
+import type * as Binding from '../../internal/Binding.js'
+import * as Expression from './Expression.js'
+import * as Literal from '../../internal/Literal.js'
+import * as Themes from './Themes.js'
+
+/** Fixed callback input slots retained in generated callables. */
+export type Slots = Readonly<Record<string, Binding.Reference>>
+
+/** Reads a finite explicitly typed parameter and a concise static object body. */
+export function read(
+  node: Ast.Node,
+  identity: string,
+  resolveType: (node: Ast.Node) => Ast.Node = (node) => node,
+) {
+  node = Expression.unwrap(node)
+
+  if (node.type !== 'ArrowFunctionExpression') return undefined
+
+  if (node.async || node.params.length !== 1)
+    throw new Themes.InvalidError(
+      'Dynamic styles require one typed values parameter.',
+      node,
+    )
+
+  const parameter = node.params[0]!
+  if (parameter.type !== 'Identifier' || !parameter.typeAnnotation)
+    throw new Themes.InvalidError(
+      'Dynamic styles require an explicit finite object type on the values parameter.',
+      parameter,
+    )
+
+  const fields = resolveType(parameter.typeAnnotation.typeAnnotation)
+  if (fields.type !== 'TSTypeLiteral')
+    throw new Themes.InvalidError(
+      'Dynamic styles require a finite object type.',
+      parameter,
+    )
+
+  const parameterName = parameter.name
+  const slots: Record<string, Binding.Reference> = Object.create(null)
+  const numeric = new Map<Binding.Reference, readonly number[]>()
+
+  for (const member of fields.members) {
+    const key =
+      member.type === 'TSPropertySignature'
+        ? member.key.type === 'Identifier'
+          ? member.key.name
+          : member.key.type === 'Literal' &&
+              typeof member.key.value === 'string'
+            ? member.key.value
+            : undefined
+        : undefined
+    if (
+      member.type !== 'TSPropertySignature' ||
+      member.computed ||
+      member.optional ||
+      !member.typeAnnotation ||
+      key === undefined ||
+      [
+        'class',
+        'className',
+        'key',
+        'ref',
+        'style',
+        'variables',
+        '__proto__',
+      ].includes(key) ||
+      Object.hasOwn(slots, key)
+    )
+      throw new Themes.InvalidError(
+        'Dynamic values require unique required scalar fields without styling override keys.',
+        member,
+      )
+
+    const type = resolveType(member.typeAnnotation.typeAnnotation)
+    const kind = scalar(type)
+    if (!kind)
+      throw new Themes.InvalidError(
+        'Dynamic values require explicit string or number scalar types.',
+        member,
+      )
+
+    const slot = (slots[key] = Object.freeze({
+      name: `--z-d${identity}-${Array.from(key)
+        .map((character) => character.codePointAt(0)!.toString(16))
+        .join('-')}`,
+      type: kind === 'number' ? 'number' : 'length',
+      ...(kind === 'zero-string' ? { zero: true } : {}),
+      variable: true,
+    }))
+
+    const values = numbers(type)
+
+    if (values) numeric.set(slot, values)
+  }
+
+  const body = Expression.unwrap(node.body)
+  if (body.type !== 'ObjectExpression')
+    throw new Themes.InvalidError(
+      'Dynamic styles require a concise static object body.',
+      node.body,
+    )
+
+  function resolve(node: Ast.Node): Binding.Reference | undefined {
+    node = Expression.unwrap(node)
+
+    if (
+      node.type !== 'MemberExpression' ||
+      node.object.type !== 'Identifier' ||
+      node.object.name !== parameterName
+    )
+      return undefined
+
+    const key = (() => {
+      if (node.property.type === 'Identifier' && !node.computed)
+        return node.property.name
+
+      if (
+        node.property.type === 'Literal' &&
+        node.computed &&
+        typeof node.property.value === 'string'
+      )
+        return node.property.value
+
+      return undefined
+    })()
+
+    const slot = key === undefined ? undefined : slots[key]
+    if (!slot || node.optional)
+      throw new Themes.InvalidError(
+        'Dynamic reads require declared scalar fields without optional access.',
+        node,
+      )
+
+    return slot
+  }
+
+  return {
+    body,
+    accepts(reference: Binding.Reference, property: string) {
+      const values = numeric.get(reference)
+      const rule = Literal.rules[property as keyof typeof Literal.rules]
+      if (!values || !rule) return false
+
+      if (rule.kind === 'grid-line')
+        return values.every(
+          (value) => Number.isSafeInteger(value) && value !== 0,
+        )
+
+      if (rule.kind !== 'number') return false
+
+      return values.every(
+        (value) =>
+          (!('integer' in rule) ||
+            !rule.integer ||
+            Number.isSafeInteger(value)) &&
+          (!('min' in rule) || value >= rule.min) &&
+          (!('max' in rule) || value <= rule.max),
+      )
+    },
+    resolve,
+    slots: Object.freeze(slots),
+    type: parameter.typeAnnotation.typeAnnotation,
+  }
+}
+
+function scalar(
+  node: Ast.Node,
+): 'number' | 'string' | 'zero-string' | undefined {
+  if (node.type === 'TSIntersectionType') {
+    const kinds = node.types.map(scalar)
+
+    return kinds.length && kinds.every((kind) => kind === kinds[0])
+      ? kinds[0]
+      : undefined
+  }
+
+  if (node.type === 'TSNumberKeyword') return 'number'
+  if (node.type === 'TSStringKeyword') return 'string'
+
+  if (
+    node.type === 'TSTemplateLiteralType' &&
+    node.types.every((type) => scalar(type) !== undefined) &&
+    node.quasis.every((part) => !part.value.raw.includes('!'))
+  )
+    return 'string'
+
+  if (node.type === 'TSLiteralType') {
+    if (numbers(node)) return 'number'
+
+    if (
+      node.literal.type === 'Literal' &&
+      typeof node.literal.value === 'number'
+    )
+      return 'number'
+
+    if (
+      node.literal.type === 'Literal' &&
+      typeof node.literal.value === 'string' &&
+      !node.literal.value.includes('!') &&
+      !['initial', 'inherit', 'unset', 'revert', 'revert-layer'].includes(
+        node.literal.value.trim().toLowerCase(),
+      )
+    )
+      return 'string'
+  }
+
+  if (node.type === 'TSUnionType') {
+    const kinds = node.types.map(scalar)
+    if (
+      kinds.some((kind) => kind === 'string' || kind === 'zero-string') &&
+      node.types.every(
+        (type, index) =>
+          kinds[index] === 'string' ||
+          kinds[index] === 'zero-string' ||
+          numbers(type)?.every((value) => value === 0),
+      )
+    )
+      return 'zero-string'
+
+    if (kinds.length && kinds.every((kind) => kind === kinds[0]))
+      return kinds[0]
+  }
+
+  return undefined
+}
+
+function numbers(node: Ast.Node): readonly number[] | undefined {
+  if (node.type === 'TSIntersectionType') {
+    const domains = node.types
+      .filter((type) => type.type !== 'TSNumberKeyword')
+      .map(numbers)
+    if (!domains.length || domains.some((domain) => domain === undefined))
+      return undefined
+
+    return domains[0]!.filter((value) =>
+      domains.every((domain) => domain!.includes(value)),
+    )
+  }
+
+  if (node.type === 'TSUnionType') {
+    const members = node.types.map(numbers)
+
+    return members.every((member) => member !== undefined)
+      ? members.flat()
+      : undefined
+  }
+
+  if (node.type !== 'TSLiteralType') return undefined
+
+  const literal = node.literal
+  if (literal.type === 'Literal' && typeof literal.value === 'number')
+    return [literal.value]
+
+  if (
+    literal.type === 'UnaryExpression' &&
+    literal.operator === '-' &&
+    literal.argument.type === 'Literal' &&
+    typeof literal.argument.value === 'number'
+  )
+    return [-literal.argument.value]
+
+  return undefined
+}

package/src/compiler/internal/Edits.ts

@@ -0,0 +1,13 @@
+/** Preserves native source replacements for syntax-tree adapters. @module */
+export const key = Symbol('native edits')
+
+/** Babel lowers authored types and does not need generated callable annotations. */
+export const runtime = Symbol('native runtime output')
+
+/** A compiler-owned expression, statement replacement, or insertion. */
+export type Edit = {
+  readonly start: number
+  readonly end: number
+  readonly code: string
+  readonly expression: boolean
+}

package/src/compiler/internal/Expression.ts

@@ -0,0 +1,135 @@
+/**
+ * Reads static template primitives and transparent TypeScript syntax without execution.
+ * @module
+ */
+import type * as Ast from '@oxc-project/types'
+import * as Binding from '../../internal/Binding.js'
+import * as Token from '../../internal/Token.js'
+
+/** Folds cooked template text and literal primitive substitutions; unresolved syntax returns undefined. */
+export function template(
+  node: Ast.TemplateLiteral,
+  depth = 0,
+  resolve?: (
+    node: Ast.Node,
+    prefix: string,
+  ) => string | Token.Reference | Binding.Reference | undefined,
+  context = '',
+): string | Token.Expression | undefined {
+  if (depth >= 128) return undefined
+
+  const parts: (string | Token.Reference | Binding.Reference)[] = []
+
+  for (const [index, quasi] of node.quasis.entries()) {
+    if (quasi.value.cooked === null) return undefined
+
+    parts.push(quasi.value.cooked)
+
+    const expression = node.expressions[index]
+    if (!expression) continue
+
+    const value = unwrap(expression)
+    const prefix =
+      context +
+      parts
+        .map((part) =>
+          typeof part === 'string' ? part : 'var(--zyzz-expression)',
+        )
+        .join('')
+    const reference = resolve?.(expression, prefix) ?? resolve?.(value, prefix)
+
+    if (reference) {
+      if (
+        quoted(
+          parts
+            .filter((part): part is string => typeof part === 'string')
+            .join(''),
+        )
+      )
+        return undefined
+
+      // var() substitutions must remain whole CSS tokens.
+      if (
+        /[%a-zA-Z_\d.-]/.test(
+          node.quasis[index + 1]?.value.cooked?.[0] ?? '',
+        ) ||
+        /[\w.#@+\\-]$/.test(quasi.value.cooked)
+      )
+        return undefined
+
+      parts.push(reference)
+    } else if (value.type === 'Literal' && !('regex' in value)) {
+      if (typeof value.value === 'number' && !Number.isFinite(value.value))
+        return undefined
+
+      parts.push(String(value.value))
+    } else if (
+      value.type === 'UnaryExpression' &&
+      (value.operator === '-' || value.operator === '+') &&
+      value.argument.type === 'Literal' &&
+      typeof value.argument.value === 'number' &&
+      Number.isFinite(value.argument.value)
+    ) {
+      parts.push(
+        String(
+          value.operator === '-' ? -value.argument.value : value.argument.value,
+        ),
+      )
+    } else if (
+      value.type === 'UnaryExpression' &&
+      value.operator === '-' &&
+      value.argument.type === 'Literal' &&
+      typeof value.argument.value === 'bigint'
+    ) {
+      parts.push(String(-value.argument.value))
+    } else if (value.type === 'TemplateLiteral') {
+      const nested = template(value, depth + 1, resolve, prefix)
+      if (nested === undefined) return undefined
+
+      if (typeof nested === 'string') parts.push(nested)
+      else parts.push(...nested.parts)
+    } else return undefined
+  }
+
+  return parts.every((part) => typeof part === 'string')
+    ? parts.join('')
+    : Token.compose(parts)
+}
+
+/** Returns the expression beneath assertions without evaluating application code. */
+export function unwrap(node: Ast.Node): Ast.Node {
+  while (
+    node.type === 'TSAsExpression' ||
+    node.type === 'TSSatisfiesExpression' ||
+    node.type === 'TSNonNullExpression' ||
+    node.type === 'TSTypeAssertion'
+  )
+    node = node.expression
+
+  return node
+}
+
+function quoted(text: string): boolean {
+  let quote = ''
+
+  for (let index = 0; index < text.length; index++) {
+    const char = text[index]!
+
+    if (char === '\\') {
+      index++
+      continue
+    }
+
+    if (quote) {
+      if (char === quote) quote = ''
+    } else if (char === '"' || char === "'") quote = char
+    else if (char === '/' && text[index + 1] === '*') {
+      const end = text.indexOf('*/', index + 2)
+      if (end < 0) return true
+
+      index = end + 1
+    }
+  }
+
+  return !!quote
+}