zyzz 0.0.0 → 0.0.2

package/src/compiler/internal/Functions.ts

@@ -0,0 +1,206 @@
+/** Checks CSS function arguments and defaults against native syntax definitions. @module */
+import * as FunctionSyntax from '../../internal/FunctionSyntax.js'
+import * as Lightning from 'lightningcss'
+import * as Tree from 'css-tree'
+
+/** Checks complete static values while leaving computed substitutions to CSS. */
+export function value(syntax: string, input: string): string | undefined {
+  const text = input.trim()
+  const body =
+    text.startsWith('{') && text.endsWith('}') ? text.slice(1, -1) : text
+  const parsed = Tree.parse(body, { context: 'value' })
+  let computed = false
+  Tree.walk(parsed, (node) => {
+    if (
+      node.type === 'Function' &&
+      /^(?:--|var$|env$|attr$)/i.test(Tree.ident.decode(node.name))
+    )
+      computed = true
+  })
+  const normalized = syntax.trim()
+  const definition = normalized.startsWith('type(')
+    ? normalized.slice(5, -1).trim()
+    : normalized
+  if (computed || definition === '*') return
+  const alternatives: string[] = []
+  let start = 0
+  Tree.tokenize(definition, (type, from, to) => {
+    if (type === Tree.tokenTypes.Delim && definition.slice(from, to) === '|') {
+      alternatives.push(definition.slice(start, from).trim())
+      start = to
+    }
+  })
+  alternatives.push(definition.slice(start).trim())
+  for (const alternative of alternatives) {
+    try {
+      if (alternative.startsWith('<')) {
+        if (alternative.startsWith('<string>')) {
+          if (Tree.lexer.match(alternative, body).error) continue
+        } else
+          Lightning.transform({
+            filename: 'argument.css',
+            code: new TextEncoder().encode(
+              `@property --argument{syntax:${JSON.stringify(alternative)};inherits:false;initial-value:${body};}`,
+            ),
+          })
+        return alternative
+      }
+      let multiplier = ''
+      let atom = alternative
+      Tree.tokenize(alternative, (type, from, to) => {
+        if (
+          type === Tree.tokenTypes.Delim &&
+          to === alternative.length &&
+          ['+', '#'].includes(alternative.slice(from, to))
+        ) {
+          multiplier = alternative.slice(from, to)
+          atom = alternative.slice(0, from)
+        }
+      })
+      const expected = Tree.ident.decode(atom)
+      const nodes = (parsed as Tree.Value).children.toArray()
+      let count = 0
+      let comma = false
+      let valid = true
+      for (const node of nodes) {
+        if (
+          node.type === 'Operator' &&
+          node.value === ',' &&
+          multiplier === '#' &&
+          count > 0 &&
+          !comma
+        ) {
+          comma = true
+          continue
+        }
+        if (
+          node.type !== 'Identifier' ||
+          Tree.ident.decode(node.name) !== expected ||
+          (count > 0 && (multiplier === '' || (multiplier === '#' && !comma)))
+        ) {
+          valid = false
+          break
+        }
+        count++
+        comma = false
+      }
+      if (valid && count > 0 && !comma) return alternative
+    } catch {
+      /* Another syntax alternative may accept this value. */
+    }
+  }
+  throw new Error('Invalid CSS function argument for its declared syntax.')
+}
+
+/** Validates packed function headers and body contexts before parser recovery. */
+export function validate(source: string): void {
+  Tree.walk(Tree.parse(source), {
+    visit: 'Atrule',
+    enter(rule) {
+      if (rule.name.toLowerCase() !== 'function') return
+      if (!rule.prelude || !rule.block)
+        throw new Error('CSS functions require parameters and a body.')
+      const prelude = Tree.generate(rule.prelude)
+      let opening = 0
+      let closing = -1
+      let depth = 0
+      const commas: number[] = []
+      Tree.tokenize(prelude, (type, start, end) => {
+        if (closing >= 0) return
+        if (
+          type === Tree.tokenTypes.Function ||
+          type === Tree.tokenTypes.LeftParenthesis
+        ) {
+          if (depth === 0) {
+            const name = Tree.ident.decode(prelude.slice(start, end - 1))
+            if (
+              start !== 0 ||
+              type !== Tree.tokenTypes.Function ||
+              !name.startsWith('--') ||
+              name.length <= 2
+            )
+              throw new Error('CSS function names require a dashed identifier.')
+            opening = end
+          }
+          depth++
+        } else if (type === Tree.tokenTypes.RightParenthesis) {
+          depth--
+          if (depth === 0) closing = start
+        } else if (type === Tree.tokenTypes.Comma && depth === 1)
+          commas.push(start)
+      })
+      if (closing < 0) throw new Error('Unclosed CSS function parameters.')
+      const names = new Set<string>()
+      let start = opening
+      for (const end of [...commas, closing]) {
+        const parameter = prelude.slice(start, end).trim()
+        start = end + 1
+        if (!parameter && end === closing && opening === closing) continue
+        let name = ''
+        let offset = 0
+        let colon = -1
+        let depth = 0
+        Tree.tokenize(parameter, (type, from, to) => {
+          if (from === 0 && type === Tree.tokenTypes.Ident) {
+            name = Tree.ident.decode(parameter.slice(from, to))
+            offset = to
+          }
+          if (
+            type === Tree.tokenTypes.Function ||
+            type === Tree.tokenTypes.LeftParenthesis
+          )
+            depth++
+          if (type === Tree.tokenTypes.RightParenthesis) depth--
+          if (type === Tree.tokenTypes.Colon && depth === 0 && colon < 0)
+            colon = from
+        })
+        if (!name.startsWith('--') || name.length <= 2 || names.has(name))
+          throw new Error(
+            'CSS function parameters require unique dashed names.',
+          )
+        names.add(name)
+        const syntax =
+          parameter.slice(offset, colon < 0 ? undefined : colon).trim() || '*'
+        if (!FunctionSyntax.accepts(syntax))
+          throw new Error('Invalid CSS function parameter syntax.')
+        if (colon >= 0) value(syntax, parameter.slice(colon + 1))
+      }
+      const returns = prelude.slice(closing + 1).trim()
+      if (
+        returns &&
+        (!returns.startsWith('returns ') ||
+          !FunctionSyntax.accepts(returns.slice(8)))
+      )
+        throw new Error('Invalid CSS function return syntax.')
+      function body(block: Tree.Block): void {
+        const declarations = Tree.parse(Tree.generate(block).slice(1, -1), {
+          context: 'declarationList',
+        }) as Tree.DeclarationList
+        declarations.children.forEach((node) => {
+          if (
+            node.type === 'Atrule' &&
+            ['media', 'supports', 'container'].includes(node.name) &&
+            node.block &&
+            node.prelude
+          ) {
+            if (
+              Tree.lexer.matchAtrulePrelude(
+                node.name,
+                Tree.generate(node.prelude),
+              ).error
+            )
+              throw new Error('Invalid CSS function condition.')
+            body(node.block)
+          } else if (
+            node.type === 'Declaration' &&
+            !node.important &&
+            (node.property === 'result' || node.property.startsWith('--'))
+          ) {
+            value('*', Tree.generate(node.value))
+          } else throw new Error('Invalid CSS function body context.')
+        })
+      }
+      body(rule.block)
+    },
+  })
+}

