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

package/src/internal/own-values.ts

@@ -0,0 +1,166 @@
+/**
+ * Base values in the DOM (ADR-0022): an element's Own value for a key, and the `style` link's
+ * lookup. A binding calls these and hands them to core's `BaseValue.of` / `BaseValue.start`, so a
+ * new binding writes no DOM code for them (the thin-bindings rule). Tier 2, for binding
+ * authors.
+ *
+ * Client-only: the read runs after mount, never during a server render (ADR-0021, "Nothing
+ * reads the DOM on a server"). `styleValueOf` and `valueLike` are pure.
+ *
+ * Observability: per element and cold (once per key), so quiet; the spine logs what it
+ * started from and returned to.
+ */
+import * as BaseValue from "@wardic/core/BaseValue"
+import * as Interpolator from "@wardic/core/Interpolator"
+import * as Bool from "effect/Boolean"
+import * as Match from "effect/Match"
+import * as MutableRef from "effect/MutableRef"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import * as Str from "effect/String"
+import { parseCssText } from "./starting-style.ts"
+import { dashCase, isSvgInner, svgAttrNameOf } from "./svg.ts"
+
+/** An element's own value for a key: the raw value read, a string, a transform key's identity, or `None`. */
+export type OwnValue = (key: string) => Option.Option<number | string>
+
+/**
+ * A reader of `element`'s own values, each read once, the first time it's needed, and kept, a miss too,
+ * so a later CSS change doesn't move it, as Motion's. For each key:
+ * 1. a transform key: its identity, with no read;
+ * 2. on an SVG element inside an `<svg>`, a key it takes as an attribute: that attribute, if it has one;
+ * 3. else its computed style, a custom property by its own name.
+ *
+ * Making a reader reads nothing, and a read from an element not in the document isn't kept. Values read
+ * are raw strings: `valueLike` reads one in a target's shape.
+ */
+// Motion's C12. A transform key: Motion's projected branch, HTMLVisualElement.ts:51 at
+// 16c61222c4166bbef5ff6ab0051192faa79fa8c8. An attribute: ADR-0014's routing.
+export const ownValues = (element: Element): OwnValue => {
+  const cache = new Map<string, Option.Option<number | string>>()
+  // The element's computed style, read once, at the first key that needs it.
+  const computed = MutableRef.make(Option.none<CSSStyleDeclaration>())
+  const computedStyle = (): CSSStyleDeclaration =>
+    Option.getOrElse(MutableRef.get(computed), () => {
+      const style = getComputedStyle(element)
+      MutableRef.set(computed, Option.some(style))
+      return style
+    })
+  // On an svg-inner element, the attribute the key is written as, if it has one.
+  const attributeOf = (key: string): Option.Option<string> =>
+    Bool.match(isSvgInner(element), {
+      onTrue: () => Option.flatMap(svgAttrNameOf(key), (name) => nonEmpty(element.getAttribute(name))),
+      onFalse: () => Option.none(),
+    })
+  const read = (key: string): Option.Option<number | string> =>
+    Option.orElse(BaseValue.transformIdentity(key), () =>
+      Option.orElse(attributeOf(key), () => nonEmpty(computedStyle().getPropertyValue(dashCase(key)).trim()))
+    )
+  return (key) =>
+    Option.getOrElse(Option.fromUndefinedOr(cache.get(key)), () => {
+      const value = read(key)
+      // An element not in the document has an empty computed style: that miss isn't the
+      // element's, so it isn't kept, and the key is read again once the element is in.
+      if (element.isConnected) cache.set(key, value)
+      return value
+    })
+}
+
+/** A read string, `None` when there's none or it's empty. */
+const nonEmpty = (value: string | null): Option.Option<string> => Option.filter(Option.fromNullOr(value), Str.isNonEmpty)
+
+/**
+ * The app's `style` value for `key`: from an object style by the key, then by the key dash-cased; from a
+ * CSS-text style, parsed as `Style.over` parses it. `undefined`, `null` and an empty string are `None`. A
+ * transform key, `x`, `scale`, `rotate`, is Wardic's, as Motion's is: a binding draws it into `transform`.
+ * The value is as given, so a binding reads a live value, an Atom or an accessor, itself.
+ *
+ * @example
+ * OwnValues.styleValueOf({ opacity: 0.5 }, "opacity") // Some(0.5)
+ */
+// The `style` link of a Base value. #130, ADR-0043 decision 4: through the flush gate.
+export const styleValueOf = (style: object | string | undefined, key: string): Option.Option<unknown> =>
+  Option.flatMap(
+    Option.fromNullishOr(style),
+    (given) => {
+      const map = recordOf(given)
+      // A value at `k`: `undefined`, `null` and an empty string are misses.
+      const at = (k: string): Option.Option<unknown> =>
+        Option.filter(
+          Option.flatMap(Option.liftPredicate(k, (name: string) => Object.hasOwn(map, name)), (name) => Option.fromNullishOr(map[name])),
+          (value) => value !== "",
+        )
+      // A custom property by its own name only; any other key then dash-cased.
+      return Option.orElse(at(key), () =>
+        Option.flatMap(Option.liftPredicate(dashCase(key), (dashed: string) => Bool.not(key.startsWith("--")) && dashed !== key), at)
+      )
+    },
+  )
+
+/** The last CSS text parsed, and its record. */
+// Module state (#460, Q7): a one-entry cache keyed by the text it parsed, read only: a Retarget asks
+// for each of a style's keys in a row, and parsed the whole text again for each (#618, F6).
+let last: { readonly text: string; readonly record: Readonly<Record<string, unknown>> } = { text: "", record: {} }
+
+/** `text` parsed, once for as long as it's the text asked for. */
+const parsedOnce = (text: string): Readonly<Record<string, unknown>> => {
+  if (text === last.text) return last.record
+  last = { text, record: parseCssText(text) }
+  return last.record
+}
+
+/** A style given as CSS text, parsed; a record as it is. */
+const recordOf: (style: object | string) => Readonly<Record<string, unknown>> = Match.type<object | string>().pipe(
+  Match.when(Predicate.isString, parsedOnce),
+  Match.orElse((record) => record as Readonly<Record<string, unknown>>),
+)
+
+/** A plain number, or a number in `px`. */
+const NUMERIC = /^\s*-?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?(px)?\s*$/i
+
+/**
+ * `raw` in the shape of a key's target `like`, or `None` when it can't be:
+ * - **A number target** takes a finite number, or a plain number or a `px` string, parsed (`"0.5"` is
+ *   0.5, `"120px"` 120). Anything else misses, `auto`, `50%`, `1em`, a colour, so the key starts at its
+ *   target. On a key that places or sizes the box, a miss of another type, `auto` or `50%`, is a Measured
+ *   pair instead: both ends are measured in px, as Motion's are.
+ * - **A string target** takes a string as it is, or a finite number as a string, but not a length in a
+ *   unit other than the target's (`"120px"` for `"0%"`), which can't blend with it.
+ */
+// A **Measured pair** (#430, `measured-pairs.ts`): its binding keeps the start. The unit interpolator dies
+// on a pair of two units, so it misses, as a numeric target misses `50%`.
+export const valueLike = (raw: unknown, like: number | string): Option.Option<number | string> => valueLikeOf({ raw, like })
+
+// The matchers are built once, at module load, not per call: a start reads every key's (#69).
+/** A plain number, or a number in `px`, as a numeric target takes it. */
+const isNumericString = (raw: unknown): raw is string => Predicate.isString(raw) && NUMERIC.test(raw)
+
+/** `raw` for a numeric target: a finite number, or a plain-number or `px` string, parsed. */
+const numericLike: (raw: unknown) => Option.Option<number> = Match.type<unknown>().pipe(
+  Match.when(Match.number, (n) => Option.liftPredicate(n, Number.isFinite)),
+  Match.when(isNumericString, (s) => Option.some(Number.parseFloat(s))),
+  Match.orElse(() => Option.none()),
+)
+
+/** `raw` for a string target `like`: a string as is unless its unit clashes with the target's, or a finite number as a string. */
+const stringLike: (pair: { readonly raw: unknown; readonly like: string }) => Option.Option<string> = Match.type<{
+  readonly raw: unknown
+  readonly like: string
+}>().pipe(
+  Match.when({ raw: Match.string }, ({ raw, like }) => Option.liftPredicate(raw, (given: string) => Bool.not(unitsClash(like, given)))),
+  Match.when({ raw: Match.number }, ({ raw }) => Option.map(Option.liftPredicate(raw, Number.isFinite), String)),
+  Match.orElse(() => Option.none()),
+)
+
+const valueLikeOf: (pair: { readonly raw: unknown; readonly like: number | string }) => Option.Option<number | string> = Match.type<{
+  readonly raw: unknown
+  readonly like: number | string
+}>().pipe(
+  Match.when({ like: Match.number }, ({ raw }): Option.Option<number | string> => numericLike(raw)),
+  // The rest have a string target.
+  Match.orElse((pair): Option.Option<number | string> => stringLike(pair as { readonly raw: unknown; readonly like: string })),
+)
+
+/** Whether `raw` is a length in another unit than `like`'s (both have a unit, and they differ). */
+const unitsClash = (like: string, raw: string): boolean =>
+  Option.exists(Interpolator.unitOf(like), (want) => want !== "" && Option.exists(Interpolator.unitOf(raw), (got) => got !== "" && got !== want))

