zyzz 0.0.0 → 0.0.2

package/src/styleFunction.ts

@@ -0,0 +1,138 @@
+/**
+ * Declares the token-free authoring boundary consumed by source transforms.
+ * @module
+ */
+import * as Authoring from './internal/Authoring.js'
+import type * as Binding from './internal/Binding.js'
+import type * as Literal from './internal/Literal.js'
+import type * as Style from './Style.js'
+
+/** Restricts callback hints to inferred declarations instead of expanding every property grammar. */
+type CompletionProperties<styles = Record<string, unknown>> = {
+  readonly [property in keyof typeof Literal.rules & keyof styles]?:
+    | Literal.Properties[property]
+    | (string & {})
+    | number
+    | object
+}
+
+type Keys<value> = value extends unknown ? keyof value : never
+
+type VariableOptions<input> = input extends {
+  readonly variables: infer variables
+}
+  ? {
+      readonly variables: {
+        readonly [key in keyof variables]: string extends key
+          ? variables[key]
+          : key extends `--${string}`
+            ? variables[key]
+            : never
+      }
+    }
+  : unknown
+
+/**
+ * Declares literal styles for source extraction. Requires a compile-time transform.
+ * @param styles - Token-free literal CSS properties. Omit for an empty definition.
+ * @returns A callable style definition after source rewriting.
+ * @throws {Error} When a definition needs an explicit identity and none is supplied.
+ */
+export function style(): style.ReturnType
+export function style<
+  const values extends Record<string, string | number>,
+  const styles extends Record<string, unknown>,
+  const callback extends (...args: never[]) => unknown,
+>(
+  styles: callback &
+    ((
+      values: values,
+    ) => styles &
+      NoInfer<Style.Accepted<styles, {}, true> & Binding.Checked<styles>>) &
+    CompletionProperties<NoInfer<styles>>,
+  // Exclude invalid callbacks by arity so they cannot mask object-property diagnostics.
+  ...options: Parameters<callback> extends [Record<string, string | number>]
+    ? values extends Binding.Inputs<values>
+      ? [options?: style.DefinitionOptions]
+      : [invalid: never, unavailable: never]
+    : [invalid: never, unavailable: never]
+): style.Dynamic<values>
+export function style<const styles extends Record<string, unknown>>(
+  styles: styles &
+    NoInfer<Style.Accepted<styles, {}, true>> &
+    CompletionProperties,
+  options?: style.DefinitionOptions,
+): style.ReturnType
+export function style(
+  styles?: unknown,
+  options: style.DefinitionOptions = {},
+): style.ReturnType {
+  return Authoring.create(styles, options)
+}
+
+/** Compile-time brand identifying callable style definitions. */
+declare const identity: unique symbol
+type Reference = { readonly [identity]: true }
+
+/** Contracts for the literal authoring boundary. */
+export declare namespace style {
+  /** Stable identity for selectors and definitions that cannot be content-addressed. */
+  type DefinitionOptions = { readonly id?: string | undefined }
+  /** Callable compiled bindings with required scalar inputs and styling overrides. */
+  type Dynamic<values, output extends Output = 'react'> = Reference &
+    (<const input extends values & Options>(
+      input: input &
+        VariableOptions<input> &
+        Record<Exclude<keyof input, keyof values | keyof Options>, never>,
+    ) => Props<output>)
+
+  /** Failure from executing source without a transform. */
+  type ErrorType = Error
+
+  /** Styling overrides consumed by a transformed definition. */
+  type Options = {
+    /** External class names appended to the generated classes. */
+    readonly className?: string | undefined
+    /** Literal inline styling overrides. */
+    readonly style?: Literal.Properties | undefined
+    /** Inline custom-property assignments, merged before explicit style overrides. */
+    readonly variables?:
+      | Readonly<Record<`--${string}`, string | number | undefined>>
+      | undefined
+  }
+
+  /** Props produced by a transformed web definition. */
+  type Output = 'html' | 'react'
+
+  /** Renderer-native props selected by configuration. */
+  type Props<output extends Output = 'react'> = output extends 'html'
+    ? { readonly class: string; readonly style?: string | undefined }
+    : {
+        /** Compiled and supplied class names. */
+        readonly className: string
+        /** Supplied inline styling overrides when present. */
+        readonly style?:
+          | Readonly<Record<string, string | number | undefined>>
+          | undefined
+      }
+
+  /** Callable definition; source rewriting supplies its implementation. */
+  type ReturnType<output extends Output = 'react'> = Reference &
+    (<const options extends Options = Options>(
+      options?: options &
+        VariableOptions<options> &
+        Record<Exclude<Keys<options>, keyof Options>, never>,
+    ) => Props<output>)
+}
+
+/** Executed authoring source has not been rewritten. */
+export class MissingTransformError extends Error {
+  /** Explains the missing transform without generating runtime CSS. */
+  constructor() {
+    super(
+      'style requires a compile-time transform. Source extraction alone does not rewrite calls; do not execute untransformed authoring source.',
+    )
+  }
+  /** Stable namespaced diagnostic name. */
+  override name = 'style.MissingTransformError'
+}

