@wardic/dom 0.0.0-stage → 1.0.0-rc.2

package/src/internal/svg.ts

@@ -0,0 +1,300 @@
+/**
+ * SVG realization for the DOM renderer (ADR-0014). The core value pipeline +
+ * the pure `project` stay AGNOSTIC and flat: SVG numeric attrs (`cx`/`r`/…)
+ * already spring as numbers and `fill`/`stroke` already interpolate as colors.
+ * This module is the DOM-API ROUTING layer — the one place that decides whether
+ * a resolved value is written as a CSS `style` or an `setAttribute`, plus the
+ * SVG-specific shaping (`transform-box`, `pathLength`→dash). It is the seam a
+ * non-DOM SVG renderer (e.g. react-native-svg) would replace wholesale; nothing
+ * here is shared with `@wardic/core`.
+ *
+ * Model (Motion's `buildSVGAttrs`): for an svg-INNER element every key is an
+ * ATTRIBUTE except `transform`/`transformOrigin`/`transformBox` + the CSS
+ * motion-path props, which stay STYLE, and a custom property (`--…`), which is style
+ * under its own name on every element (#151). For an HTML element or the `<svg>` ROOT
+ * everything is style (the root has a CSS box; only `viewBox` would be an attr —
+ * deferred). So the HTML path is unchanged: its attribute map is always empty.
+ */
+import type * as Renderer from "@wardic/core/Renderer"
+import * as Bool from "effect/Boolean"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+
+/**
+ * Keys that remain CSS `style` on an svg-inner element; everything else routes
+ * to an attribute. `transform` is applied as a CSS transform (with `transform-box`
+ * below); the motion-path props are CSS-only on SVG too (Motion parity).
+ */
+const SVG_STYLE_KEYS: ReadonlySet<string> = new Set([
+  "transform",
+  "transformOrigin",
+  "transform-origin",
+  "transformBox",
+  "transform-box",
+  "offsetDistance",
+  "offsetPath",
+  "offsetRotate",
+  "offsetAnchor",
+])
+
+/**
+ * SVG attribute names always written camelCase (never dash-cased) — Motion's
+ * `camelCaseAttributes`. Everything else is dash-cased (`strokeWidth` →
+ * `stroke-width`).
+ */
+const CAMEL_CASE_ATTRS: ReadonlySet<string> = new Set([
+  "baseFrequency",
+  "diffuseConstant",
+  "kernelMatrix",
+  "kernelUnitLength",
+  "keySplines",
+  "keyTimes",
+  "limitingConeAngle",
+  "markerHeight",
+  "markerWidth",
+  "numOctaves",
+  "targetX",
+  "targetY",
+  "surfaceScale",
+  "specularConstant",
+  "specularExponent",
+  "stdDeviation",
+  "tableValues",
+  "viewBox",
+  "gradientTransform",
+  "pathLength",
+  "startOffset",
+  "textLength",
+  "lengthAdjust",
+])
+
+/**
+ * Escape hatches: `x`/`y` are transform shorthands in Wardic (translateX/Y), so
+ * the SVG geometry ATTRIBUTE form is the explicit `attr*` key (Motion's
+ * `attrX`/`attrY`/`attrScale`). Maps to the bare attribute name.
+ */
+const ATTR_ALIASES: Record<string, string> = { attrX: "x", attrY: "y", attrScale: "scale" }
+
+/**
+ * Each key's dash-cased name, computed once (ADR-0034): the commit dash-cases every key of
+ * every patch, each frame. Keys come from animation configs, so the set stays small.
+ */
+// Module state (#460, Q7): a cache keyed by what it caches: a bounded set of names.
+const DASHED = new Map<string, string>()
+
+/**
+ * Whether `key` is a CSS custom property (`--brandColor`): it keeps its name, which is
+ * case-sensitive, and is always a style property, on SVG too (ADR-0014, *Amendment (#151)*;
+ * Motion's `isCSSVariableName`).
+ */
+const isCustomProperty = (key: string): boolean => key.startsWith("--")
+
+/**
+ * camelCase → dash-case for a CSS/attribute name (`transformBox` → `transform-box`); a
+ * custom property keeps its name (`--brandColor`).
+ */
+export const dashCase = (key: string): string => {
+  const cached = DASHED.get(key)
+  if (Predicate.isNotUndefined(cached)) return cached
+  const dashed = Bool.match(isCustomProperty(key), {
+    onTrue: () => key,
+    onFalse: () => key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`),
+  })
+  DASHED.set(key, dashed)
+  return dashed
+}
+
+/** The attribute name for an engine key: dash-cased unless it's a known camelCase attr. */
+const attrName = (key: string): string => {
+  if (CAMEL_CASE_ATTRS.has(key)) return key
+  return dashCase(key)
+}
+
+/** Whether a key collapses into the stroke dash: `pathLength`, `pathSpacing` or `pathOffset`. */
+export const isPathKey = (key: string): boolean => key === "pathLength" || key === "pathSpacing" || key === "pathOffset"
+
+/**
+ * The attribute an svg-inner element's `key` is written as (the routing below), or
+ * `None` for a key that stays style ({@link SVG_STYLE_KEYS}, a custom property) or collapses into the
+ * stroke dash (`pathLength` / `pathSpacing` / `pathOffset`). Internal: the Own-value read
+ * reads the attribute a key is written as (ADR-0022).
+ */
+export const svgAttrNameOf = (key: string): Option.Option<string> =>
+  Bool.match(isPathKey(key) || isCustomProperty(key), {
+    onTrue: () => Option.none(),
+    onFalse: () =>
+      Option.orElse(Option.fromUndefinedOr(ATTR_ALIASES[key]), () =>
+        Option.map(Option.liftPredicate(key, (k: string) => Bool.not(SVG_STYLE_KEYS.has(k))), attrName)
+      ),
+  })
+
+/** Whether `el` is an `<svg>` root, which is styled as HTML is: it has a CSS box. */
+export const isSvgRoot = (el: unknown): boolean => {
+  // No SVG classes on a server. Per frame (a flush's split): plain checks.
+  const SvgRoot = (globalThis as { readonly SVGSVGElement?: typeof SVGSVGElement }).SVGSVGElement
+  return Predicate.isNotUndefined(SvgRoot) && el instanceof SvgRoot
+}
+
+/** Whether `el` is an SVG element inside an `<svg>`: any SVG element but the root. */
+export const isSvgInner = (el: unknown): boolean => {
+  const Svg = (globalThis as { readonly SVGElement?: typeof SVGElement }).SVGElement
+  return Predicate.isNotUndefined(Svg) && el instanceof Svg && !isSvgRoot(el)
+}
+
+/** A style patch, split: the keys written as CSS, and the ones written as attributes. */
+export interface SplitPatch {
+  /** The keys written as CSS: the whole patch for HTML and an `<svg>` root, the very object given. */
+  readonly style: Readonly<Record<string, unknown>>
+  /** The keys written with `setAttribute`: none for HTML and an `<svg>` root. */
+  readonly attrs: Readonly<Record<string, string>>
+}
+
+/** An HTML element's attributes from a patch: none, one shared frozen record (#618: one a split). */
+const NO_ATTRS: Readonly<Record<string, string>> = Object.freeze({})
+
+/**
+ * A style patch split for `el`: an HTML element's, or an `<svg>` root's, is all style. An SVG element
+ * inside one takes every key as an attribute but the keys CSS styles and a custom property; `attrX`,
+ * `attrY` and `attrScale` as its `x`, `y` and `scale` attributes; a `transform` with `transform-box:
+ * fill-box` and `transform-origin: 50% 50%`, unless the values set them, so it turns about its own centre
+ * as an HTML element does; and `pathLength`, `pathSpacing` and `pathOffset` as a normalised
+ * `stroke-dasharray` and `stroke-dashoffset`, with `pathLength="1"`.
+ */
+// The CSS keys: `SVG_STYLE_KEYS`.
+export const splitPatch = (el: unknown, patch: Renderer.Patch): SplitPatch => {
+  if (isSvgInner(el)) return routeSvgInner(patch)
+  return { style: patch as Readonly<Record<string, unknown>>, attrs: NO_ATTRS }
+}
+
+/**
+ * SVG's element names that HTML doesn't share, lowercase (Motion's list,
+ * framer-motion/src/render/svg/lowercase-elements.ts @ 16c6122, without the `svg` root).
+ * A name with a capital letter (`clipPath`, `linearGradient`, `feGaussianBlur` …) is SVG
+ * too, as Motion's `isSVGComponent` decides; `a`, `script`, `style` and `title` count as
+ * HTML, since a server has no namespace to tell them apart.
+ */
+const SVG_INNER_TAGS: ReadonlySet<string> = new Set([
+  "animate",
+  "circle",
+  "defs",
+  "desc",
+  "ellipse",
+  "g",
+  "image",
+  "line",
+  "filter",
+  "marker",
+  "mask",
+  "metadata",
+  "path",
+  "pattern",
+  "polygon",
+  "polyline",
+  "rect",
+  "stop",
+  "switch",
+  "symbol",
+  "text",
+  "tspan",
+  "use",
+  "view",
+])
+
+/** Whether `tag` names an SVG element inside an `<svg>`, by its name alone. */
+export const isSvgInnerTag = (tag: string): boolean => !tag.includes("-") && (SVG_INNER_TAGS.has(tag) || /[A-Z]/.test(tag))
+
+/** `splitPatch` by tag name, for where there's no element yet: a server render, a starting style. `undefined` is an HTML element. */
+// ADR-0021.
+export const splitPatchForTag = (tag: string | undefined, patch: Renderer.Patch): SplitPatch =>
+  Bool.match(Predicate.isNotUndefined(tag) && isSvgInnerTag(tag), {
+    onTrue: () => routeSvgInner(patch),
+    onFalse: () => ({ style: patch as Readonly<Record<string, unknown>>, attrs: NO_ATTRS }),
+  })
+
+/** The svg-inner routing {@link splitPatch} and {@link splitPatchForTag} share. */
+const routeSvgInner = (patch: Renderer.Patch): SplitPatch => {
+  const style: Record<string, unknown> = {}
+  const attrs: Record<string, string> = {}
+  let hasTransform = false
+  let pathLength: unknown
+  let pathSpacing: unknown
+  let pathOffset: unknown
+
+  for (const key in patch) {
+    const value = patch[key]
+    if (Predicate.isUndefined(value)) continue
+    if (key === "pathLength") {
+      pathLength = value
+      continue
+    }
+    if (key === "pathSpacing") {
+      pathSpacing = value
+      continue
+    }
+    if (key === "pathOffset") {
+      pathOffset = value
+      continue
+    }
+    const alias: string | undefined = ATTR_ALIASES[key]
+    if (Predicate.isNotUndefined(alias)) {
+      attrs[alias] = String(value)
+      continue
+    }
+    if (SVG_STYLE_KEYS.has(key)) {
+      style[key] = value
+      if (key === "transform") hasTransform = true
+      continue
+    }
+    // A custom property is a style property (ADR-0014, *Amendment (#151)*).
+    if (isCustomProperty(key)) {
+      style[key] = value
+      continue
+    }
+    attrs[attrName(key)] = String(value)
+  }
+
+  // SVG's transform-origin defaults to the document origin (0 0), not the element
+  // centre — so a CSS transform on SVG reads differently from HTML. `fill-box` +
+  // a centred origin restore HTML-like semantics (Motion). User-set wins.
+  if (hasTransform) {
+    if (Predicate.isUndefined(style["transformBox"]) && Predicate.isUndefined(style["transform-box"])) {
+      style["transform-box"] = "fill-box"
+    }
+    if (Predicate.isUndefined(style["transformOrigin"]) && Predicate.isUndefined(style["transform-origin"])) {
+      style["transform-origin"] = "50% 50%"
+    }
+  }
+
+  // pathLength → normalised stroke dash (Motion's buildSVGPath). Unitless: Safari
+  // mis-scales px dash values when the page is zoomed.
+  if (Predicate.isNotUndefined(pathLength)) {
+    attrs["pathLength"] = "1"
+    attrs["stroke-dasharray"] = `${pathLength} ${spacingOf(pathSpacing)}`
+    attrs["stroke-dashoffset"] = String(dashOffsetOf(offsetOf(pathOffset)))
+  }
+
+  return { style, attrs }
+}
+
+// The stroke dash's parts, per frame: early returns.
+/** `pathSpacing`, 1 when none is given. */
+const spacingOf = (spacing: unknown): unknown => {
+  if (Predicate.isNullish(spacing)) return 1
+  return spacing
+}
+/** `pathOffset` as a number, 0 when none is given. */
+const offsetOf = (offset: unknown): number => {
+  if (Predicate.isNumber(offset)) return offset
+  if (Predicate.isNullish(offset)) return 0
+  return Number(offset)
+}
+/** The dash offset an offset draws: its negation, 0 for one that isn't finite. */
+const dashOffsetOf = (offset: number): number => {
+  if (Number.isFinite(offset)) return -offset
+  return 0
+}
+
+/** Writes each attribute onto `el` with `setAttribute`; nothing for an empty map. */
+export const setSvgAttrs = (el: Element, attrs: Readonly<Record<string, string>>): void => {
+  for (const name in attrs) el.setAttribute(name, attrs[name])
+}

package/src/internal/variables.ts

@@ -0,0 +1,145 @@
+/**
+ * Variable values in the DOM (#55, ADR-0035 *Amendment (#55)*; CONTEXT.md): a value that is wholly a
+ * `var(--name)`, with or without a fallback, stands for that custom property's value on the element.
+ * `variableValues(element)` is a Key rule bound to one element, which a binding adds to each leg it
+ * builds (`InterpolatorRegistry.withKeyRules`). Motion's rule (`getVariableValue`,
+ * css-variables-conversion.ts:18-53, and `DOMKeyframesResolver.readKeyframes` at 16c6122):
+ *
+ * - Either end that is a Variable value is resolved against the element, once, when the leg is
+ *   built: the custom property's computed value, else its fallback, following a fallback that is
+ *   itself a Variable value up to 4 deep. A numeric result is a number.
+ * - The resolved pair goes on through `next`, so the rules after this one still apply (`"none"` →
+ *   `var(--shadow)` grows from its Animatable none), then blends by value.
+ * - The leg's last frame writes the target as written, so at rest the element follows the custom
+ *   property again; a change mid-leg is followed from there.
+ * - A Variable value that doesn't resolve leaves the pair as written: the rule declines, and it
+ *   switches as a Discrete pair, as Motion's does. A `var()` inside a larger value is text (#158).
+ *
+ * Client-only: it reads the element's computed style, after mount (ADR-0021).
+ *
+ * @module
+ */
+import type * as InterpolatorRegistry from "@wardic/core/InterpolatorRegistry"
+import * as Arr from "effect/Array"
+import * as Bool from "effect/Boolean"
+import * as Effect from "effect/Effect"
+import { pipe } from "effect/Function"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import * as Str from "effect/String"
+
+/** A value a key blends: a number or a string. */
+/** What a Variable value resolves to: a number or a string. */
+type Value = number | string
+
+/** A Variable value's custom property, and its fallback when it has one (Motion's `parseCSSVariable`). */
+const PARTS_RE = /^var\(\s*(--[\w-]+)\s*(?:,\s*([\s\S]*?))?\s*\)$/
+
+/** The cheap first check: a string that starts as a `var()` does. */
+const VAR_START_RE = /^\s*var\(/
+
+/** How a character moves the bracket depth. */
+const depthStep = (ch: string): number => Bool.match(ch === "(", { onTrue: () => 1, onFalse: () => Bool.match(ch === ")", { onTrue: () => -1, onFalse: () => 0 }) })
+
+/** Brackets that close as they open: a fallback that is one value, not the rest of a longer string. */
+const isBalanced = (text: string): boolean => {
+  const end = Arr.reduce(Str.split(text, ""), 0, (depth, ch) => Bool.match(depth < 0, { onTrue: () => depth, onFalse: () => depth + depthStep(ch) }))
+  return end === 0
+}
+
+/** A Variable value's parts: its custom property's name and its fallback. */
+interface Parts {
+  readonly name: string
+  readonly fallback: Option.Option<string>
+}
+
+/**
+ * A Variable value's parts, or `None` for any other value: `var(--name)` or `var(--name, fallback)`,
+ * the fallback's brackets balanced, at any depth of nested `var()`s (a pattern alone stops at one).
+ * So `var(--a, 1px) var(--b)` isn't one: two values side by side.
+ */
+const partsOf = (value: string): Option.Option<Parts> => {
+  // Asked of a string end of every key, each leg (#460): one that doesn't start as one builds nothing.
+  if (!VAR_START_RE.test(value)) return Option.none()
+  return pipe(
+    Option.fromNullishOr(PARTS_RE.exec(Str.trim(value))),
+    Option.map(([, name, fallback]): Parts => ({ name, fallback: Option.map(Option.fromUndefinedOr(fallback), Str.trim) })),
+    Option.filter((parts) => Option.match(parts.fallback, { onNone: () => true, onSome: isBalanced })),
+  )
+}
+
+/** How deep a fallback that is itself a Variable value is followed (Motion's `maxDepth`). */
+const MAX_DEPTH = 4
+
+/** A numeric string, which a resolved value becomes a number from (Motion's `isNumericalString`). */
+const NUMERIC_RE = /^-?\d*\.?\d+(?:e[-+]?\d+)?$/i
+
+/** Whether `value` is a Variable value: a string that's wholly a `var()`. */
+// CONTEXT.md's Variable value.
+export const isVariableValue = (value: unknown): value is string => Predicate.isString(value) && Option.isSome(partsOf(value))
+
+/** A resolved value as a key blends it: a number when it reads as one, else the string. */
+const valueOf = (raw: string): Value => Bool.match(NUMERIC_RE.test(raw), { onTrue: () => Number.parseFloat(raw), onFalse: () => raw })
+
+/**
+ * What a Variable value stands for on `element`: its custom property's computed value, else its
+ * fallback, a fallback that is itself a Variable value followed up to 4 deep. `None` when nothing
+ * resolves. Reads the element's computed style.
+ */
+export const resolveVariable = (element: Element, value: string): Option.Option<Value> => resolveAt(element, value, 1)
+
+/** {@link resolveVariable} at `depth`, following a fallback that's itself a Variable value. */
+// #618 (F7): the depth counter was the public function's third parameter.
+const resolveAt = (element: Element, value: string, depth: number): Option.Option<Value> => {
+  if (depth > MAX_DEPTH) return Option.none()
+  return Option.flatMap(partsOf(value), ({ name, fallback }) => {
+    const own = Str.trim(getComputedStyle(element).getPropertyValue(name))
+    if (Str.isNonEmpty(own)) return Option.some(valueOf(own))
+    return pipe(
+      fallback,
+      Option.filter(Str.isNonEmpty),
+      Option.flatMap((rest) =>
+        Bool.match(isVariableValue(rest), {
+          onTrue: () => resolveAt(element, rest, depth + 1),
+          onFalse: () => Option.some(valueOf(rest)),
+        })),
+    )
+  })
+}
+
+/** An end as the leg blends it: a Variable value resolved on `element`, any other value as it is. */
+const endOf = (element: Element, value: Value): Option.Option<Value> =>
+  Bool.match(isVariableValue(value), {
+    onTrue: () => resolveVariable(element, value as string),
+    onFalse: () => Option.some(value),
+  })
+
+/**
+ * A blend that writes its target as written on the run's last Frame: a Variable value rests as the
+ * `var()` itself, so the element follows its custom property again. Per frame: a statement `if`.
+ */
+const landOn =
+  (blend: InterpolatorRegistry.KeyBlend, to: Value): InterpolatorRegistry.KeyBlend =>
+  (t, done) => {
+    if (done) return to
+    return blend(t, done)
+  }
+
+/**
+ * The Key rule for `element`'s Variable values: a pair with one at either end blends what they resolve
+ * to on `element`, through the rules after it and then by value, and lands on its target as written. It
+ * declines a pair with none, and one that doesn't resolve.
+ *
+ * @example
+ * yield* buildLegs.pipe(InterpolatorRegistry.withKeyRules([Variables.values(element)]))
+ */
+// #55.
+export const variableValues = (element: Element): InterpolatorRegistry.KeyRule => ({
+  name: "variable values",
+  blend: (key, from, to, _resolve, next) => {
+    // Per key, each leg (#460): a statement.
+    if (!isVariableValue(from) && !isVariableValue(to)) return Option.none()
+    return Option.map(Option.all([endOf(element, from), endOf(element, to)]), ([a, b]) =>
+      Effect.map(next(key, a, b), (blend) => landOn(blend, to)))
+  },
+})