package/src/compiler/internal/Identifiers.ts

@@ -0,0 +1,124 @@
+/** Decodes CSS identifier spellings at source and packed compiler boundaries. @module */
+import * as Lightning from 'lightningcss'
+
+/** Reads an entire CSS identifier list, including escaped delimiters and comments. */
+export function list(
+  value: string,
+  separator: 'comma' | 'space',
+): readonly string[] | undefined {
+  const input = tokens(value)
+  if (!input) return undefined
+  const names: string[] = []
+  let needName = true
+  for (const token of input) {
+    if (token.type === 'token' && token.value.type === 'comma') {
+      if (separator !== 'comma' || needName) return undefined
+      needName = true
+      continue
+    }
+    const name =
+      token.type === 'dashed-ident'
+        ? token.value
+        : token.type === 'token' && token.value.type === 'ident'
+          ? token.value.value
+          : undefined
+    if (name === undefined || (!needName && separator === 'comma'))
+      return undefined
+    names.push(name)
+    needName = false
+  }
+  return !needName && names.length ? names : undefined
+}
+
+/** Checks a complete CSS URL value without accepting an injected declaration. */
+export function url(value: string): boolean {
+  const input = tokens(value)
+  return input?.length === 1 && input[0]?.type === 'url'
+}
+
+function tokens(value: string): readonly Lightning.TokenOrValue[] | undefined {
+  try {
+    let result: readonly Lightning.TokenOrValue[] | undefined
+    Lightning.transform({
+      filename: 'tokens.css',
+      code: new TextEncoder().encode(`@zyzz-tokens ${value};`),
+      visitor: {
+        StyleSheet(sheet) {
+          const rule = sheet.rules[0]
+          if (
+            sheet.rules.length === 1 &&
+            rule?.type === 'unknown' &&
+            rule.value.name === 'zyzz-tokens' &&
+            rule.value.block === null
+          )
+            result = rule.value.prelude.filter(
+              (token) =>
+                !(
+                  token.type === 'token' &&
+                  ['white-space', 'comment'].includes(token.value.type)
+                ),
+            )
+        },
+      },
+    })
+    return result
+  } catch {
+    return undefined
+  }
+}
+
+/** Returns the identifier token value, or undefined for malformed input. */
+export function read(value: string): string | undefined {
+  if (/^(?:--|-?[_a-zA-Z])[\w-]*$/.test(value)) return value
+
+  try {
+    let decoded: string | undefined
+    Lightning.transform({
+      filename: 'identifier.css',
+      code: new TextEncoder().encode(
+        `@namespace ${value}\n"urn:zyzz:identifier";`,
+      ),
+      visitor: {
+        StyleSheet(sheet) {
+          const rule = sheet.rules[0]
+          if (
+            sheet.rules.length === 1 &&
+            rule?.type === 'namespace' &&
+            rule.value.url === 'urn:zyzz:identifier'
+          )
+            decoded = rule.value.prefix ?? undefined
+        },
+      },
+    })
+    return decoded
+  } catch {
+    return undefined
+  }
+}
+
+/** Reads an explicit authoring identity shared with uncompiled execution. */
+export function explicit(
+  call: import('@oxc-project/types').CallExpression,
+): string | undefined {
+  const argument = call.arguments[1]
+  if (!argument) return undefined
+  if (argument.type !== 'ObjectExpression' || argument.properties.length !== 1)
+    throw new Error('Definition options require one literal id.')
+  const property = argument.properties[0]!
+  if (
+    property.type !== 'Property' ||
+    property.computed ||
+    property.kind !== 'init' ||
+    property.method ||
+    (property.key.type === 'Identifier'
+      ? property.key.name
+      : property.key.type === 'Literal'
+        ? property.key.value
+        : undefined) !== 'id' ||
+    property.value.type !== 'Literal' ||
+    typeof property.value.value !== 'string' ||
+    !property.value.value
+  )
+    throw new Error('Definition options require one nonempty literal id.')
+  return property.value.value
+}

