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

package/src/internal/require-global.ts

@@ -0,0 +1,46 @@
+/**
+ * DomLive is client-only, and says so (ADR-0021, decision 7). A server render builds no
+ * runtime, so building a DomLive Layer on a server is always a mistake: each Layer that
+ * needs a browser global checks for it as its build starts, and fails with one message
+ * naming the Layer, the global and the rule, instead of a `ReferenceError` from deep
+ * inside the build.
+ *
+ * Read when the Layer builds, never when `@wardic/dom` is imported. Once per build, so
+ * no log or span (the cold path's message is the error itself).
+ */
+import * as Bool from "effect/Boolean"
+import * as Effect from "effect/Effect"
+import * as Predicate from "effect/Predicate"
+
+/** The browser globals a DomLive Layer can need. */
+export type BrowserGlobal = "requestAnimationFrame" | "document" | "window"
+
+/** The DOM's Layers that need a browser global, by the names an app knows them by. */
+export type ClientLayer = "DomClock.layer" | "DomInput.layer" | "DomProbe.layer" | "DomAnnouncer.layer"
+
+/** Where an app gets each: three are `DomLive`'s, and a gesture builds the input. */
+const FROM: Readonly<Record<ClientLayer, string>> = {
+  "DomClock.layer": "DomLive's",
+  "DomProbe.layer": "DomLive's",
+  "DomAnnouncer.layer": "DomLive's",
+  "DomInput.layer": "a gesture's",
+}
+
+/**
+ * Fail the build of `layer` with ADR-0021's client-only error when `global` doesn't exist.
+ * Make it the first step of the build: anything that reads the global must come after it.
+ */
+// #618 (D7): the error named the Layers ADR-0041 renamed (`ClockDomLive`…), and an ADR; `layer` is a
+// union of today's names, so a rename can't leave it behind. Short, as every app ships it.
+export const requireGlobal = (layer: ClientLayer, global: BrowserGlobal): Effect.Effect<void> =>
+  Effect.suspend(() =>
+    Bool.match(Predicate.isUndefined((globalThis as Record<string, unknown>)[global]), {
+      onTrue: () =>
+        Effect.die(
+          new Error(
+            `${layer} (${FROM[layer]}) needs ${global}: Wardic's runtime is client-only, never built during a server render.`,
+          ),
+        ),
+      onFalse: () => Effect.void,
+    })
+  )

package/src/internal/reveal.ts

