zyzz 0.0.0 → 0.0.2

package/src/web/colorProfile.ts

@@ -0,0 +1,60 @@
+/** Declares a compiler-owned colorProfile stylesheet identity. @module */
+import type * as Context from './internal/Context.js'
+import type * as Lexical from '../internal/Lexical.js'
+import * as Identity from '../internal/Identity.js'
+import type * as RuleReference from '../internal/RuleReference.js'
+
+/** Emits static descriptors and returns a domain-specific CSS name. */
+export function colorProfile<
+  const options extends Omit<colorProfile.Options, 'renderingIntent'> & {
+    readonly renderingIntent?: string | undefined
+  },
+>(
+  options: options &
+    Record<Exclude<keyof options, keyof colorProfile.Options>, never> &
+    RuleReference.Checked<options> & {
+      readonly renderingIntent?: Intent<options['renderingIntent']>
+    },
+  context: Context.Options = {},
+): colorProfile.Reference {
+  void options
+  void context
+  return Identity.contribution(
+    'colorProfile',
+    context.id,
+  ) as colorProfile.Reference
+}
+/** Descriptor and identity contracts. */
+export declare namespace colorProfile {
+  /** Exact CSS descriptor input; declaration order is preserved. */
+  type Options = {
+    /** Ordered, comma-separated component names for relative colors. */
+    readonly components?: string | undefined
+    /** CSS renderingIntent descriptor. */
+    readonly renderingIntent?:
+      | 'absolute-colorimetric'
+      | 'relative-colorimetric'
+      | 'perceptual'
+      | 'saturation'
+      | undefined
+    /** CSS src descriptor. */
+    readonly src: string
+  }
+  /** Compiler-owned reference usable in the matching CSS domain. */
+  type Reference = RuleReference.Reference<'colorProfile'>
+}
+
+type Intent<value> = value extends string
+  ? Keyword<Lexical.Normalized<value>> extends Exclude<
+      colorProfile.Options['renderingIntent'],
+      undefined
+    >
+    ? value
+    : never
+  : undefined
+type Keyword<value extends string> =
+  value extends `${' ' | '\t' | '\n' | '\r' | '\f'}${infer rest}`
+    ? Keyword<rest>
+    : value extends `${infer rest}${' ' | '\t' | '\n' | '\r' | '\f'}`
+      ? Keyword<rest>
+      : Lexical.Fold<value>

package/src/web/counterStyle.ts