package/src/compiler/internal/Keyframes.ts

@@ -0,0 +1,62 @@
+/** Checks complete keyframe selectors, including named timeline ranges. @module */
+import * as Lightning from 'lightningcss'
+
+/** Rejects invalid ordinary offsets and importance in transported keyframes. */
+export function validate(source: string): void {
+  Lightning.transform({
+    filename: 'keyframes.css',
+    code: new TextEncoder().encode(source),
+    visitor: {
+      Rule(rule) {
+        if (rule.type !== 'keyframes') return
+        for (const frame of rule.value.keyframes) {
+          if (
+            frame.selectors.some(
+              (selector) =>
+                selector.type === 'percentage' &&
+                (selector.value < 0 || selector.value > 1),
+            )
+          )
+            throw new Error('Ordinary keyframe offsets must be within 0–100%.')
+          if (frame.declarations.importantDeclarations?.length)
+            throw new Error('Keyframes forbid important declarations.')
+        }
+      },
+    },
+  })
+}
+
+/** Named timeline percentages are unrestricted; ordinary offsets remain within 0–100%. */
+export function accepts(selector: string): boolean {
+  try {
+    let valid = false
+    Lightning.transform({
+      filename: 'keyframe.css',
+      code: new TextEncoder().encode(
+        `@keyframes zyzz {${selector}{opacity:0}}`,
+      ),
+      visitor: {
+        StyleSheet(sheet) {
+          const rule = sheet.rules[0]
+          if (
+            sheet.rules.length !== 1 ||
+            rule?.type !== 'keyframes' ||
+            rule.value.keyframes.length !== 1
+          )
+            return
+          const frame = rule.value.keyframes[0]!
+          valid =
+            frame.selectors.length > 0 &&
+            frame.selectors.every(
+              (selector) =>
+                selector.type !== 'percentage' ||
+                (selector.value >= 0 && selector.value <= 1),
+            )
+        },
+      },
+    })
+    return valid
+  } catch {
+    return false
+  }
+}