@@ -0,0 +1,69 @@
+/**
+ * Keep a **Keyboard reorder**'s item in view (ADR-0037, Q13): after a step, scroll its new place
+ * into view, as little as needed, in each scroller that moves it and then the page, as
+ * `scrollIntoView({ block: "nearest", inline: "nearest" })` would. Its new place, not where it's
+ * drawn: a step's layout animation starts it where it was, so the box is the element's painted one
+ * with its own transform (a translate and a scale about its origin) undone. Instant, so it never
+ * runs against the step's own animation, and with nothing for reduced motion to stop.
+ *
+ * @internal for the Reorder controller.
+ */
+import { scrollersOf } from "./scrollers.ts"
+import * as Arr from "effect/Array"
+
+/** A box on screen, in client coordinates. */
+interface Rect {
+  readonly left: number
+  readonly top: number
+  readonly right: number
+  readonly bottom: number
+}
+
+/**
+ * `el`'s layout box on screen: its painted box with its own transform undone. A translate and a
+ * scale (the projection's) about its `transform-origin`; a box drawn with no transform is as painted.
+ */
+export const layoutRectOf = (el: Element): Rect => {
+  const painted = el.getBoundingClientRect()
+  const style = getComputedStyle(el)
+  const m = new DOMMatrixReadOnly(style.transform)
+  if (m.isIdentity) return painted
+  if (m.a === 0) return painted
+  if (m.d === 0) return painted
+  const [ox = 0, oy = 0] = style.transformOrigin.split(" ").map((v) => Number.parseFloat(v))
+  const left = painted.left - m.e - ox * (1 - m.a)
+  const top = painted.top - m.f - oy * (1 - m.d)
+  return { left, top, right: left + painted.width / m.a, bottom: top + painted.height / m.d }
+}
+
+/**
+ * How far to scroll a view from `viewMin` to `viewMax` so `min` to `max` shows: 0 when it does, else
+ * the least that brings it in, its start first when it can't all fit.
+ */
+const scrollToShow = (min: number, max: number, viewMin: number, viewMax: number): number => {
+  if (min < viewMin) return min - viewMin
+  if (max > viewMax) return Math.min(max - viewMax, min - viewMin)
+  return 0
+}
+
+/** Scroll `el`'s new place into view (see the module doc). */
+export const revealLayoutOf = (el: Element): void => {
+  const { ancestors, page } = scrollersOf(el)
+  // Each scroller in turn, nearest first: what it scrolls moves the element for the next.
+  const rect = Arr.reduce(ancestors, layoutRectOf(el), (rect, scroller) => {
+    const box = scroller.getBoundingClientRect()
+    const top = box.top + scroller.clientTop
+    const left = box.left + scroller.clientLeft
+    const dy = scrollToShow(rect.top, rect.bottom, top, top + scroller.clientHeight)
+    const dx = scrollToShow(rect.left, rect.right, left, left + scroller.clientWidth)
+    if (dx === 0 && dy === 0) return rect
+    scroller.scrollBy({ left: dx, top: dy, behavior: "instant" })
+    return { left: rect.left - dx, top: rect.top - dy, right: rect.right - dx, bottom: rect.bottom - dy }
+  })
+  const win = el.ownerDocument.defaultView
+  if (page && win !== null) {
+    const dy = scrollToShow(rect.top, rect.bottom, 0, win.innerHeight)
+    const dx = scrollToShow(rect.left, rect.right, 0, win.innerWidth)
+    if (dx !== 0 || dy !== 0) win.scrollBy({ left: dx, top: dy, behavior: "instant" })
+  }
+}

package/src/internal/runner.ts