package/src/themes/LICENSE.tailwind

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Tailwind Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/variable.ts

@@ -0,0 +1,105 @@
+/** Declares optionally typed CSS variables with static references and inline assignments. @module */
+import type * as Binding from './internal/Binding.js'
+import type * as Literal from './internal/Literal.js'
+import * as Identity from './internal/Identity.js'
+import * as Variable from './runtime/Variable.js'
+
+/** Declares a custom property. Omitting the domain accepts any string or number; typed options register CSS @property. */
+export function variable(options: {
+  readonly id: string
+}): variable.Reference<'*'>
+export function variable<kind extends Binding.Kind>(
+  kind: kind,
+  options: { readonly id: string },
+): variable.Reference<kind>
+export function variable(): variable.Reference<'*'>
+export function variable<const kind extends Binding.Kind>(
+  kind: kind,
+): variable.Reference<kind>
+export function variable<
+  const kind extends Binding.Kind,
+  const options extends variable.Options<kind>,
+>(
+  kind: kind,
+  options: options &
+    Record<Exclude<keyof options, keyof variable.Options<kind>>, never> & {
+      readonly initialValue: Literal.Checked<options['initialValue']> &
+        Independent<options['initialValue']> &
+        (kind extends 'length'
+          ? options['initialValue'] extends `-${string}`
+            ? never
+            : unknown
+          : unknown)
+    },
+): variable.Reference<kind>
+export function variable(
+  kind?: Binding.Kind | { readonly id: string },
+  options?: { readonly id?: string | undefined },
+): unknown {
+  const id = typeof kind === 'object' ? kind.id : options?.id
+  return Variable.create({
+    name: `--z-v${Identity.requireId(id, 'variable')}`,
+    type: typeof kind === 'string' ? kind : '*',
+    variable: true,
+  })
+}
+
+/** Types shared by variable declarations and assignments. */
+export declare namespace variable {
+  /** Supported scalar domains. */
+  type Kind = Binding.Kind
+  /** Optional registration uses the variable's scalar domain as its CSS syntax. */
+  type Options<kind extends Binding.Kind = Binding.Kind> = {
+    /** Stable identity required without source transformation. */
+    readonly id?: string | undefined
+    /** Whether the custom property inherits through the DOM. */
+    readonly inherits: boolean
+    /** Computationally independent initial value emitted in @property. */
+    readonly initialValue: Initial<kind>
+    /** Matching CSS syntax; inferred from the domain when omitted. */
+    readonly syntax?: Syntax<kind> | undefined
+  }
+  /** Opaque computed key and declaration reference; the untyped domain accepts any scalar. */
+  type Reference<kind extends Binding.Domain = Binding.Domain> = string &
+    Binding.Reference<kind> & {
+      /** Produces one inline custom-property assignment without runtime value validation. */
+      readonly set: <const value extends Binding.Value<kind>>(
+        value: value & (kind extends '*' ? unknown : Literal.Checked<value>),
+      ) => Readonly<Record<`--${string}`, value>>
+    }
+}
+
+/** Computationally independent initial values for registered properties. */
+type Initial<kind extends Binding.Kind> = kind extends 'length' | 'signedLength'
+  ? 0 | '0' | `${number}${'px' | 'in' | 'cm' | 'mm' | 'q' | 'pt' | 'pc'}`
+  : kind extends 'color'
+    ? Exclude<
+        Binding.Value<kind>,
+        'currentColor' | 'currentcolor' | `light-dark(${string})`
+      >
+    : Binding.Value<kind>
+
+type Independent<value> = value extends string
+  ? Lowercase<value> extends `${string}${'currentcolor' | 'var(' | 'env(' | 'light-dark('}${string}`
+    ? never
+    : value
+  : value
+
+/** CSS syntax corresponding to a supported scalar domain. */
+type Syntax<kind extends Binding.Kind> = kind extends 'signedLength'
+  ? '<length>'
+  : kind extends 'signedPercentage'
+    ? '<percentage>'
+    : `<${kind}>`
+
+/** Reports execution of authoring source without its compile-time transform. */
+export class MissingTransformError extends Error {
+  /** Explains the missing transform. */
+  constructor() {
+    super(
+      'variable requires a compile-time transform; do not execute untransformed authoring source.',
+    )
+  }
+  /** Stable namespaced diagnostic name. */
+  override name = 'variable.MissingTransformError'
+}

