zyzz 0.0.0 → 0.0.3

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Exposes token-free authoring, ordered style definitions, and theme contracts.
+ * @module
+ */
+/** Explicit theme and layer authoring contracts. */
+export * as Config from './Config.js'
+/** Token-free literal authoring; requires a compile-time source transform. */
+export { style } from './styleFunction.js'
+/** Ordered composition of applied styling props. */
+export { cx } from './cx.js'
+/** Inferred component inputs from callable style definitions. */
+export type * as Props from './Props.js'
+/** Typed literal style definitions and validation diagnostics. */
+export * as Style from './Style.js'
+/** Typed theme contracts and compatible token overrides. */
+export * as Theme from './Theme.js'
+/** Typed CSS variable declarations and inline assignments. */
+export { variable } from './variable.js'
+/** Single-element finite recipes compiled ahead of time. */
+export { variants } from './variants.js'

package/src/internal/Authoring.ts

@@ -0,0 +1,199 @@
+/** Binds authored style data to extracted stylesheets without inserting CSS. @module */
+import type { style } from '../styleFunction.js'
+import * as Html from '../runtime/CompositionHtml.js'
+import * as Identity from './Identity.js'
+import * as Props from '../runtime/Props.js'
+import * as Style from '../Style.js'
+import type * as Theme from '../Theme.js'
+
+/** Private ownership used by uncompiled composition; never spread onto DOM props. */
+export const metadata = Symbol.for('zyzz.authoring')
+
+/** Identity and replaceable attribute/slot ownership for an applied definition. */
+export type Owner = {
+  readonly name: string
+  readonly attributes: readonly string[]
+  readonly slots: readonly string[]
+}
+
+/** Attaches authoring ownership without adding enumerable props. */
+export function bind<value extends object>(
+  value: value,
+  owners: readonly Owner[],
+): value {
+  Object.defineProperty(value, metadata, { value: owners })
+  return value
+}
+
+/** Authoring identity, output convention, and optional token context. */
+export type Options = {
+  readonly id?: string | undefined
+  readonly output?: style.Output | undefined
+  readonly theme?: Theme.Definition | undefined
+}
+
+/** Expands selector and variable containers without changing declaration order. */
+export function body(input: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(input).flatMap(([key, value]) => {
+      if (key === 'targets') {
+        if (!value || typeof value !== 'object') return [[key, value]]
+        const descriptors = Object.getOwnPropertyDescriptors(value)
+        const web = descriptors.web
+        if (web && 'value' in web && web.value && typeof web.value === 'object')
+          descriptors.web = { ...web, value: body(web.value) }
+        return [[key, Object.create(Object.getPrototypeOf(value), descriptors)]]
+      }
+      if (key === 'selectors' || key === 'variables')
+        return Object.entries(value as Record<string, unknown>).map(
+          ([name, entry]) => [
+            name,
+            key === 'selectors'
+              ? body(entry as Record<string, unknown>)
+              : entry,
+          ],
+        )
+      if (key.startsWith('@') || key.startsWith(':') || key.includes('&'))
+        return [[key, body(value as Record<string, unknown>)]]
+      return [[key, value]]
+    }),
+  )
+}
+
+/** Creates spreadable props using content identities or an explicit definition identity. */
+export function create(
+  input: unknown = {},
+  options: Options = {},
+): style.ReturnType {
+  const dynamic = typeof input === 'function'
+  const id =
+    options.id === undefined
+      ? undefined
+      : Identity.requireId(options.id, 'style')
+  if (dynamic && !id) Identity.requireId(undefined, 'Dynamic style')
+  if (!dynamic && !id && Object.keys(input as object).length === 0)
+    Identity.requireId(undefined, 'Empty style')
+
+  const className = id
+    ? `z-style-${id}`
+    : Identity.style(
+        (
+          Style.define as (
+            input: Record<string, unknown>,
+            options: Style.define.Options,
+          ) => Style.Definition
+        )(
+          { style: body(input as Record<string, unknown>) },
+          { theme: options.theme },
+        ).styles[0]!,
+      )
+  const props = Props.create({ className })
+  const apply = (values?: style.Options & Record<string, unknown>) => {
+    let result = props(values as style.Options)
+    if (dynamic) {
+      const style: Record<string, string | number | undefined> = {
+        ...result.style,
+      }
+      for (const [field, value] of Object.entries(values ?? {})) {
+        if (['className', 'style', 'variables'].includes(field)) continue
+        style[Identity.slot(id!, field)] =
+          value === '' ? ' ' : (value as string | number)
+      }
+      result = { ...result, style }
+    }
+    return bind(options.output === 'html' ? Html.from(result) : result, [
+      {
+        name: className,
+        attributes: [],
+        slots: dynamic
+          ? Object.keys(values ?? {})
+              .filter(
+                (key) => !['className', 'style', 'variables'].includes(key),
+              )
+              .map((key) => Identity.slot(id!, key))
+          : [],
+      },
+    ])
+  }
+  Object.defineProperty(apply, Symbol.toPrimitive, {
+    value: () => `.${className}`,
+  })
+  return apply as style.ReturnType
+}
+
+/** Selects finite variants and binds dynamic payloads using explicit identities. */
+export function variants(
+  input: Record<string, unknown>,
+  options: Options = {},
+): unknown {
+  const id = Identity.requireId(options.id, 'variants')
+  const className = `z-style-${id}`
+  const axes = Object.entries(
+    (input.variants ?? {}) as Record<string, Record<string, unknown>>,
+  )
+  const conditions = Object.keys((input.conditions ?? {}) as object)
+  const defaults = (input.defaultVariants ?? {}) as Record<string, unknown>
+  const props = Props.create({ className })
+
+  return (values: Record<string, unknown> & style.Options = {}) => {
+    const result = { ...props(values as style.Options) } as {
+      className: string
+      style?: style.Props['style']
+      [key: `data-${string}`]: string | undefined
+    }
+    const bindings: Record<string, string | number> = {}
+    function select(axis: string, value: unknown, context: number): unknown {
+      if (!value || typeof value !== 'object') return value
+      const choice = Object.keys(value)[0]!
+      const payload = (
+        value as Record<string, Record<string, string | number>>
+      )[choice]!
+      const axisIndex = axes.findIndex(([name]) => name === axis)
+      const choiceIndex = Object.keys(axes[axisIndex]![1]).indexOf(choice)
+      for (const [field, value] of Object.entries(payload))
+        bindings[
+          Identity.slot(
+            `${id}-${axisIndex + 1}-${choiceIndex}-${context}`,
+            field,
+          )
+        ] = value === '' ? ' ' : value
+      return choice
+    }
+    for (const [axis] of axes) {
+      const value = select(
+        axis,
+        values[axis] === undefined ? defaults[axis] : values[axis],
+        0,
+      )
+      if (value !== undefined && value !== null)
+        result[`data-${axis}`] = String(value)
+    }
+    const selected = values.conditions as
+      | Record<string, Record<string, unknown>>
+      | undefined
+    for (const [index, name] of conditions.entries()) {
+      const context = selected?.[name]
+      if (!context) continue
+      for (const [axis] of axes) {
+        const value = select(axis, context[axis], index + 1)
+        if (value !== undefined)
+          result[`data-zyzz-condition-${index}-${axis}`] =
+            value === null ? 'n' : `s${value}`
+      }
+    }
+    if (Object.keys(bindings).length)
+      result.style = { ...result.style, ...bindings }
+    return bind(options.output === 'html' ? Html.from(result) : result, [
+      {
+        name: className,
+        attributes: axes.flatMap(([axis]) => [
+          `data-${axis}`,
+          ...conditions.map(
+            (_, index) => `data-zyzz-condition-${index}-${axis}`,
+          ),
+        ]),
+        slots: Object.keys(bindings),
+      },
+    ])
+  }
+}