package/src/internal/pass-ends.ts

@@ -0,0 +1,23 @@
+/**
+ * One Projection system's Measure-pass ends, for the Reorder controller (ADR-0020): the engine's Layer
+ * provides it beside the engine, and `ReorderController.make` requires it. Not exported from
+ * `@wardic/dom`, so there's no public push hook (ADR-0020 decision 2).
+ *
+ * @internal
+ */
+// #618 (decision 12): the controller found the engine's listeners in a WeakMap keyed by the engine
+// object, so a wrapped or replaced ProjectionSystem in the context silently heard no pass end.
+import * as Context from "effect/Context"
+
+/** `onPassEnd(listener)` runs `listener` at the end of every Measure pass, and returns the unsubscribe. */
+export class PassEnds extends Context.Service<
+  PassEnds,
+  {
+    /**
+     * Run `listener` at the end of every Measure pass: once per pass, after every round's boxes are
+     * stored (a blocked pass and one whose flush triggered more rounds included). A listener that
+     * throws is logged and doesn't stop the pass or the others.
+     */
+    readonly onPassEnd: (listener: () => void) => () => void
+  }
+>()("@wardic/dom/PassEnds") {}

package/src/internal/positional-keys.ts

@@ -0,0 +1,24 @@
+/**
+ * The DOM Environment's Positional keys (CONTEXT.md; ADR-0029, ADR-0036): the transforms, and the
+ * box's position and size as CSS names them, `width`, `height`, `top`, `left`, `right` and `bottom`
+ * (Motion's `positionalKeys`). Reduced motion Snaps these. Core names only the transforms; these
+ * box keys are CSS's, so they're the DOM's. `DomLive` provides the Layer.
+ *
+ * @module
+ */
+import * as ReducedMotion from "@wardic/core/ReducedMotion"
+import * as Layer from "effect/Layer"
+import * as Predicate from "effect/Predicate"
+import { dashCase } from "./svg.ts"
+
+/** The box's position and size, as CSS properties. */
+const BOX_KEYS: ReadonlySet<string> = new Set(["width", "height", "top", "left", "right", "bottom"])
+
+/** A key of the box's position or size, written as a CSS name or in camelCase. */
+const isBoxKey: Predicate.Predicate<string> = (key) => BOX_KEYS.has(dashCase(key))
+
+/** Whether reduced motion lands `key` at once: a transform, or a key that places or sizes the box. */
+export const isPositional: Predicate.Predicate<string> = Predicate.or(ReducedMotion.isTransform, isBoxKey)
+
+/** The DOM Environment's `ReducedMotion.PositionalKeys`. */
+export const PositionalKeysDomLive: Layer.Layer<ReducedMotion.PositionalKeys> = Layer.succeed(ReducedMotion.PositionalKeys, { isPositional })