package/src/compiler/internal/Namespaces.ts

@@ -0,0 +1,296 @@
+/** Isolates CSS namespace selectors and composes their generated source maps. @module */
+import MagicString, { Bundle } from 'magic-string'
+import * as Mapping from '@jridgewell/gen-mapping'
+import * as Trace from '@jridgewell/trace-mapping'
+import type * as Lightning from 'lightningcss'
+import * as Namespace from '../../web/internal/Namespace.js'
+import * as AtRules from './AtRules.js'
+import * as Identifiers from './Identifiers.js'
+
+/** Rewrites namespace-sensitive selectors using native selector ASTs. */
+export function rewrite(
+  css: string,
+  namespaces: readonly Namespace.Definition[],
+  previous?: Mapping.EncodedSourceMap,
+  includeDeclarations = false,
+) {
+  if (!namespaces.length || !css) return { css, map: previous }
+  // Last bindings win across the module, including equivalent escaped spellings.
+  const names = new Map(
+    namespaces.map((value) => [
+      value.prefix === undefined ? undefined : Identifiers.read(value.prefix),
+      value.name,
+    ]),
+  )
+  function selector(input: Lightning.Selector): Lightning.Selector {
+    const output: Lightning.Selector = []
+    let first = true
+    for (const original of input) {
+      let component = original
+      if (component.type === 'combinator') first = true
+      else if (first) {
+        const name = names.get(undefined)
+        if (
+          name &&
+          component.type !== 'namespace' &&
+          component.type !== 'nesting'
+        ) {
+          output.push({ type: 'namespace', kind: 'named', prefix: name })
+          if (component.type !== 'type' && component.type !== 'universal')
+            output.push({ type: 'universal' })
+        }
+        first = false
+      }
+      if (component.type === 'namespace' && component.kind === 'named')
+        component = {
+          ...component,
+          prefix: names.get(component.prefix) ?? component.prefix,
+        }
+      if (
+        component.type === 'attribute' &&
+        component.namespace?.type === 'specific'
+      )
+        component = {
+          ...component,
+          namespace: {
+            ...component.namespace,
+            prefix:
+              names.get(component.namespace.prefix) ??
+              component.namespace.prefix,
+          },
+        }
+      if ('selectors' in component && Array.isArray(component.selectors))
+        component = {
+          ...component,
+          selectors: Array.isArray(component.selectors[0])
+            ? (component.selectors as Lightning.Selector[]).map(selector)
+            : selector(component.selectors as Lightning.Selector),
+        } as typeof component
+      if ('of' in component && component.of)
+        component = { ...component, of: component.of.map(selector) }
+      output.push(component)
+    }
+    return output
+  }
+  const declared = new Set<string>()
+  const rewritten = AtRules.transform({
+    filename: 'zyzz.css',
+    code: new TextEncoder().encode(css),
+    sourceMap: !!previous,
+    visitor: {
+      Selector: selector,
+      Rule(rule) {
+        if (rule.type === 'namespace' && rule.value.prefix)
+          declared.add(rule.value.prefix)
+      },
+    },
+  })
+  const declarations = includeDeclarations
+    ? namespaces
+        .filter((value) => !declared.has(value.name))
+        .map(Namespace.statement)
+    : []
+  const output = [
+    ...declarations,
+    new TextDecoder().decode(rewritten.code).trimEnd(),
+  ].join('\n')
+  if (!previous || !rewritten.map) return { css: output, map: previous }
+  const input = new Trace.TraceMap(previous)
+  const map = new Mapping.GenMapping({ file: previous.file ?? 'zyzz.css' })
+  Trace.eachMapping(
+    new Trace.TraceMap(JSON.parse(new TextDecoder().decode(rewritten.map))),
+    (entry) => {
+      if (entry.originalLine === null || entry.originalColumn === null) return
+      const original = Trace.originalPositionFor(input, {
+        line: entry.originalLine,
+        column: entry.originalColumn,
+      })
+      if (
+        original.line === null ||
+        original.column === null ||
+        original.source === null
+      )
+        return
+      const generated = {
+        line: entry.generatedLine + declarations.length,
+        column: entry.generatedColumn,
+      }
+      const position = { line: original.line, column: original.column }
+      if (original.name)
+        Mapping.addMapping(map, {
+          generated,
+          original: position,
+          source: original.source,
+          name: original.name,
+        })
+      else
+        Mapping.addMapping(map, {
+          generated,
+          original: position,
+          source: original.source,
+        })
+    },
+  )
+  previous.sources.forEach((source, index) => {
+    if (source !== null)
+      Mapping.setSourceContent(
+        map,
+        source,
+        previous.sourcesContent?.[index] ?? null,
+      )
+  })
+  return { css: output, map: Mapping.toEncodedMap(map) }
+}
+
+/** Reads namespace metadata at the packed-library boundary. */
+export function read(value: unknown): readonly Namespace.Definition[] {
+  if (value === undefined) return []
+  if (!Array.isArray(value)) throw new Error('Invalid packed namespaces.')
+  return value.map((entry: unknown) => {
+    if (!entry || typeof entry !== 'object')
+      throw new Error('Invalid packed namespace.')
+    const { name, prefix, uri } = entry as Partial<Namespace.Definition>
+    const decoded =
+      typeof prefix === 'string' ? Identifiers.read(prefix) : undefined
+    if (
+      typeof name !== 'string' ||
+      !/^z-n[a-z0-9-]+$/.test(name) ||
+      typeof uri !== 'string' ||
+      (prefix !== undefined &&
+        (typeof prefix !== 'string' || decoded === undefined))
+    )
+      throw new Error('Invalid packed namespace.')
+    return { name, uri, ...(prefix !== undefined ? { prefix } : {}) }
+  })
+}
+
+/** Shields namespaces until Vite has concatenated and minified its CSS chunks. */
+export function protect(css: string): string {
+  return AtRules.rename(css, 'namespace', '-zyzz-ns-')
+}
+
+/** Restores namespace declarations to the stylesheet prolog after bundling. */
+export function bundle(css: string, previous?: Mapping.EncodedSourceMap) {
+  if (!css.includes('@-zyzz-ns-')) return { css, map: previous }
+  const lines = [0]
+  for (let index = 0; index < css.length; index++)
+    if (css[index] === '\n') lines.push(index + 1)
+  const statements: { start: number; end: number; namespace: boolean }[] = []
+  AtRules.transform({
+    filename: 'bundle.css',
+    code: new TextEncoder().encode(css),
+    visitor: {
+      StyleSheet(sheet) {
+        let prolog = true
+        for (const rule of sheet.rules) {
+          const namespace =
+            rule.type === 'unknown' && rule.value.name === '-zyzz-ns-'
+          if (
+            !namespace &&
+            rule.type !== 'import' &&
+            rule.type !== 'layer-statement'
+          )
+            prolog = false
+          if (
+            !namespace &&
+            rule.type !== 'import' &&
+            !(rule.type === 'layer-statement' && prolog)
+          )
+            continue
+          if (!('value' in rule) || !('loc' in rule.value)) continue
+          const start = lines[rule.value.loc.line]! + rule.value.loc.column - 1
+          let quote = '',
+            parentheses = 0,
+            end = start
+          for (; end < css.length; end++) {
+            const char = css[end]
+            if (char === '\\') {
+              end++
+              continue
+            }
+            if (quote) {
+              if (char === quote) quote = ''
+              continue
+            }
+            if (char === '"' || char === "'") quote = char
+            else if (char === '/' && css[end + 1] === '*')
+              end = css.indexOf('*/', end + 2) + 1
+            else if (char === '(') parentheses++
+            else if (char === ')') parentheses--
+            else if (char === ';' && !parentheses) {
+              end++
+              break
+            }
+          }
+          statements.push({ start, end, namespace })
+        }
+      },
+    },
+  })
+  const original = new MagicString(css, { filename: 'bundle.css' })
+  const output = new Bundle({ separator: '' })
+  const remaining = original.clone()
+  const seen = new Set<string>()
+  for (const statement of statements.toSorted(
+    (a, b) => Number(a.namespace) - Number(b.namespace),
+  )) {
+    const text = css.slice(statement.start, statement.end)
+    remaining.remove(statement.start, statement.end)
+    if (statement.namespace && seen.has(text)) continue
+    if (statement.namespace) seen.add(text)
+    output.addSource({
+      content: original.snip(statement.start, statement.end),
+      filename: 'bundle.css',
+    })
+  }
+  output.addSource({ content: remaining, filename: 'bundle.css' })
+  const restored = AtRules.rename(output.toString(), '-zyzz-ns-', 'namespace')
+  if (!previous) return { css: restored, map: previous }
+  const input = new Trace.TraceMap(previous)
+  const map = new Mapping.GenMapping({ file: previous.file ?? 'bundle.css' })
+  Trace.eachMapping(
+    new Trace.TraceMap(
+      output.generateMap({ hires: true, includeContent: true }).toString(),
+    ),
+    (entry) => {
+      if (entry.originalLine === null || entry.originalColumn === null) return
+      const original = Trace.originalPositionFor(input, {
+        line: entry.originalLine,
+        column: entry.originalColumn,
+      })
+      if (
+        original.source === null ||
+        original.line === null ||
+        original.column === null
+      )
+        return
+      const generated = {
+        line: entry.generatedLine,
+        column: entry.generatedColumn,
+      }
+      const position = { line: original.line, column: original.column }
+      if (original.name)
+        Mapping.addMapping(map, {
+          generated,
+          original: position,
+          source: original.source,
+          name: original.name,
+        })
+      else
+        Mapping.addMapping(map, {
+          generated,
+          original: position,
+          source: original.source,
+        })
+    },
+  )
+  previous.sources.forEach((source, index) => {
+    if (source !== null)
+      Mapping.setSourceContent(
+        map,
+        source,
+        previous.sourcesContent?.[index] ?? null,
+      )
+  })
+  return { css: restored, map: Mapping.toEncodedMap(map) }
+}