package/src/internal/Binding.ts

@@ -0,0 +1,187 @@
+/** Describes fixed custom-property slots shared by explicit and callback bindings. @module */
+import type * as Literal from './Literal.js'
+import type * as Token from './Token.js'
+import * as BindingDomains from './BindingDomains.js'
+
+/** Explicit scalar domains or an unconstrained custom property. */
+export type Domain = Kind | '*'
+
+/** Supported runtime scalar domains. */
+export type Kind =
+  | 'color'
+  | 'length'
+  | 'number'
+  | 'percentage'
+  | 'signedLength'
+  | 'signedPercentage'
+
+/** A compiler-assigned web custom property with its scalar domain. */
+export type Reference<kind extends Domain = Domain> = {
+  /** Fixed CSS custom-property name. */
+  readonly name: `--${string}`
+  /** Scalar domain used by authoring types and runtime primitive checks. */
+  readonly type: kind
+  /** Distinguishes slots from theme references. */
+  readonly variable: true
+}
+
+/** Scalar inputs accepted by a slot. CSS semantics remain statically checked. */
+export type Value<kind extends Domain> = kind extends '*'
+  ? string | number
+  : kind extends 'number'
+    ? number
+    : kind extends 'color'
+      ? Literal.Color
+      : kind extends 'signedPercentage'
+        ? `${number}%`
+        : kind extends 'signedLength'
+          ? Exclude<Literal.Length, `${number}%`>
+          : kind extends 'percentage'
+            ? `${number}%` & NonNegative
+            : Exclude<Literal.Length, `${number}%`> & (NonNegative | 0)
+
+type NonNegative =
+  `${'0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '.' | '+'}${string}`
+
+/** Property domains that accept each scalar reference. */
+export type Properties<kind extends Kind> = {
+  [property in keyof Literal.Properties]: Property<kind, property>
+}[keyof Literal.Properties]
+
+/** Checks one property's binding domain without enumerating every CSS grammar. */
+export type Property<
+  kind extends Kind,
+  property extends keyof Literal.Properties,
+> = property extends `--${string}`
+  ? property
+  : property extends keyof typeof Literal.rules
+    ? (typeof Literal.rules)[property] extends { kind: 'compound' }
+      ? never
+      : kind extends 'percentage' | 'signedPercentage'
+        ? (typeof Literal.rules)[property] extends { kind: 'number' }
+          ? (typeof Literal.rules)[property] extends { percentage: true }
+            ? Compatible<kind, property>
+            : never
+          : Compatible<kind, property>
+        : Compatible<kind, property>
+    : never
+
+type Compatible<
+  kind extends Kind,
+  property extends keyof Literal.Properties,
+> = kind extends 'color'
+  ? property extends Token.Properties<'color'>
+    ? property
+    : never
+  : kind extends 'number'
+    ? number extends Literal.Properties[property]
+      ? property extends keyof typeof Literal.rules
+        ? property extends
+            | 'opacity'
+            | 'fillOpacity'
+            | 'floodOpacity'
+            | 'stopOpacity'
+            | 'strokeOpacity'
+          ? property
+          : (typeof Literal.rules)[property] extends
+                | { kind: 'grid-line' | 'ratio' }
+                | { integer: true }
+                | { min: number }
+                | { max: number }
+                | { negative: false }
+            ? never
+            : property
+        : property
+      : never
+    : Extract<
+          Literal.Properties[property],
+          kind extends 'percentage' | 'signedPercentage'
+            ? `${number}%`
+            : `${number}px`
+        > extends never
+      ? never
+      : kind extends 'signedLength' | 'signedPercentage'
+        ? property extends keyof typeof Literal.rules
+          ? (typeof Literal.rules)[property] extends
+              | { negative: false }
+              | { kind: 'line' | 'grid-tracks' }
+              | { min: number }
+              | { max: number }
+            ? never
+            : property
+          : property
+        : property
+
+/** Rejects broad numeric callback values where a property requires a narrower domain. */
+export type Checked<style> = {
+  [property in keyof style]: property extends 'targets'
+    ? never
+    : property extends keyof Literal.Properties
+      ? number extends style[property]
+        ? property extends Property<'number', property>
+          ? unknown
+          : never
+        : unknown
+      : style[property] extends Record<string, unknown>
+        ? Checked<style[property]>
+        : unknown
+}
+
+/** Rejects reserved callback field names and importance-bearing value domains. */
+export type Inputs<values> = {
+  [key in keyof values]: key extends
+    | 'class'
+    | 'className'
+    | 'key'
+    | 'ref'
+    | 'style'
+    | 'variables'
+    | '__proto__'
+    ? never
+    : Extract<values[key], `${string}!${string}`> extends never
+      ? Extract<
+          Lowercase<Extract<values[key], string>>,
+          'initial' | 'inherit' | 'unset' | 'revert' | 'revert-layer'
+        > extends never
+        ? values[key]
+        : never
+      : never
+}
+
+/** Recognizes fixed slot data without invoking consumer accessors. */
+export function is(value: unknown): value is Reference {
+  if (typeof value !== 'object' || value === null || !Object.isFrozen(value))
+    return false
+
+  const fields = Object.getOwnPropertyDescriptors(value)
+
+  return (
+    ['name', 'type', 'variable'].every(
+      (key) => fields[key] && 'value' in fields[key]!,
+    ) &&
+    fields.variable!.value === true &&
+    typeof fields.name!.value === 'string' &&
+    /^--[a-zA-Z0-9_-]+$/.test(fields.name!.value) &&
+    [
+      '*',
+      'color',
+      'length',
+      'number',
+      'percentage',
+      'signedLength',
+      'signedPercentage',
+    ].includes(fields.type!.value)
+  )
+}
+
+/** Checks template reference domains against declaration shapes. */
+export function accepts(
+  kind: Domain,
+  property: keyof Literal.Properties,
+): boolean {
+  if (kind === '*' || property.startsWith('--')) return true
+
+  return (BindingDomains.properties[kind] as readonly string[]).includes(
+    property,
+  )
+}