@@ -0,0 +1,64 @@
+/**
+ * A Layer-built service's runner (#132, ADR-0041): how `FlushGate.make` and `DomProjectionSystem.make`
+ * run their Effects after they're built, synchronously and forked, on the context their Layer was
+ * built in, forking into its Scope.
+ *
+ * The context drops a sync scheduler, and keeps any other (ADR-0041, *Amendment (#208)*). A
+ * binding's first read builds the Layer inside a `ManagedRuntime.runSync`, whose fiber carries a sync
+ * `MixedScheduler`: kept, it would pin every later fork to that scheduler, which resumes a fork's
+ * yields on a microtask, where Effect's default resumes them on a macrotask. Without it, forks use
+ * the default, as a `ManagedRuntime`'s do. A host's own async scheduler, provided in the Layers it
+ * hands Wardic (Foldkit's microtask `MixedScheduler`), is the host's choice: forks keep it (ADR-0027,
+ * decision 6: a fork inherits the scheduler it's forked under). A host that provides a *sync* one is
+ * overridden too: a sync scheduler is for draining a `runSync`.
+ */
+import * as Bool from "effect/Boolean"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import type * as Fiber from "effect/Fiber"
+import * as FiberSet from "effect/FiberSet"
+import * as Scheduler from "effect/Scheduler"
+import * as Scope from "effect/Scope"
+
+/** Runs Effects synchronously, and forked into the Scope it was made in. */
+export interface Runner<R> {
+  readonly runSync: <A, E>(effect: Effect.Effect<A, E, R>) => A
+  readonly runFork: <A, E>(effect: Effect.Effect<A, E, R>) => Fiber.Fiber<A, E>
+  /**
+   * The Scope it was made in: what a service built with it keeps its own fibers in, so closing the
+   * Scope ends them, after the service's own cleanup, and awaits them.
+   */
+  // #618 (L1): each service opened a detached Scope of its own, closed by a fork or a throwing runSync.
+  readonly scope: Scope.Scope
+}
+
+/**
+ * A runner over the current context, without a sync scheduler, forking into a `FiberSet` in the
+ * current Scope. It forks with that context itself (`Effect.runForkWith`), not through
+ * `FiberSet.runtime`, which reads the context again in the current fiber, where the building call's
+ * scheduler still is: `Effect.provideContext` merges into a fiber's context, it doesn't replace it.
+ */
+// Not `Effect.fnUntraced`, as effect-4's guide prefers: TypeScript can't carry `R` through it, and the
+// runner's context would be `unknown` (#618, H1).
+export const makeRunner = <R>(): Effect.Effect<Runner<R>, never, R | Scope.Scope> =>
+  Effect.gen(function* () {
+    const context = withoutSyncScheduler(yield* Effect.context<R | Scope.Scope>())
+    const fibers = yield* FiberSet.make()
+    const fork = Effect.runForkWith(context)
+    const runFork = <A, E>(effect: Effect.Effect<A, E, R>): Fiber.Fiber<A, E> => {
+      const fiber = fork(effect)
+      FiberSet.addUnsafe(fibers, fiber)
+      return fiber
+    }
+    return { runSync: Effect.runSyncWith(context), runFork, scope: Context.get(context, Scope.Scope) }
+  })
+
+/**
+ * `context` without its scheduler when that one is sync (`runSync`'s), else as it is: a host's
+ * async scheduler stays, and with none stored the context has Effect's default already.
+ */
+const withoutSyncScheduler = <S>(context: Context.Context<S>): Context.Context<S> =>
+  Bool.match(Context.get(context, Scheduler.Scheduler).executionMode === "sync", {
+    onTrue: () => Context.omit(Scheduler.Scheduler)(context),
+    onFalse: () => context,
+  })

package/src/internal/scale-correction.ts