@@ -0,0 +1,82 @@
+/** Declares a compiler-owned counterStyle stylesheet identity. @module */
+import type * as Context from './internal/Context.js'
+import type * as Lexical from '../internal/Lexical.js'
+import * as Identity from '../internal/Identity.js'
+import type * as RuleReference from '../internal/RuleReference.js'
+
+/** Emits static descriptors and returns a domain-specific CSS name. */
+export function counterStyle<
+  const options extends Omit<counterStyle.Options, 'system'> & {
+    readonly system?: string | undefined
+  },
+>(
+  options: options &
+    Record<Exclude<keyof options, keyof counterStyle.Options>, never> &
+    RuleReference.Checked<options> & {
+      readonly system?: Checked<options['system']>
+    } & (System<options['system']> extends 'additive'
+      ? { readonly additiveSymbols: string }
+      : System<options['system']> extends `extends ${string}`
+        ? unknown
+        : { readonly symbols: string }),
+  context: Context.Options = {},
+): counterStyle.Reference {
+  void options
+  void context
+  return Identity.contribution(
+    'counterStyle',
+    context.id,
+  ) as counterStyle.Reference
+}
+/** Descriptor and identity contracts. */
+export declare namespace counterStyle {
+  /** Exact CSS descriptor input; declaration order is preserved. */
+  type Options = {
+    /** CSS additiveSymbols descriptor. */
+    readonly additiveSymbols?: string | undefined
+    /** CSS fallback descriptor. */
+    readonly fallback?: string | undefined
+    /** CSS negative descriptor. */
+    readonly negative?: string | undefined
+    /** CSS pad descriptor. */
+    readonly pad?: string | undefined
+    /** CSS prefix descriptor. */
+    readonly prefix?: string | undefined
+    /** CSS range descriptor. */
+    readonly range?: string | undefined
+    /** CSS speakAs descriptor. */
+    readonly speakAs?: string | undefined
+    /** CSS suffix descriptor. */
+    readonly suffix?: string | undefined
+    /** CSS symbols descriptor. */
+    readonly symbols?: string | undefined
+    /** CSS system descriptor. */
+    readonly system?:
+      | 'cyclic'
+      | 'numeric'
+      | 'alphabetic'
+      | 'symbolic'
+      | 'additive'
+      | 'fixed'
+      | `fixed ${bigint}`
+      | `extends ${string}`
+      | undefined
+  }
+  /** Compiler-owned reference usable in the matching CSS domain. */
+  type Reference = RuleReference.Reference<'counterStyle'>
+}
+
+type System<value> = value extends string
+  ? Trim<Lexical.Fold<Lexical.Normalized<value>>>
+  : undefined
+type Checked<value> = value extends string
+  ? System<value> extends counterStyle.Options['system']
+    ? value
+    : never
+  : undefined
+type Space = ' ' | '\t' | '\n' | '\r' | '\f'
+type Trim<value extends string> = value extends `${Space}${infer rest}`
+  ? Trim<rest>
+  : value extends `${infer rest}${Space}`
+    ? Trim<rest>
+    : value

package/src/web/cssFunction.ts