package/src/internal/probe.ts

@@ -0,0 +1,176 @@
+/**
+ * `ProbeDomLive` — the browser realization of `Probe`: measurement
+ * (`getBoundingClientRect`), reactive viewport size, the `prefers-reduced-motion`
+ * preference, whether the page is shown (`document.visibilityState`, #443), and per-target
+ * resize/intersection observation streams.
+ *
+ * The writable Atoms (`viewport`, `prefersReducedMotion`, `pageVisible`) are pinned with
+ * `keepAlive` and written through the
+ * Environment's {@link AtomRegistry} captured at build time — the same registry
+ * a consumer reads `Probe.viewport`/`Probe.prefersReducedMotion` from — so the
+ * `make`/event path can update them without leaking an `AtomRegistry`
+ * requirement into the `Probe` interface. The window `resize`, the
+ * `MediaQueryList` `change` and the document's `visibilitychange` listeners are the only writers, forked into the
+ * layer's scope so they live exactly as long as the Layer.
+ *
+ * Per CONTEXT.md's **Shared source** contract, `observeResize` goes through core's
+ * `SharedSource.byTarget`: one `ResizeObserver` per target, ref-counted — the observer is
+ * constructed and `observe()`d on the first subscriber and `disconnect()`ed when the last
+ * unsubscribes. `observeIntersection` is an **Input feed** (#318) making one `IntersectionObserver`
+ * per subscriber, since each may ask its own root, margin and amount (#273, Motion's `viewport`).
+ *
+ * Observability (CONTEXT.md observability convention): core's `SharedSource` already
+ * carries a `wardic.sharedSource.*` span + a debug-log on subscribe; the hot
+ * `measure`/viewport-write paths stay quiet.
+ */
+import type * as InputFeed from "@wardic/core/InputFeed"
+import * as Probe from "@wardic/core/Probe"
+import * as SharedSource from "@wardic/core/SharedSource"
+import * as Arr from "effect/Array"
+import * as Bool from "effect/Boolean"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import * as Queue from "effect/Queue"
+import * as Stream from "effect/Stream"
+import * as UndefinedOr from "effect/UndefinedOr"
+import { Atom, AtomRegistry } from "effect/reactivity"
+import { requireGlobal } from "./require-global.ts"
+import { makeScroll } from "./scroll.ts"
+
+/** Map a `DOMRect`-like value onto the engine's portable {@link Bounds}. */
+/** An `IntersectionObserver`'s init from the Probe's options: each left out when not given. */
+const observerInit = (options: Probe.IntersectionOptions): IntersectionObserverInit => ({
+  ...UndefinedOr.match(options.root as Element | Document | undefined, { onUndefined: () => ({}), onDefined: (root) => ({ root }) }),
+  ...UndefinedOr.match(options.margin, { onUndefined: () => ({}), onDefined: (rootMargin) => ({ rootMargin }) }),
+  ...UndefinedOr.match(options.amount, { onUndefined: () => ({}), onDefined: (threshold) => ({ threshold }) }),
+})
+
+const toBounds = (r: DOMRect): Probe.Bounds => ({
+  x: r.x,
+  y: r.y,
+  width: r.width,
+  height: r.height,
+  top: r.top,
+  right: r.right,
+  bottom: r.bottom,
+  left: r.left,
+})
+
+/**
+ * Captures the Environment's {@link AtomRegistry} and adds the window's `resize` listener and
+ * the media query's `change` listener in the layer scope; each is the sole writer of its Atom.
+ * The `resize` listener writes `viewport` inside the event (ADR-0018, *Amendment (#45)*).
+ * `Layer.effect` runs `make` in the layer's own scope (it `Exclude`s `Scope`),
+ * which the shared helpers' `RcMap`s and the forked listeners need.
+ */
+const make = Effect.gen(function* () {
+  // Client-only (ADR-0021, decision 7): the viewport below reads `window`.
+  yield* requireGlobal("DomProbe.layer", "window")
+
+  // The shared Environment registry — the one consumers read these atoms from.
+  const registry = yield* AtomRegistry.AtomRegistry
+
+  // --- viewport -----------------------------------------------------------
+  // `keepAlive` pins the node so the value the resize listener writes survives
+  // between reads (an idle node with no subscriber would be GC'd and re-init).
+  const viewport = Atom.keepAlive(
+    Atom.make<Probe.Viewport>({ width: window.innerWidth, height: window.innerHeight }),
+  )
+  // The window's "resize" listener is the only writer of `viewport`, and it writes inside the
+  // event (ADR-0018, *Amendment (#45)*): a reader, the projection system's Resize block among
+  // them, sees the new size within the dispatch, not a scheduler hop later, before the frame's
+  // Measure pass. A forked Stream consumer would land a task after the event.
+  const writeViewport = (): void => registry.set(viewport, { width: window.innerWidth, height: window.innerHeight })
+  yield* Effect.acquireRelease(
+    Effect.sync(() => window.addEventListener("resize", writeViewport)),
+    () => Effect.sync(() => window.removeEventListener("resize", writeViewport)),
+  )
+
+  // --- prefersReducedMotion ----------------------------------------------
+  // Guard `matchMedia` (absent in some headless environments): default false.
+  const mql = Bool.match(Predicate.isFunction(window.matchMedia), {
+    onTrue: () => Option.some(window.matchMedia("(prefers-reduced-motion: reduce)")),
+    onFalse: () => Option.none<MediaQueryList>(),
+  })
+  const prefersReducedMotion = Atom.keepAlive(Atom.make(Option.exists(mql, (query) => query.matches)))
+  if (Option.isSome(mql)) {
+    // The MediaQueryList's `change` listener is the Atom's only writer, and it writes inside the
+    // event, as `viewport`'s and `pageVisible`'s do: a reader sees the new preference before the next
+    // frame (#618, M8: a fiber over `Stream.fromEventListener` set it a task later).
+    const query = mql.value
+    const writeReduced = (event: MediaQueryListEvent): void => registry.set(prefersReducedMotion, event.matches)
+    yield* Effect.acquireRelease(
+      Effect.sync(() => query.addEventListener("change", writeReduced)),
+      () => Effect.sync(() => query.removeEventListener("change", writeReduced)),
+    )
+  }
+
+  // --- pageVisible (#443) ---------------------------------------------------
+  // The document's `visibilitychange` listener is its only writer, and it writes inside the event,
+  // as `viewport`'s does: a reader sees the page hidden before the next frame.
+  const pageVisible = Atom.keepAlive(Atom.make(document.visibilityState !== "hidden"))
+  const writePageVisible = (): void => registry.set(pageVisible, document.visibilityState !== "hidden")
+  yield* Effect.acquireRelease(
+    Effect.sync(() => document.addEventListener("visibilitychange", writePageVisible)),
+    () => Effect.sync(() => document.removeEventListener("visibilitychange", writePageVisible)),
+  )
+
+  // --- observeResize ------------------------------------------------------
+  // One ResizeObserver per target, ref-counted via `SharedSource.byTarget`. The
+  // observer is constructed on the first subscriber; `Effect.addFinalizer`
+  // disconnects it when the last subscriber's scope closes.
+  const observeResize = yield* SharedSource.byTarget<Probe.Bounds>((target) =>
+    Effect.succeed(
+      Stream.callback<Probe.Bounds>((queue) =>
+        Effect.gen(function* () {
+          const el = target as Element
+          const ro = new ResizeObserver(() => {
+            Queue.offerUnsafe(queue, toBounds(el.getBoundingClientRect()))
+          })
+          ro.observe(el)
+          yield* Effect.addFinalizer(() => Effect.sync(() => ro.disconnect()))
+        })
+      )
+    )
+  )
+
+  // --- observeIntersection ------------------------------------------------
+  // An Input feed (#318) with one IntersectionObserver per subscriber, against its options (#273,
+  // Motion's `viewport`): the root (the viewport when none), the margin (`rootMargin`) and the amount
+  // (`threshold`). Each report carries the entry.
+  const observeIntersection =
+    (target: unknown, options: Probe.IntersectionOptions = {}): InputFeed.InputFeed<Probe.Intersection> => (emit) => {
+      const io = new IntersectionObserver(
+        (entries) => Arr.forEach(entries, (entry) => emit({ intersecting: entry.isIntersecting, raw: entry })),
+        observerInit(options),
+      )
+      io.observe(target as Element)
+      return () => io.disconnect()
+    }
+
+  return Probe.Probe.of({
+    // Hot path — intentionally unlogged/un-spanned.
+    measure: (target) => Effect.sync(() => toBounds((target as Element).getBoundingClientRect())),
+    viewport,
+    prefersReducedMotion,
+    pageVisible,
+    // A container's scroll, set within its events (#234): `scroll.ts`.
+    scroll: yield* makeScroll(registry),
+    observeResize,
+    observeIntersection,
+  })
+})
+
+/**
+ * Core's `Probe` on the DOM. It needs the Environment's `AtomRegistry`, which it writes the viewport's
+ * size, the reduced-motion preference and whether the page is shown through, and readers read them from;
+ * `DomLive` provides it. Building it on a server fails, with an error that says it's client-only.
+ */
+// Built with `Layer.effect`, so `make` runs in the layer's scope: the shared helpers' `RcMap`s and the
+// forked listeners live for the layer's lifetime; `testLayer` provides the registry the same way.
+// ADR-0021, decision 7.
+export const ProbeDomLive: Layer.Layer<Probe.Probe, never, AtomRegistry.AtomRegistry> = Layer.effect(
+  Probe.Probe,
+)(make)