package/src/variants.ts

@@ -0,0 +1,218 @@
+/** Declares single-element recipes for ahead-of-time compilation. @module */
+import * as Authoring from './internal/Authoring.js'
+import type { style } from './styleFunction.js'
+import type * as Config from './Config.js'
+import type * as Binding from './internal/Binding.js'
+import type * as Condition from './internal/Condition.js'
+import type * as Shorthands from './internal/Shorthands.js'
+import type * as Style from './Style.js'
+import type * as Theme from './Theme.js'
+
+type Axes<definition> = definition extends { readonly variants: infer axes }
+  ? axes
+  : {}
+type Conditions<definition> = definition extends {
+  readonly conditions: infer conditions
+}
+  ? conditions
+  : {}
+type ChoiceName<choices> = keyof choices extends infer key
+  ? key extends 'true' | 'false'
+    ? key extends 'true'
+      ? true
+      : false
+    : key extends string
+      ? key
+      : never
+  : never
+type DynamicKeys<choices> = {
+  [key in keyof choices]: choices[key] extends (...args: never[]) => unknown
+    ? key
+    : never
+}[keyof choices]
+type Choice<choices> =
+  | ChoiceName<Omit<choices, DynamicKeys<choices>>>
+  | {
+      [key in DynamicKeys<choices>]: choices[key] extends (
+        values: infer values,
+      ) => unknown
+        ? { readonly [name in key]: values } & {
+            readonly [name in Exclude<keyof choices, key>]?: never
+          }
+        : never
+    }[DynamicKeys<choices>]
+type CheckedChoice<
+  style,
+  tokens extends Theme.Tokens,
+  layers extends string,
+  mappings extends Shorthands.Map,
+> = style extends (values: infer values) => infer body
+  ? (
+      values: values,
+    ) => CheckedStyles<body, tokens, layers, mappings> &
+      Binding.Checked<body> &
+      (string extends keyof values
+        ? never
+        : values extends Record<string, string | number> &
+              Binding.Inputs<values>
+          ? unknown
+          : never)
+  : CheckedStyles<style, tokens, layers, mappings>
+type Keys<value> = value extends unknown ? keyof value : never
+type Selections<axes> = {
+  readonly [axis in keyof axes]?: Choice<axes[axis]> | null | undefined
+}
+type Input<definition> = Selections<Axes<definition>> &
+  style.Options &
+  (keyof Conditions<definition> extends never
+    ? {}
+    : {
+        readonly conditions?:
+          | {
+              readonly [name in keyof Conditions<definition>]?:
+                | Selections<Axes<definition>>
+                | undefined
+            }
+          | undefined
+      })
+type CheckedStyles<
+  style,
+  tokens extends Theme.Tokens,
+  layers extends string,
+  mappings extends Shorthands.Map,
+> =
+  style extends Record<string, unknown>
+    ? [keyof mappings | layers] extends [never]
+      ? Style.Accepted<style, tokens, keyof tokens extends never ? true : false>
+      : Config.Body<style, tokens, layers, mappings>
+    : never
+type Checked<
+  definition,
+  tokens extends Theme.Tokens,
+  layers extends string,
+  mappings extends Shorthands.Map,
+> = {
+  readonly [key in keyof definition]: key extends 'base'
+    ? CheckedStyles<definition[key], tokens, layers, mappings>
+    : key extends 'variants'
+      ? {
+          readonly [axis in keyof definition[key]]: axis extends
+            | keyof style.Options
+            | 'class'
+            | 'conditions'
+            | 'key'
+            | 'ref'
+            | `zyzz-condition-${string}`
+            ? never
+            : {
+                readonly [choice in keyof definition[key][axis]]: CheckedChoice<
+                  definition[key][axis][choice],
+                  tokens,
+                  layers,
+                  mappings
+                >
+              }
+        }
+      : key extends 'conditions'
+        ? {
+            readonly [name in keyof definition[key]]: Extract<
+              Condition.Keys<tokens>,
+              `@${'media' | 'supports'}${' ' | '(' | '/' | '\t' | '\n' | '\r' | '\f'}${string}`
+            >
+          }
+        : key extends 'defaultVariants'
+          ? Selections<Axes<definition>> &
+              Record<
+                Exclude<keyof definition[key], keyof Axes<definition>>,
+                never
+              >
+          : key extends 'compoundVariants'
+            ? readonly {
+                readonly when: {
+                  readonly [axis in keyof Axes<definition>]?:
+                    | ChoiceName<Axes<definition>[axis]>
+                    | readonly ChoiceName<Axes<definition>[axis]>[]
+                }
+                readonly style: Record<string, unknown>
+              }[] & {
+                readonly [index in keyof definition[key]]: definition[key][index] extends {
+                  readonly style: infer style
+                  readonly when: infer when
+                }
+                  ? {
+                      readonly style: CheckedStyles<
+                        style,
+                        tokens,
+                        layers,
+                        mappings
+                      >
+                      readonly when: Record<
+                        Exclude<keyof when, keyof Axes<definition>>,
+                        never
+                      >
+                    } & Record<
+                      Exclude<keyof definition[key][index], 'style' | 'when'>,
+                      never
+                    >
+                  : definition[key][index]
+              }
+            : never
+}
+
+/**
+ * Declares base styles, variant axes, defaults, and ordered compounds.
+ * @param definition - Static recipe for one element.
+ * @returns A callable selecting precompiled styles and returning one props object.
+ * @throws {Error} When uncompiled authoring omits an explicit identity.
+ */
+export function variants<const definition extends Record<string, unknown>>(
+  definition: definition & NoInfer<Checked<definition, {}, never, {}>>,
+  options: style.DefinitionOptions = {},
+): variants.ReturnType<definition> {
+  return Authoring.variants(
+    definition,
+    options,
+  ) as variants.ReturnType<definition>
+}
+
+/** Inferred recipe authoring and selection contracts. */
+export declare namespace variants {
+  /** Theme-bound authoring with the same inferred selection contract. */
+  type Bound<
+    tokens extends Theme.Tokens,
+    output extends style.Output = 'react',
+    layers extends string = never,
+    mappings extends Shorthands.Map = {},
+  > = <const definition extends Record<string, unknown>>(
+    definition: definition &
+      NoInfer<Checked<definition, tokens, layers, mappings>>,
+    options?: style.DefinitionOptions,
+  ) => ReturnType<definition, output>
+
+  /** Callable selection; omitted values use defaults and null suppresses them. */
+  type ReturnType<definition, output extends style.Output = 'react'> = <
+    const input extends Input<definition> = Input<definition>,
+  >(
+    input?: input &
+      Record<Exclude<Keys<input>, keyof Input<definition>>, never>,
+  ) => style.Props<output> & {
+    readonly [axis in keyof Axes<definition> as `data-${axis & string}`]?:
+      | string
+      | undefined
+  }
+
+  /** Missing source transformation diagnostic. */
+  type ErrorType = Error
+}
+
+/** Executed recipe authoring has not been rewritten. */
+export class MissingTransformError extends Error {
+  /** Explains the required recipe transformation. */
+  constructor() {
+    super(
+      'variants requires a compile-time transform. Do not execute untransformed recipe authoring.',
+    )
+  }
+  /** Stable recipe diagnostic name. */
+  override name = 'variants.MissingTransformError'
+}