@@ -0,0 +1,181 @@
+/** Declares a native CSS custom function without evaluating its body in JavaScript. @module */
+import type * as Context from './internal/Context.js'
+import type * as FunctionSyntax from '../internal/FunctionSyntax.js'
+import type * as FunctionValue from '../internal/FunctionValue.js'
+import type * as Literal from '../internal/Literal.js'
+import * as Identity from '../internal/Identity.js'
+import type * as Numeric from '../internal/Numeric.js'
+/** Emits a CSS function and returns a callable that formats its fixed CSS expression. */
+export function cssFunction<const options extends cssFunction.Options>(
+  options: options &
+    Record<Exclude<keyof options, keyof cssFunction.Options>, never> & {
+      readonly body: Checked<options['body']>
+      readonly parameters: {
+        [index in keyof options['parameters']]: options['parameters'][index] extends {
+          syntax: infer syntax extends string
+        }
+          ? options['parameters'][index] & {
+              readonly syntax: FunctionSyntax.Checked<syntax>
+            }
+          : options['parameters'][index]
+      }
+    } & {
+      readonly returns?: options extends {
+        returns: infer syntax extends string
+      }
+        ? FunctionSyntax.Checked<syntax>
+        : undefined
+    },
+  context: Context.Options = {},
+): cssFunction.Reference<
+  options['parameters'],
+  options extends { returns: infer syntax extends cssFunction.Syntax }
+    ? syntax
+    : '*'
+> {
+  void options
+  void context
+  const name = Identity.contribution('cssFunction', context.id)
+  return ((...args: readonly (string | number)[]) =>
+    name +
+    '(' +
+    args
+      .map((value) =>
+        typeof value === 'string' &&
+        value.includes(',') &&
+        !value.trimStart().startsWith('{')
+          ? '{' + value + '}'
+          : value,
+      )
+      .join(',') +
+    ')') as cssFunction.Reference<
+    options['parameters'],
+    options extends { returns: infer syntax extends cssFunction.Syntax }
+      ? syntax
+      : '*'
+  >
+}
+/** CSS function parameter and result contracts. */
+export declare namespace cssFunction {
+  /** CSS value syntax accepted by a parameter or returned value. */
+  type Syntax = string
+  /** One ordered parameter with an optional default. */
+  type Parameter = {
+    /** Parameter custom-property name. */
+    readonly name: `--${string}`
+    /** CSS parameter syntax; omitted accepts arbitrary CSS tokens. */
+    readonly syntax?: Syntax | undefined
+    /** Static CSS default, evaluated by the browser. */
+    readonly default?: string | number | undefined
+  }
+  /** Static CSS function definition. */
+  type Options = {
+    /** Local custom properties, result declarations, and conditional groups. */
+    readonly body: Body
+    /** Ordered parameter declarations. */
+    readonly parameters: readonly Parameter[]
+    /** CSS return syntax; omitted accepts arbitrary CSS tokens. */
+    readonly returns?: Syntax | undefined
+  }
+  /** Exact allowed declarations and nested conditions. */
+  type Body = {
+    /** Function result, or omission for a guaranteed-invalid result. */
+    readonly result?: string | number | undefined
+    /** Function-local custom-property declarations. */
+    readonly [local: `--${string}`]: string | number | undefined
+    /** Conditional function result or local assignments. */
+    readonly [condition:
+      | `@media ${string}`
+      | `@supports ${string}`
+      | `@container ${string}`]: Body
+  }
+  /** Callable CSS expression; JavaScript never evaluates the CSS function body. */
+  type Reference<
+    parameters extends readonly Parameter[] = readonly Parameter[],
+    syntax extends Syntax = '*',
+  > = <const args extends Arguments<parameters>>(
+    ...args: args & {
+      [index in keyof args]: index extends keyof parameters
+        ? parameters[index] extends { syntax: infer syntax extends string }
+          ? FunctionSyntax.IntegerOnly<syntax> extends true
+            ? args[index] extends number
+              ? Numeric.Checked<args[index], true>
+              : args[index]
+            : args[index]
+          : args[index]
+        : args[index]
+    }
+  ) => FunctionValue.Reference<syntax>
+  /** Ordered arguments with optional trailing defaults. */
+  type Arguments<parameters extends readonly Parameter[]> =
+    number extends parameters['length']
+      ? readonly (string | number)[]
+      : parameters extends readonly [
+            infer first extends Parameter,
+            ...infer rest extends readonly Parameter[],
+          ]
+        ? first extends { default: string | number }
+          ? readonly [Input<first>?, ...Arguments<rest>]
+          : readonly [Input<first>, ...Arguments<rest>]
+        : readonly []
+  /** Scalar domain implied by an authored parameter syntax. */
+  type Input<parameter extends Parameter> =
+    | (parameter extends {
+        syntax: infer syntax extends string
+      }
+        ? InputSyntax<FunctionSyntax.Unwrap<syntax>>
+        : string | number)
+    | (parameter extends { syntax: infer syntax extends string }
+        ? FunctionValue.Reference<syntax>
+        : FunctionValue.Reference)
+}
+
+type Checked<body> = {
+  [key in keyof body]: key extends symbol
+    ? Checked<body[key]>
+    : key extends 'result' | `--${string}`
+      ? body[key]
+      : key extends
+            | `@media ${string}`
+            | `@supports ${string}`
+            | `@container ${string}`
+        ? Checked<body[key]>
+        : never
+}
+
+type InputSyntax<syntax extends string> =
+  syntax extends `${infer first}|${infer rest}`
+    ?
+        | InputSyntax<FunctionSyntax.Trim<first>>
+        | InputSyntax<FunctionSyntax.Trim<rest>>
+    : syntax extends '*'
+      ? string | number
+      : syntax extends `${infer base}+` | `${infer base}#`
+        ? string | InputSyntax<base>
+        : syntax extends '<number>' | '<integer>'
+          ? number
+          : syntax extends '<percentage>'
+            ? `${number}%`
+            : syntax extends '<length>'
+              ? Exclude<Literal.Length, `${number}%`>
+              : syntax extends '<length-percentage>'
+                ? Literal.Length
+                : syntax extends '<angle>'
+                  ? `${number}${'deg' | 'grad' | 'rad' | 'turn'}`
+                  : syntax extends '<time>'
+                    ? Literal.Time
+                    : syntax extends '<color>'
+                      ? Literal.Color
+                      : syntax extends '<resolution>'
+                        ? `${number}${'dpi' | 'dpcm' | 'dppx' | 'x'}`
+                        : syntax extends '<url>'
+                          ? `url(${string})`
+                          : syntax extends '<string>'
+                            ? `"${string}"` | `'${string}'`
+                            : syntax extends
+                                  | '<image>'
+                                  | '<custom-ident>'
+                                  | '<transform-function>'
+                                  | '<transform-list>'
+                              ? string
+                              : syntax