package/src/internal/projection-defaults.ts

@@ -0,0 +1,45 @@
+/**
+ * Motion's default layout and drag transitions, apart from the Projection system: a binding's layout
+ * element code reads them on every page, and the engine, `projection.ts`, ships only where an app lays
+ * out.
+ */
+// ADR-0009 *Amendment (#171)*, ADR-0016 *Amendment (#140)*; #548; ADR-0067, *Amendment (#548)*.
+import type * as Machine from "@wardic/core/Machine"
+
+/**
+ * A layout animation's transition: a spring, its fields and its `delay`; or a tween, its `duration`,
+ * `ease` and `delay`. A repeat means nothing for a flight that lands once. A tween with no `duration` or
+ * `ease` takes the tween's own defaults, 0.3 s and linear (a binding fills Motion's `easeOut` first).
+ */
+// ADR-0009 *Amendment (#171)*; #360; ADR-0051.
+export type LayoutTransition = ({ readonly type: "spring" } & Machine.SpringOptions) | ({ readonly type: "tween" } & Machine.TweenOptions)
+
+/**
+ * Motion's default layout transition (motion-dom 13.3.0, `defaultLayoutTransition`): a 0.45 s tween,
+ * eased `cubic-bezier(0.4, 0, 0.1, 1)`, so a layout animation lands on time.
+ */
+// ADR-0009 *Amendment (#171)*.
+export const DEFAULT_LAYOUT_TRANSITION: LayoutTransition = { type: "tween", duration: 0.45, ease: [0.4, 0, 0.1, 1] }
+
+/**
+ * A drag's release (Motion's `dragTransition`): the inertia a node's Release offset runs on, with both
+ * edges at its slot, so it springs back there on the bounce. Times in seconds. Its edges are the slot's,
+ * never its own.
+ */
+// ADR-0016, *Amendment (#140)*.
+export type DragTransition = Omit<Machine.InertiaOptions, "min" | "max">
+
+/**
+ * Motion's drag transition (framer-motion 13.4.0, `VisualElementDragControls.startAnimation`), with its
+ * default `dragElastic`: a 0.75 s time constant, power 0.8, the bounce 200 / 40, at rest within 1 px and
+ * 10 px/s. A node's Release offset runs on it when it's given none.
+ */
+// ADR-0016, *Amendment (#140)*.
+export const DEFAULT_DRAG_TRANSITION: DragTransition = {
+  power: 0.8,
+  timeConstant: 0.75,
+  bounceStiffness: 200,
+  bounceDamping: 40,
+  restDelta: 1,
+  restSpeed: 10,
+}