zyzz 0.0.0 → 0.0.3

package/src/internal/Condition.ts

@@ -0,0 +1,283 @@
+/** Typed nested selector and condition keys without a general string index. @module */
+import type * as Theme from '../Theme.js'
+
+type Case<text extends string> = text extends `${infer first}${infer rest}`
+  ? `${Lowercase<first> | Uppercase<first>}${Case<rest>}`
+  : ''
+
+type Media = Case<'all' | 'print' | 'screen'>
+
+/** Explicit scoped selectors and standard conditional rule forms. */
+export type Raw =
+  | `@${'media' | 'supports' | 'container' | 'scope' | 'layer'}${'\t' | '\n' | '\r' | '\f' | '(' | `/*${string}*/`}${string}`
+  | `${string}&${string}`
+  | `:${string}`
+  | `@document ${string}`
+  | '@starting-style'
+  | '@scope'
+  | '@layer'
+  | `@scope (${string}`
+  | `@scope to (${string}`
+  | `@layer ${string}`
+  | `@container scroll-state(${string}`
+  | `@container ${string} scroll-state(${string}`
+  | `@container not ${string}`
+  | `@supports selector(${string}`
+  | `@supports ${string}(${string}`
+  | `@media (${string}`
+  | `@media ${Media}`
+  | `@media ${Media} ${string}`
+  | `@media ${Media},${string}`
+  | `@media ${Case<'only' | 'not'>} ${string}`
+  | `@container style(${string}`
+  | `@container ${string} style(${string}`
+  | `@container (${string}`
+  | `@container ${string} (${string}`
+
+type Names<tokens, group extends PropertyKey> = group extends keyof tokens
+  ? `${Extract<keyof NonNullable<tokens[group]>, string | number>}`
+  : never
+
+type Alias<name extends string> =
+  | name
+  | `>=${name}`
+  | `<${name}`
+  | `${name}..${name}`
+
+type Containers<tokens> = tokens extends {
+  containerNames: readonly (infer name extends string)[]
+}
+  ? name
+  : never
+declare const query: unique symbol
+/** Opaque grouping key emitted by a custom-media declaration. */
+export type Query = symbol & { readonly [query]: true }
+
+declare const relationship: unique symbol
+/** Opaque key returned only by typed relationship authoring helpers. */
+export type Relationship = symbol & { readonly [relationship]: true }
+
+/** Keys inferred from the bound theme's own threshold groups. */
+export type Keys<
+  tokens extends Theme.Tokens = {},
+  key extends PropertyKey = never,
+> =
+  | ([key] extends [never]
+      ? never
+      : symbol extends key
+        ? symbol
+        : Relationship | Query)
+  | Raw
+  | `@media ${Alias<Names<tokens, 'breakpoints'>>}`
+  | `@container ${Alias<Names<tokens, 'containers'>>}`
+  | `@container ${Containers<tokens>} ${Alias<Names<tokens, 'containers'>>}`
+
+/** Recognizes structured rule keys before declaration parsing. */
+export function is(key: string): boolean {
+  if (key.startsWith('--')) return false
+
+  return (
+    nested(key) ||
+    key.startsWith(':') ||
+    ['@starting-style', '@scope', '@layer'].includes(key) ||
+    /^@(media|supports|container|scope|layer|document)(?=[\t\n\r\f (]|\/\*)/.test(
+      key,
+    )
+  )
+}
+
+/** Detects nesting tokens outside quoted data, comments, and escapes. */
+export function nested(key: string): boolean {
+  let quote = ''
+
+  for (let index = 0; index < key.length; index++) {
+    const char = key[index]!
+
+    if (char === '\\') {
+      index++
+      continue
+    }
+
+    if (quote) {
+      if (char === quote) quote = ''
+
+      continue
+    }
+
+    if (char === '"' || char === "'") {
+      quote = char
+      continue
+    }
+
+    if (char === '/' && key[index + 1] === '*') {
+      const end = key.indexOf('*/', index + 2)
+      if (end === -1) return false
+
+      index = end + 1
+    } else if (char === '&') return true
+  }
+
+  return false
+}
+
+/** Normalizes rule whitespace and rejects unbalanced delimiters and unscoped selector lists. */
+export function normalize(key: string): string {
+  const stack: string[] = []
+  let quote = ''
+  let output = ''
+  let scoped = false
+  let list = false
+
+  for (let index = 0; index < key.length; index++) {
+    const char = key[index]!
+
+    if (!quote && char === '/' && key[index + 1] === '*') {
+      const end = key.indexOf('*/', index + 2)
+      if (end === -1) throw new Error('Unterminated condition comment.')
+
+      output += key.slice(index, end + 2).replace(/[\n\r\f]/g, ' ')
+      index = end + 1
+      continue
+    }
+
+    if (char === '\\') {
+      const next = key[++index]
+      if (next === undefined) throw new Error('Incomplete condition escape.')
+
+      if (next !== '\n' && next !== '\r' && next !== '\f') output += char + next
+      else if (next === '\r' && key[index + 1] === '\n') index++
+
+      continue
+    }
+
+    if (quote) {
+      output += char
+
+      if (char === quote) quote = ''
+
+      continue
+    }
+
+    if (char === '"' || char === "'") quote = char
+    else if (char === '(' || char === '[') stack.push(char === '(' ? ')' : ']')
+    else if (char === ')' || char === ']') {
+      if (stack.pop() !== char)
+        throw new Error('Unbalanced condition delimiters.')
+    } else if (char === '{' || char === '}')
+      throw new Error('Unexpected condition block delimiter.')
+    else if (char === '&') scoped = true
+    else if (char === ',' && !stack.length && !key.startsWith('@')) {
+      if (!scoped)
+        throw new Error('Selector lists require explicit & selectors.')
+
+      scoped = false
+      list = true
+    }
+
+    output += /[\n\r\f]/.test(char) ? ' ' : char
+  }
+
+  if (quote || stack.length) throw new Error('Unbalanced condition delimiters.')
+
+  if (list && !scoped)
+    throw new Error('Selector lists require explicit & selectors.')
+
+  return output
+}
+
+/** Identifies conservative same-element selectors for private inline callback variables. */
+export function local(key: string): boolean {
+  if (key.startsWith('@')) return true
+
+  let nesting = 0
+  let quoted = ''
+
+  for (let index = 0; index < key.length; index++) {
+    const char = key[index]!
+
+    if (!quoted && char === '/' && key[index + 1] === '*') {
+      const end = key.indexOf('*/', index + 2)
+      if (end < 0) return false
+
+      index = end + 1
+      continue
+    }
+
+    if (char === '\\') {
+      index++
+      continue
+    }
+
+    if (quoted) {
+      if (char === quoted) quoted = ''
+
+      continue
+    }
+
+    if (char === '"' || char === "'") quoted = char
+    else if (char === '(' || char === '[') nesting++
+    else if (char === ')' || char === ']') nesting--
+    else if (char === ',' && !nesting)
+      return (
+        local(key.slice(0, index).trim()) && local(key.slice(index + 1).trim())
+      )
+  }
+
+  if (!key.startsWith('&') && (!key.startsWith(':') || nested(key)))
+    return false
+
+  let depth = 0
+  let quote = ''
+
+  for (let index = 0; index < key.length; index++) {
+    const char = key[index]!
+
+    if (!quote && char === '/' && key[index + 1] === '*') {
+      const end = key.indexOf('*/', index + 2)
+      if (end < 0) return false
+
+      index = end + 1
+      continue
+    }
+
+    if (char === '\\') {
+      index++
+      continue
+    }
+
+    if (quote) {
+      if (char === quote) quote = ''
+
+      continue
+    }
+
+    if (char === '"' || char === "'") {
+      quote = char
+      continue
+    }
+
+    if (!depth && char === ':' && key[index + 1] === ':') {
+      const name = /^::([a-z-]+)/i.exec(key.slice(index))?.[1]?.toLowerCase()
+      if (
+        !name ||
+        ![
+          'before',
+          'after',
+          'first-letter',
+          'first-line',
+          'marker',
+          'placeholder',
+          'selection',
+        ].includes(name)
+      )
+        return false
+    }
+
+    if (char === '(' || char === '[') depth++
+    else if (char === ')' || char === ']') depth--
+    else if (!depth && (/[\s+~>,]/.test(char) || (char === '&' && index !== 0)))
+      return false
+  }
+
+  return true
+}

package/src/internal/Corner.ts

@@ -0,0 +1,17 @@
+/**
+ * Describes corner curvature keywords and numeric superellipse functions.
+ * @module
+ */
+
+/** Canonical corner shapes and explicit superellipse curvature. */
+export type Value = (typeof keywords)[number] | `superellipse(${string})`
+
+/** Named curvature values from the CSS Borders grammar. */
+export const keywords = [
+  'bevel',
+  'notch',
+  'round',
+  'scoop',
+  'square',
+  'squircle',
+] as const

package/src/internal/FunctionSyntax.ts

@@ -0,0 +1,271 @@
+/** Models CSS function syntax components and composite alternatives. @module */
+
+/** Value types in the CSS Properties and Values syntax-definition grammar. */
+export const primitives = [
+  '<angle>',
+  '<color>',
+  '<custom-ident>',
+  '<image>',
+  '<integer>',
+  '<length>',
+  '<length-percentage>',
+  '<number>',
+  '<percentage>',
+  '<resolution>',
+  '<string>',
+  '<time>',
+  '<transform-function>',
+  '<transform-list>',
+  '<url>',
+] as const
+
+/** One primitive syntax component. */
+export type Primitive = (typeof primitives)[number]
+
+/** Removes CSS whitespace around signature components. */
+export type Trim<value extends string> =
+  value extends `${' ' | '\t' | '\n' | '\r' | '\f'}${infer rest}`
+    ? Trim<rest>
+    : value extends `${infer rest}${' ' | '\t' | '\n' | '\r' | '\f'}`
+      ? Trim<rest>
+      : value
+
+/** Removes the type() wrapper without changing authored alternatives. */
+export type Unwrap<value extends string> =
+  Trim<value> extends `type(${infer body})` ? Trim<body> : Trim<value>
+
+/** Rejects unsupported syntax-definition structure at the authoring boundary. */
+export type Checked<value extends string> = string extends value
+  ? never
+  : Trim<value> extends '*'
+    ? value
+    : Trim<value> extends `type(${infer body})`
+      ? Trim<body> extends '*'
+        ? value
+        : Valid<Trim<body>> extends true
+          ? value
+          : never
+      : Component<Trim<value>> extends true
+        ? value
+        : never
+
+type Valid<value extends string> = value extends `${infer first}|${infer rest}`
+  ? Component<Trim<first>> extends true
+    ? Valid<Trim<rest>>
+    : false
+  : Component<value>
+
+type Component<value extends string> = value extends `${infer base}${'+' | '#'}`
+  ? base extends '<transform-list>'
+    ? false
+    : Atom<base>
+  : Atom<value>
+
+type AsciiOther =
+  | ' '
+  | '\t'
+  | '\n'
+  | '\r'
+  | '\f'
+  | '!'
+  | '"'
+  | '#'
+  | '$'
+  | '%'
+  | '&'
+  | "'"
+  | '('
+  | ')'
+  | '*'
+  | '+'
+  | ','
+  | '.'
+  | '/'
+  | ':'
+  | ';'
+  | '<'
+  | '='
+  | '>'
+  | '?'
+  | '@'
+  | '['
+  | '\\'
+  | ']'
+  | '^'
+  | '`'
+  | '{'
+  | '|'
+  | '}'
+  | '~'
+type Letter =
+  | 'a'
+  | 'b'
+  | 'c'
+  | 'd'
+  | 'e'
+  | 'f'
+  | 'g'
+  | 'h'
+  | 'i'
+  | 'j'
+  | 'k'
+  | 'l'
+  | 'm'
+  | 'n'
+  | 'o'
+  | 'p'
+  | 'q'
+  | 'r'
+  | 's'
+  | 't'
+  | 'u'
+  | 'v'
+  | 'w'
+  | 'x'
+  | 'y'
+  | 'z'
+type Tail<value extends string> = value extends ''
+  ? true
+  : value extends `${infer first}${infer rest}`
+    ? Lowercase<first> extends
+        | Letter
+        | '_'
+        | '-'
+        | '0'
+        | '1'
+        | '2'
+        | '3'
+        | '4'
+        | '5'
+        | '6'
+        | '7'
+        | '8'
+        | '9'
+      ? Tail<rest>
+      : first extends AsciiOther
+        ? false
+        : Tail<rest>
+    : false
+type Identifier<value extends string> = value extends `--${infer rest}`
+  ? Tail<rest>
+  : value extends `-${infer rest}`
+    ? Identifier<rest>
+    : value extends `${infer first}${infer rest}`
+      ? Lowercase<first> extends Letter | '_'
+        ? Tail<rest>
+        : first extends AsciiOther | `${number}`
+          ? false
+          : Tail<rest>
+      : false
+type Atom<value extends string> = value extends `${string}\\${string}`
+  ? true
+  : value extends Primitive
+    ? true
+    : Lowercase<value> extends
+          | 'default'
+          | 'inherit'
+          | 'initial'
+          | 'revert'
+          | 'revert-layer'
+          | 'unset'
+      ? false
+      : Identifier<value>
+
+/** Checks a source-extracted signature without executing application code. */
+export function accepts(value: string): boolean {
+  const text = value.trim()
+  if (text === '*') return true
+
+  const wrapped = text.startsWith('type(') && text.endsWith(')')
+  const body = wrapped ? text.slice(5, -1).trim() : text
+  if (wrapped && body === '*') return true
+  if (!wrapped && body.includes('|')) return false
+
+  const escape = String.raw`\\(?:[0-9a-fA-F]{1,6}[ \t\n\r\f]?|[^\n\r\f0-9a-fA-F])`
+  const start = `(?:[_a-zA-Z\\u0080-\\uFFFF]|${escape})`
+  const tail = `(?:[-_a-zA-Z0-9\\u0080-\\uFFFF]|${escape})*`
+  const component = new RegExp(
+    `(?:<[-a-z]+>|(?:--|-${start}|${start})${tail})([+#])?`,
+    'y',
+  )
+  let index = 0
+  while (index < body.length) {
+    while (/[ \t\n\r\f]/.test(body[index] ?? '') && index < body.length) index++
+    component.lastIndex = index
+    const match = component.exec(body)
+    if (!match) return false
+    const atom = match[0].slice(0, match[0].length - (match[1]?.length ?? 0))
+    if (atom.startsWith('<')) {
+      if (
+        !(primitives as readonly string[]).includes(atom) ||
+        (atom === '<transform-list>' && match[1])
+      )
+        return false
+    } else {
+      const decoded = atom.replace(
+        /\\([0-9a-fA-F]{1,6})[ \t\n\r\f]?|\\([^\n\r\f])/g,
+        (_, hex: string | undefined, literal: string | undefined) => {
+          const point = hex ? Number.parseInt(hex, 16) : 0
+          return hex
+            ? String.fromCodePoint(
+                point === 0 ||
+                  point > 0x10ffff ||
+                  (point >= 0xd800 && point <= 0xdfff)
+                  ? 0xfffd
+                  : point,
+              )
+            : literal!
+        },
+      )
+      if (
+        [
+          'default',
+          'inherit',
+          'initial',
+          'revert',
+          'revert-layer',
+          'unset',
+        ].includes(decoded.replace(/[A-Z]/g, (c) => c.toLowerCase()))
+      )
+        return false
+    }
+    index = component.lastIndex
+    while (index < body.length && /[ \t\n\r\f]/.test(body[index]!)) index++
+    if (index === body.length) return true
+    if (!wrapped || body[index++] !== '|') return false
+    if (index === body.length) return false
+  }
+  return false
+}
+
+/** Whether numeric arguments are restricted to integer tokens by every alternative. */
+export type IntegerOnly<syntax extends string> =
+  'number' extends NumericKind<Unwrap<syntax>>
+    ? false
+    : 'integer' extends NumericKind<Unwrap<syntax>>
+      ? true
+      : false
+
+type NumericKind<syntax extends string> =
+  syntax extends `${infer first}|${infer rest}`
+    ? NumericKind<Trim<first>> | NumericKind<Trim<rest>>
+    : syntax extends `${infer base}+` | `${infer base}#`
+      ? NumericKind<base>
+      : syntax extends '<number>'
+        ? 'number'
+        : syntax extends '<integer>'
+          ? 'integer'
+          : never
+
+/** Finds the integer-only scalar domain in a checked function signature. */
+export function integerOnly(syntax: string): boolean {
+  const value = syntax.trim()
+  const body = value.startsWith('type(') ? value.slice(5, -1) : value
+  const alternatives = body
+    .split('|')
+    .map((value) => value.trim().replace(/[+#]$/, ''))
+
+  return (
+    alternatives.includes('<integer>') && !alternatives.includes('<number>')
+  )
+}

package/src/internal/FunctionValue.ts

@@ -0,0 +1,96 @@
+/** Carries native CSS function result domains through static declaration checking. @module */
+import type * as FunctionSyntax from './FunctionSyntax.js'
+import type * as Literal from './Literal.js'
+
+declare const result: unique symbol
+/** A native function expression with a declared CSS value syntax. */
+export type Reference<syntax extends string = '*'> =
+  `--${string}(${string})` & { readonly [result]: syntax }
+/** Detects a function result without expanding ordinary property grammars. */
+export type Is<value> = typeof result extends keyof value ? true : false
+/** Accepts results only when their value domain and repetition fit the destination. */
+export type Accepted<value, property, name> =
+  value extends Reference<infer syntax>
+    ? Repeated<FunctionSyntax.Unwrap<syntax>, name> extends false
+      ? never
+      : FunctionSyntax.Unwrap<syntax> extends '*'
+        ? value
+        : [Representative<FunctionSyntax.Unwrap<syntax>>] extends [never]
+          ? never
+          : Representative<FunctionSyntax.Unwrap<syntax>> extends property
+            ? value
+            : never
+    : never
+
+type Repetition<syntax> = syntax extends `${infer first}|${infer rest}`
+  ?
+      | Repetition<FunctionSyntax.Trim<first>>
+      | Repetition<FunctionSyntax.Trim<rest>>
+  : syntax extends `${string}+`
+    ? '+'
+    : syntax extends `${string}#`
+      ? '#'
+      : never
+
+// Finite shorthand domains may have broad textual tails; only explicit list metadata proves repetition.
+type Repeated<syntax, name> = [Repetition<syntax>] extends [never]
+  ? true
+  : name extends `--${string}`
+    ? true
+    : name extends keyof typeof Literal.rules
+      ? [Repetition<syntax>] extends ['#']
+        ? (typeof Literal.rules)[name] extends { list: true }
+          ? true
+          : false
+        : name extends 'transform'
+          ? syntax extends '<transform-function>+'
+            ? true
+            : false
+          : false
+      : false
+
+type Representative<syntax> = syntax extends `${infer first}|${infer rest}`
+  ?
+      | Representative<FunctionSyntax.Trim<first>>
+      | Representative<FunctionSyntax.Trim<rest>>
+  : syntax extends `${infer base}+`
+    ?
+        | Representative<base>
+        | `${Extract<Representative<base>, string | number>} ${string}`
+    : syntax extends `${infer base}#`
+      ?
+          | Representative<base>
+          | `${Extract<Representative<base>, string | number>},${string}`
+      : syntax extends '<color>'
+        ? '#000'
+        : syntax extends '<length>'
+          ? '1px'
+          : syntax extends '<length-percentage>'
+            ? '1px' | '1%'
+            : syntax extends '<number>'
+              ? number
+              : syntax extends '<integer>'
+                ? 1
+                : syntax extends '<percentage>'
+                  ? '1%'
+                  : syntax extends '<angle>'
+                    ? '1deg'
+                    : syntax extends '<time>'
+                      ? '1s'
+                      : syntax extends '<resolution>'
+                        ? '1dppx'
+                        : syntax extends '<image>'
+                          ? 'url(/image.svg)' | 'linear-gradient(red, blue)'
+                          : syntax extends '<url>'
+                            ? 'url(/image.svg)'
+                            : syntax extends '<string>'
+                              ? '"text"'
+                              : syntax extends '<custom-ident>'
+                                ? string
+                                : syntax extends
+                                      | '<transform-function>'
+                                      | '<transform-list>'
+                                  ? 'translateX(1px)'
+                                  : syntax extends `<${string}>`
+                                    ? never
+                                    : syntax

package/src/internal/Geometry.ts

@@ -0,0 +1,30 @@
+/** Describes CSS geometric value types. @module */
+/** Canonical CSS angle shapes. */
+export type Angle = `${number}${'deg' | 'grad' | 'rad' | 'turn'}`
+
+/** Transform functions available to typed authoring. */
+export type FunctionName =
+  | 'matrix'
+  | 'matrix3d'
+  | 'perspective'
+  | 'rotate'
+  | 'rotate3d'
+  | 'rotateX'
+  | 'rotateY'
+  | 'rotateZ'
+  | 'scale'
+  | 'scale3d'
+  | 'scaleX'
+  | 'scaleY'
+  | 'scaleZ'
+  | 'skew'
+  | 'skewX'
+  | 'skewY'
+  | 'translate'
+  | 'translate3d'
+  | 'translateX'
+  | 'translateY'
+  | 'translateZ'
+
+/** Geometric property domain. */
+export type Kind = 'ratio' | 'rotate' | 'scale' | 'transform' | 'translate'