package/src/web/customMedia.ts

@@ -0,0 +1,16 @@
+/** Declares a compiler-owned custom media query. @module */
+import type * as Condition from '../internal/Condition.js'
+import * as Identity from '../internal/Identity.js'
+/** Emits a query definition and returns its opaque grouping key. */
+export function customMedia(
+  query: string | boolean,
+  options: { readonly id?: string | undefined } = {},
+): customMedia.Reference {
+  void query
+  return `@media (${Identity.contribution('customMedia', options.id)})` as unknown as customMedia.Reference
+}
+/** Custom query key consumed directly as a computed grouping key. */
+export declare namespace customMedia {
+  /** A generated media condition with a fixed query identity. */
+  type Reference = Condition.Query
+}

package/src/web/fontFace.ts

@@ -0,0 +1,41 @@
+/** Declares module-level font-face descriptors without loading fonts. @module */
+import type * as Context from './internal/Context.js'
+
+/** Compiles literal font-face descriptors into the initial stylesheet. */
+export function fontFace<const options extends fontFace.Options>(
+  options: options &
+    Record<Exclude<keyof options, keyof fontFace.Options>, never>,
+  context: Context.Options = {},
+): void {
+  void context
+  void options
+  return
+}
+
+/** Supported font-face descriptor contracts. */
+export declare namespace fontFace {
+  /** Source and family plus standard scalar font selection descriptors. */
+  type Options = {
+    /** OpenType feature settings for the face. */
+    readonly fontFeatureSettings?: string | undefined
+    /** Variable font axis defaults. */
+    readonly fontVariationSettings?: string | undefined
+    readonly fontFamily: string
+    readonly src: string
+    readonly fontDisplay?:
+      | 'auto'
+      | 'block'
+      | 'swap'
+      | 'fallback'
+      | 'optional'
+      | undefined
+    readonly fontStyle?: string | undefined
+    readonly fontWeight?: string | number | undefined
+    readonly fontStretch?: string | undefined
+    readonly unicodeRange?: string | undefined
+    readonly sizeAdjust?: `${number}%` | undefined
+    readonly ascentOverride?: 'normal' | `${number}%` | undefined
+    readonly descentOverride?: 'normal' | `${number}%` | undefined
+    readonly lineGapOverride?: 'normal' | `${number}%` | undefined
+  }
+}

package/src/web/fontFeatureValues.ts