@@ -0,0 +1,310 @@
+/**
+ * Scale-correction registry (ADR-0011) — the visual-correction half of the
+ * projection (ADR-0009). A scaling projection counter-scales an element's
+ * geometry via the transform, but non-geometric CSS — `border-radius`,
+ * `box-shadow` — is still distorted by that scale. Each {@link ScaleCorrector}
+ * reads the element's base value at measure time and, per frame, emits a CSS
+ * string that — once the transform scales it — renders as the AUTHORED value.
+ *
+ * The projection coordinator owns the pipeline (it has the element + the per-frame
+ * `delta`/`treeScale`); the corrected value is written into the node's gate entry
+ * as an ordinary style key, so the Renderer stays pure (ADR-0002/0006) — it just
+ * applies what the projection computed.
+ *
+ * Units: `getComputedStyle` resolves em/rem/etc. to px, leaving only **px**
+ * (corrected via `/scale`) and **`%`** (self-correcting — a percentage stays the
+ * same fraction of each scaled dimension, so it passes through). Reading resolved
+ * values therefore gives full-grammar parity.
+ */
+import type * as Box from "@wardic/core/Box"
+import type * as Point from "@wardic/core/Point"
+import type * as Projection from "@wardic/core/Projection"
+import * as Predicate from "effect/Predicate"
+
+/**
+ * What an app's scale corrector is handed beside the value: the projection node's fields Motion's
+ * correctors read, as Motion names them. `target` is the box the node is drawn into this frame,
+ * `treeScale` its ancestors' scale, `projectionDelta` its delta.
+ */
+// #443.
+export interface CorrectorInfo {
+  /** The box the node is drawn into this frame. */
+  readonly target: Box.Box
+  /** Its ancestors' scale, multiplied together. */
+  readonly treeScale: Point.Point
+  /** Its delta, from its layout box to `target`. */
+  readonly projectionDelta: Projection.Delta
+}
+
+/**
+ * An app's scale corrector (Motion's `addScaleCorrector` entry), given to a provider by the value key it
+ * corrects (`borderRadius`, `--card-radius`): `correct` turns the element's value into the one to write
+ * while its projection scales it, written under `applyTo`'s keys when given, else its own.
+ */
+// #443.
+export interface ScaleCorrectorEntry {
+  /** The value to write while the projection scales the element, from its own value, `latest`, and the node's fields. */
+  readonly correct: (latest: string | number, info: CorrectorInfo) => string | number
+  /** The keys the corrected value is written under: its own key when left out. */
+  readonly applyTo?: ReadonlyArray<string> | undefined
+}
+
+/** A registered scale corrector — owns reading its base + emitting the corrected value. */
+export interface ScaleCorrector {
+  /** The gate value-map / CSS key the corrected value is written under. */
+  readonly key: string
+  /**
+   * Read the element's base value(s) at measure time (read phase), or `undefined`
+   * if there is nothing to correct (e.g. radius all `0px`, shadow `none`).
+   */
+  readonly read: (el: HTMLElement) => unknown
+  /** Emit the corrected CSS string for the per-axis visual scale `(sx, sy)`. */
+  readonly correct: (base: unknown, sx: number, sy: number) => string
+}
+
+const EPS = 1e-3
+/** Whether a per-axis scale is ~identity (no correction needed). */
+export const isUnitScale = (sx: number, sy: number): boolean => Math.abs(sx - 1) < EPS && Math.abs(sy - 1) < EPS
+
+// --- border-radius -----------------------------------------------------------
+
+/** One corner's horizontal + vertical radius as authored strings (px or %). */
+interface CornerRadius {
+  readonly h: string
+  readonly v: string
+}
+/** The four corners, in CSS order: top-left, top-right, bottom-right, bottom-left. */
+type RadiusBase = readonly [CornerRadius, CornerRadius, CornerRadius, CornerRadius]
+
+const CORNER_PROPS = [
+  "borderTopLeftRadius",
+  "borderTopRightRadius",
+  "borderBottomRightRadius",
+  "borderBottomLeftRadius",
+] as const
+
+/** Parse a computed longhand (`"H V"` or `"H"`) into its H + V components. */
+const parseCorner = (computed: string): CornerRadius => {
+  // `split` gives at least one part. A single value is circular (H === V).
+  const parts = computed.trim().split(/\s+/)
+  const h = parts[0]
+  if (parts.length < 2) return { h, v: h }
+  return { h, v: parts[1] }
+}
+
+/** Whether every corner is zero (nothing to correct). */
+const isZeroRadius = (base: RadiusBase): boolean =>
+  base.every((c) => (Number.parseFloat(c.h) || 0) === 0 && (Number.parseFloat(c.v) || 0) === 0)
+
+/**
+ * Correct one radius component for `scale`. A `%` is self-correcting (a fraction
+ * of each scaled dimension) and passes through; a px value is divided by the
+ * scale so the transform renders it back to the authored px.
+ */
+const correctRadiusComponent = (value: string, scale: number): string => {
+  if (value.endsWith("%")) return value
+  const px = Number.parseFloat(value)
+  if (!Number.isFinite(px)) return value
+  return `${px / scale}px`
+}
+
+export const borderRadiusCorrector: ScaleCorrector = {
+  // Kebab-case: corrected values flow through the gate's style object, which the
+  // binding applies via `el.style.setProperty` — that requires hyphenated names
+  // (a camelCase key is silently dropped). `transform`/`opacity` work either way.
+  key: "border-radius",
+  read: (el) => {
+    const cs = getComputedStyle(el)
+    const base = CORNER_PROPS.map((p) => parseCorner((cs[p] as string) || "0px")) as unknown as RadiusBase
+    if (isZeroRadius(base)) return undefined
+    return base
+  },
+  correct: (base, sx, sy) => {
+    const corners = base as RadiusBase
+    const h = corners.map((c) => correctRadiusComponent(c.h, sx)).join(" ")
+    const v = corners.map((c) => correctRadiusComponent(c.v, sy)).join(" ")
+    // Elliptical shorthand: horizontal radii / vertical radii.
+    return `${h} / ${v}`
+  },
+}
+
+/** No corner rounded: what a twin with no radius blends from or to (ADR-0010 *Amendment (#166)*). */
+const ZERO_CORNER: CornerRadius = { h: "0px", v: "0px" }
+export const ZERO_RADIUS: unknown = [ZERO_CORNER, ZERO_CORNER, ZERO_CORNER, ZERO_CORNER] as RadiusBase
+
+/** A radius, or {@link ZERO_RADIUS} for none. */
+const orZero = (radius: unknown): RadiusBase => {
+  if (Predicate.isUndefined(radius)) return ZERO_RADIUS as RadiusBase
+  return radius as RadiusBase
+}
+
+/**
+ * One radius component between `from` and `to` at `progress` (ADR-0010 *Amendment (#166)*, Motion's
+ * `mixValues`): mixed when both are the same unit or either is 0, as a `%` when either is one, and
+ * never below 0; otherwise `to` as it is. Per frame.
+ */
+const blendComponent = (from: string, to: string, progress: number): string => {
+  const f = Number.parseFloat(from) || 0
+  const t = Number.parseFloat(to) || 0
+  const fromPercent = from.endsWith("%")
+  const toPercent = to.endsWith("%")
+  if (f !== 0 && t !== 0 && fromPercent !== toPercent) return to
+  const mixed = Math.max(f + (t - f) * progress, 0)
+  if (fromPercent || toPercent) return `${mixed}%`
+  return `${mixed}px`
+}
+
+/**
+ * A border radius between a twin's and a Lead's at `progress` (ADR-0010 *Amendment (#166)*): corner by
+ * corner and axis by axis, `undefined` standing for no radius. What {@link borderRadiusCorrector}
+ * corrects while a handover blends. Per frame.
+ */
+export const blendRadius = (from: unknown, to: unknown, progress: number): unknown => {
+  const b = orZero(to)
+  return orZero(from).map((corner, i) => blendCorner(corner, b[i], progress))
+}
+
+/** One corner between `from` and `to` at `progress`, axis by axis. Per frame. */
+const blendCorner = (from: CornerRadius, to: CornerRadius | undefined, progress: number): CornerRadius => {
+  if (Predicate.isUndefined(to)) return from
+  return { h: blendComponent(from.h, to.h, progress), v: blendComponent(from.v, to.v, progress) }
+}
+
+/**
+ * `radius` as drawn under an own scale `(sx, sy)` (ADR-0010 *Amendment (#166)*): its px components
+ * scaled, its `%` ones as they are (a fraction of the scaled box already). Per frame.
+ */
+export const scaleRadius = (radius: unknown, sx: number, sy: number): unknown => {
+  if (Predicate.isUndefined(radius)) return undefined
+  if (sx === 1 && sy === 1) return radius
+  return (radius as RadiusBase).map((corner) => ({ h: scaleComponent(corner.h, sx), v: scaleComponent(corner.v, sy) }))
+}
+
+/** One radius component under an own scale: px scaled, `%` as it is. */
+const scaleComponent = (value: string, scale: number): string => {
+  if (value.endsWith("%")) return value
+  return `${(Number.parseFloat(value) || 0) * scale}px`
+}
+
+// --- box-shadow --------------------------------------------------------------
+
+/** One parsed shadow layer: the verbatim color, the px lengths, and inset flag. */
+interface ShadowLayer {
+  readonly color: string
+  readonly offsetX: number
+  readonly offsetY: number
+  readonly blur: number
+  readonly spread: number
+  readonly inset: boolean
+  /** How many length tokens were authored (2–4), to round-trip the shape faithfully. */
+  readonly lengthCount: number
+}
+
+/** Split a `box-shadow` value into layers on TOP-LEVEL commas (ignoring `rgb(…)` commas). */
+const splitLayers = (value: string): Array<string> => {
+  const layers: Array<string> = []
+  let depth = 0
+  let start = 0
+  for (let i = 0; i < value.length; i++) {
+    const ch = value[i]
+    if (ch === "(") depth++
+    if (ch === ")") depth--
+    if (ch === "," && depth === 0) {
+      layers.push(value.slice(start, i))
+      start = i + 1
+    }
+  }
+  layers.push(value.slice(start))
+  return layers
+}
+
+/** Tokenise a layer, keeping parenthesised groups (e.g. `rgb(0, 0, 0)`) intact. */
+const tokenizeLayer = (layer: string): Array<string> => {
+  const tokens: Array<string> = []
+  let depth = 0
+  let cur = ""
+  for (const ch of layer.trim()) {
+    if (ch === "(") depth++
+    if (ch === ")") depth--
+    if (/\s/.test(ch) && depth === 0) {
+      if (cur !== "") tokens.push(cur)
+      cur = ""
+      continue
+    }
+    cur += ch
+  }
+  if (cur !== "") tokens.push(cur)
+  return tokens
+}
+
+const isLength = (t: string): boolean => Number.isFinite(Number.parseFloat(t))
+
+const parseLayer = (layer: string): ShadowLayer | undefined => {
+  const tokens = tokenizeLayer(layer)
+  if (tokens.length === 0) return undefined
+  let inset = false
+  const lengths: Array<number> = []
+  let color = ""
+  for (const t of tokens) {
+    if (t === "inset") {
+      inset = true
+      continue
+    }
+    if (isLength(t)) {
+      lengths.push(Number.parseFloat(t))
+      continue
+    }
+    color = t // a non-length, non-inset token is the color (verbatim)
+  }
+  if (lengths.length < 2) return undefined // offsetX + offsetY are required
+  return {
+    color,
+    offsetX: lengths[0],
+    offsetY: lengths[1],
+    blur: lengthAt(lengths, 2),
+    spread: lengthAt(lengths, 3),
+    inset,
+    lengthCount: lengths.length,
+  }
+}
+
+/** A shadow's `i`th length, 0 when it wasn't authored. */
+const lengthAt = (lengths: ReadonlyArray<number>, i: number): number => {
+  if (i >= lengths.length) return 0
+  return lengths[i]
+}
+
+const formatLayer = (l: ShadowLayer, sx: number, sy: number): string => {
+  const mean = (sx + sy) / 2
+  // Per-axis offsets exact; blur + spread are scalar -> axis mean (no exact value
+  // under non-uniform scale).
+  const lens = [l.offsetX / sx, l.offsetY / sy, l.blur / mean, l.spread / mean]
+    .slice(0, l.lengthCount)
+    .map((n) => `${n}px`)
+  const parts: Array<string> = []
+  if (l.inset) parts.push("inset")
+  parts.push(...lens)
+  if (l.color !== "") parts.push(l.color)
+  return parts.join(" ")
+}
+
+export const boxShadowCorrector: ScaleCorrector = {
+  key: "box-shadow", // kebab-case (see borderRadiusCorrector.key)
+  read: (el) => {
+    const value = getComputedStyle(el).boxShadow
+    if (value === "" || value === "none") return undefined
+    const layers = splitLayers(value)
+      .map(parseLayer)
+      .filter(Predicate.isNotUndefined)
+    if (layers.length === 0) return undefined
+    return layers
+  },
+  correct: (base, sx, sy) => (base as Array<ShadowLayer>).map((l) => formatLayer(l, sx, sy)).join(", "),
+}
+
+/**
+ * The default scale-corrector registry (ADR-0011). Ship `borderRadius` +
+ * `boxShadow`; a public `addScaleCorrector` API is a deferred follow-up (adding
+ * an entry here is the extension point until then).
+ */
+export const SCALE_CORRECTORS: ReadonlyArray<ScaleCorrector> = [borderRadiusCorrector, boxShadowCorrector]