@@ -0,0 +1,79 @@
+/** Declares named OpenType feature sets for a font family list. @module */
+import type * as Context from './internal/Context.js'
+import type * as Lexical from '../internal/Lexical.js'
+
+/** Emits eager font feature aliases in authored block and declaration order. */
+export function fontFeatureValues<
+  const options extends Omit<fontFeatureValues.Options, 'fontDisplay'> & {
+    readonly fontDisplay?: string | undefined
+  },
+>(
+  options: options &
+    Record<Exclude<keyof options, keyof fontFeatureValues.Options>, never> & {
+      readonly fontDisplay?: Checked<
+        options['fontDisplay'],
+        Exclude<fontFeatureValues.Options['fontDisplay'], undefined>
+      >
+    } & {
+      readonly features: Record<
+        Exclude<
+          keyof options['features'],
+          keyof fontFeatureValues.Options['features']
+        >,
+        never
+      >
+    },
+  context: Context.Options = {},
+): void {
+  void options
+  void context
+  return
+}
+/** Family, display, and nested feature alias contracts. */
+export declare namespace fontFeatureValues {
+  /** Static font family list and named OpenType feature blocks. */
+  type Options = {
+    /** CSS font family list, or individually quoted family names. */
+    readonly families: string | readonly [string, ...string[]]
+    /** Named feature groups. */
+    readonly features: {
+      /** Annotation feature indices. */
+      readonly '@annotation'?: Readonly<Record<string, number>> | undefined
+      /** Character variant index and optional variation selector. */
+      readonly '@character-variant'?:
+        | Readonly<Record<string, number | readonly [number, number]>>
+        | undefined
+      /** Ornament feature indices. */
+      readonly '@ornaments'?: Readonly<Record<string, number>> | undefined
+      /** Ordered stylistic-set indices. */
+      readonly '@styleset'?:
+        | Readonly<Record<string, number | readonly [number, ...number[]]>>
+        | undefined
+      /** Stylistic alternate indices. */
+      readonly '@stylistic'?: Readonly<Record<string, number>> | undefined
+      /** Swash feature indices. */
+      readonly '@swash'?: Readonly<Record<string, number>> | undefined
+    }
+    /** Font display policy for the family aliases. */
+    readonly fontDisplay?:
+      | 'auto'
+      | 'block'
+      | 'fallback'
+      | 'optional'
+      | 'swap'
+      | undefined
+  }
+}
+
+type Keyword<value extends string> =
+  value extends `${' ' | '\t' | '\n' | '\r' | '\f'}${infer rest}`
+    ? Keyword<rest>
+    : value extends `${infer rest}${' ' | '\t' | '\n' | '\r' | '\f'}`
+      ? Keyword<rest>
+      : Lexical.Fold<value>
+
+type Checked<value, domain> = value extends string
+  ? Keyword<Lexical.Normalized<value>> extends domain
+    ? value
+    : never
+  : undefined

package/src/web/fontPaletteValues.ts

@@ -0,0 +1,42 @@
+/** Declares a compiler-owned fontPaletteValues stylesheet identity. @module */
+import * as Identity from '../internal/Identity.js'
+import type * as RuleReference from '../internal/RuleReference.js'
+import type * as Context from './internal/Context.js'
+
+/** Emits static descriptors and returns a domain-specific CSS name. */
+export function fontPaletteValues<
+  const options extends fontPaletteValues.Options,
+>(
+  options: options &
+    Record<Exclude<keyof options, keyof fontPaletteValues.Options>, never> &
+    RuleReference.Checked<options> &
+    (options extends { basePalette: infer value extends number }
+      ? `${value}` extends `${bigint}`
+        ? `${value}` extends `-${string}`
+          ? never
+          : unknown
+        : never
+      : unknown),
+  context: Context.Options = {},
+): fontPaletteValues.Reference {
+  void options
+  void context
+  return Identity.contribution(
+    'fontPaletteValues',
+    context.id,
+  ) as fontPaletteValues.Reference
+}
+/** Descriptor and identity contracts. */
+export declare namespace fontPaletteValues {
+  /** Exact CSS descriptor input; declaration order is preserved. */
+  type Options = {
+    /** CSS basePalette descriptor. */
+    readonly basePalette?: 'light' | 'dark' | number | undefined
+    /** CSS fontFamily descriptor. */
+    readonly fontFamily: string
+    /** CSS overrideColors descriptor. */
+    readonly overrideColors?: string | undefined
+  }
+  /** Compiler-owned reference usable in the matching CSS domain. */
+  type Reference = RuleReference.Reference<'fontPaletteValues'>
+}

package/src/web/global.ts

@@ -0,0 +1,39 @@
+/** Declares eager module-level global stylesheet effects. @module */
+import type * as Condition from '../internal/Condition.js'
+import type * as Literal from '../internal/Literal.js'
+import type * as Style from '../Style.js'
+
+/** Compiles module-level selector declarations; never registers runtime CSS. */
+export function global<const styles extends Record<string, unknown>>(
+  styles: styles & NoInfer<global.Body<styles>>,
+): void {
+  void styles
+  return
+}
+
+/** Global selector and grouping contracts. */
+export declare namespace global {
+  /** Selectors contain exact declarations; at-rules contain further selectors. */
+  type Body<styles> = {
+    [key in keyof styles]: key extends Condition.Query
+      ? Body<styles[key]>
+      : key extends `@${string}`
+        ? key extends Extract<Condition.Raw, `@${string}`>
+          ? Body<styles[key]>
+          : never
+        : Style.Accepted<styles[key]> & WithoutRelationships<styles[key]>
+  }
+}
+
+/** Global declarations do not accept marker-relative conditions. */
+type WithoutRelationships<value> = value extends readonly unknown[]
+  ? unknown
+  : value extends object
+    ? {
+        [key in keyof value]: key extends symbol
+          ? never
+          : key extends keyof Literal.Properties
+            ? unknown
+            : WithoutRelationships<value[key]>
+      }
+    : unknown

package/src/web/importCss.ts

@@ -0,0 +1,23 @@
+/** Declares ordered external stylesheet imports. @module */
+/** Emits a stylesheet import before namespaces and ordinary rules. */
+export function importCss<const options extends importCss.Options>(
+  options: options &
+    Record<Exclude<keyof options, keyof importCss.Options>, never>,
+): void {
+  void options
+  return
+}
+/** Import conditions and layer placement. */
+export declare namespace importCss {
+  /** Static import URL and optional conditions. */
+  type Options = {
+    /** Named layer, or true for an anonymous layer. */
+    readonly layer?: string | true | undefined
+    /** Media query list. */
+    readonly media?: string | undefined
+    /** Supports condition or declaration, without the outer supports(). */
+    readonly supports?: string | undefined
+    /** Stylesheet URL resolved relative to its source owner. */
+    readonly url: string
+  }
+}

package/src/web/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Exposes the pure web CSS compiler independently of source and file adapters.
+ * @module
+ */
+
+export { colorProfile } from './colorProfile.js'
+export { counterStyle } from './counterStyle.js'
+export * as Css from './Css.js'
+export { cssFunction } from './cssFunction.js'
+export { customMedia } from './customMedia.js'
+export { fontFace } from './fontFace.js'
+export { fontFeatureValues } from './fontFeatureValues.js'
+export { fontPaletteValues } from './fontPaletteValues.js'
+export { global } from './global.js'
+export { importCss } from './importCss.js'
+export { keyframes } from './keyframes.js'
+export { layers } from './layers.js'
+export { namespace } from './namespace.js'
+export { page } from './page.js'
+export { positionTry } from './positionTry.js'
+export { property } from './property.js'
+export { viewTransition } from './viewTransition.js'

package/src/web/internal/Block.ts

@@ -0,0 +1,29 @@
+/** Represents ordered descriptor and declaration blocks independently of parsing. @module */
+import type * as Style from '../../Style.js'
+/** One authored descriptor, element declaration fragment, or nested descriptor block. */
+export type Entry =
+  | {
+      readonly kind: 'descriptor'
+      readonly name: string
+      readonly value: string | number
+    }
+  | { readonly kind: 'style'; readonly style: Style.NamedStyle }
+  | {
+      readonly kind: 'block'
+      readonly header: string
+      readonly entries: readonly Entry[]
+    }
+/** Renders a structured block while delegating ordinary property serialization to the CSS compiler. */
+export function render(
+  entries: readonly Entry[],
+  style: (value: Style.NamedStyle) => string,
+): string {
+  return entries
+    .map((entry) => {
+      if (entry.kind === 'style') return style(entry.style)
+      if (entry.kind === 'block')
+        return `${entry.header}{${render(entry.entries, style)}}`
+      return `${entry.name}:${entry.value};`
+    })
+    .join('')
+}