@wardic/solid 1.0.0-rc.4 → 1.0.0-rc.6

package/src/live-scroll.ts

@@ -0,0 +1,125 @@
+/**
+ * `createScroll` (#518): in a module of its own, so it brings the `scroll` Feature only to an app that
+ * reads a scroll, and on the pages that do (ADR-0067, *Amendments (#548, #518)*).
+ *
+ * @module
+ */
+import * as LiveValue from "@wardic/core/LiveValue"
+import * as ScrollSource from "@wardic/core/ScrollSource"
+import type * as ScrollOffset from "@wardic/dom/ScrollOffset"
+import * as Arr from "effect/Array"
+import * as Bool from "effect/Boolean"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import * as AtomRegistry from "effect/reactivity/AtomRegistry"
+import * as Scope from "effect/Scope"
+import * as UndefinedOr from "effect/UndefinedOr"
+import { type Accessor, createEffect, createSignal, onCleanup } from "solid-js"
+import type { Feature } from "./feature.ts"
+import { scroll } from "./features/scroll.ts"
+import { serviceOf } from "./gesture-features.ts"
+import { CLOSE_FAILED, SERVER_ZERO } from "./live-value.ts"
+import * as OwnerScope from "./owner-scope.ts"
+import { useBrought, useWardicRuntime } from "./provider.tsx"
+import { isServer } from "./server.ts"
+
+/** What it brings (ADR-0067 decision 12): the `scroll` Feature, whatever its section has (#518). */
+const SCROLL: ReadonlyArray<Feature> = [scroll]
+
+/** An element, or an accessor of one, such as `() => box` for a ref: read once it's there. */
+export type ElementSource = Element | Accessor<Element | undefined>
+
+/** `createScroll`'s options, as Motion's `useScroll`'s. */
+export interface ScrollOptions {
+  /** The scrolling element, as an accessor of its ref: `() => box`. The page's scroll when left out. */
+  readonly container?: ElementSource
+  /** An element whose way through the container the progress reads, between the `offset`s. */
+  readonly target?: ElementSource
+  /**
+   * Where the progress runs, as Motion's: each stop pairs an edge of the target with an edge of the
+   * container, `["start end", "end start"]`, 0 at the first and 1 at the last. An edge is `start`,
+   * `center` or `end`, a fraction, or a length. With a target, `["start start", "end end"]` by default.
+   */
+  // The DOM's syntax (`@wardic/dom/ScrollOffset`); with a target and none given, its `All`.
+  readonly offset?: ScrollOffset.ScrollOffset
+  /** The axis `target` and `offset` read: `"y"` (the default) or `"x"`. */
+  readonly axis?: "x" | "y"
+}
+
+/** `createScroll`'s values, Motion's four, each an accessor. */
+export interface ScrollValues {
+  /** How far it's scrolled across, in pixels. */
+  readonly scrollX: Accessor<number>
+  /** How far it's scrolled down, in pixels. */
+  readonly scrollY: Accessor<number>
+  /** Its progress across, from 0 to 1: through its range, or, with a `target` or `offset`, through theirs. */
+  readonly scrollXProgress: Accessor<number>
+  /** Its progress down, from 0 to 1: through its range, or, with a `target` or `offset`, through theirs. */
+  readonly scrollYProgress: Accessor<number>
+}
+
+const SERVER_SCROLL: ScrollValues = { scrollX: SERVER_ZERO, scrollY: SERVER_ZERO, scrollXProgress: SERVER_ZERO, scrollYProgress: SERVER_ZERO }
+
+/** An element source read now: `None` for an accessor whose ref hasn't arrived. */
+const elementOf = (source: ElementSource): Option.Option<Element> =>
+  Bool.match(Predicate.isFunction(source), {
+    onTrue: () => Option.fromUndefinedOr((source as Accessor<Element | undefined>)()),
+    onFalse: () => Option.some(source as Element),
+  })
+
+/**
+ * A scroll as values: `scrollX` and `scrollY`, how far it's scrolled, in pixels, and `scrollXProgress`
+ * and `scrollYProgress`, from 0 to 1 through its range. The page's, or a `container`'s. With a
+ * `target`, the progress is the target's way through, between two `offset`s, on `axis`. Each is set in
+ * the scroll's own event, so a value derived from one paints in the frame that shows the scroll. A
+ * `container` or `target` given as an accessor of a ref reads 0s until the ref is there. 0s on a
+ * server. Motion's `useScroll`.
+ *
+ * @example
+ * let box!: HTMLDivElement
+ * const { scrollYProgress } = createScroll({ container: () => box })
+ * <div ref={box}>…</div>
+ * <w.div style={{ scaleX: scrollYProgress }} />
+ * @see https://wardic.dev/reference/solid/live-values/create-scroll
+ */
+// #234. An accessor `container` or `target` is read in an effect, and a change of either follows the
+// new one.
+export const createScroll = (options: ScrollOptions = {}): ScrollValues => {
+  const runtime = useWardicRuntime()
+  if (isServer) return SERVER_SCROLL
+  const services = useBrought(SCROLL)
+  const [scrollX, setScrollX] = createSignal(0)
+  const [scrollY, setScrollY] = createSignal(0)
+  const [scrollXProgress, setScrollXProgress] = createSignal(0)
+  const [scrollYProgress, setScrollYProgress] = createSignal(0)
+  createEffect(() => {
+    const container = UndefinedOr.match(options.container, { onUndefined: () => Option.some(undefined), onDefined: elementOf })
+    const target = UndefinedOr.match(options.target, { onUndefined: () => Option.some(undefined), onDefined: elementOf })
+    // A ref not there yet: the values hold until it is.
+    if (Bool.or(Option.isNone(container), Option.isNone(target))) return
+    const registry = runtime.runSync(AtomRegistry.AtomRegistry)
+    const scope = OwnerScope.open(runtime)
+    onCleanup(() => OwnerScope.close(runtime, scope, CLOSE_FAILED))
+    const values = runtime.runSync(
+      LiveValue.scroll({
+        ...UndefinedOr.match(Option.getOrUndefined(container), { onUndefined: () => ({}), onDefined: (element) => ({ container: element }) }),
+        ...UndefinedOr.match(Option.getOrUndefined(target), { onUndefined: () => ({}), onDefined: (element) => ({ target: element }) }),
+        ...UndefinedOr.match(options.offset, { onUndefined: () => ({}), onDefined: (offset) => ({ offset }) }),
+        ...UndefinedOr.match(options.axis, { onUndefined: () => ({}), onDefined: (axis) => ({ axis }) }),
+      }).pipe(Effect.provideService(ScrollSource.ScrollSource, serviceOf(services(), ScrollSource.ScrollSource)), Scope.provide(scope)),
+    )
+    // Each derived Atom is read at once: it tracks the scroll only once it's been read.
+    const stops = Arr.map(
+      [
+        [values.scrollX, setScrollX],
+        [values.scrollY, setScrollY],
+        [values.scrollXProgress, setScrollXProgress],
+        [values.scrollYProgress, setScrollYProgress],
+      ] as const,
+      ([atom, set]) => registry.subscribe(atom, (v) => void set(v), { immediate: true }),
+    )
+    onCleanup(() => Arr.forEach(stops, (stop) => stop()))
+  })
+  return { scrollX, scrollY, scrollXProgress, scrollYProgress }
+}

package/src/live-style.ts

@@ -28,7 +28,8 @@ import * as Bool from "effect/Boolean"
 import { constVoid } from "effect/Function"
 import * as Option from "effect/Option"
 import * as Predicate from "effect/Predicate"
-import { Atom, AtomRegistry } from "effect/reactivity"
+import * as Atom from "effect/reactivity/Atom"
+import * as AtomRegistry from "effect/reactivity/AtomRegistry"
 import * as Rec from "effect/Record"
 import * as UndefinedOr from "effect/UndefinedOr"
 import type { WardicInertia } from "./config.ts"

package/src/live-value.ts

@@ -21,17 +21,15 @@
  */
 import type * as InterpolatorRegistry from "@wardic/core/InterpolatorRegistry"
 import * as LiveValue from "@wardic/core/LiveValue"
-import type * as ScrollOffset from "@wardic/dom/ScrollOffset"
 import * as Bool from "effect/Boolean"
 import * as Effect from "effect/Effect"
 import { identity } from "effect/Function"
 import * as Predicate from "effect/Predicate"
-import { Atom, AtomRegistry } from "effect/reactivity"
+import * as Atom from "effect/reactivity/Atom"
+import * as AtomRegistry from "effect/reactivity/AtomRegistry"
 import * as UndefinedOr from "effect/UndefinedOr"
 import * as Scope from "effect/Scope"
-import * as Arr from "effect/Array"
-import * as Option from "effect/Option"
-import { type Accessor, createComputed, createEffect, createMemo, createSignal, on, onCleanup, untrack } from "solid-js"
+import { type Accessor, createComputed, createMemo, on, onCleanup, untrack } from "solid-js"
 import { eachFrameOf } from "./animation-frame.ts"
 import { fromAtom } from "./bridge.ts"
 import type { FollowAccessor, FollowValueOptions, LiveSource, SpringAccessor, WillChange } from "./live-style.ts"
@@ -45,14 +43,16 @@ import { withServerInterpolators } from "./server-interpolators.ts"
 /** A Live value as an accessor: an accessor as it is, an Atom read through the provider's registry. */
 const accessorOf = <A>(source: LiveSource<A>): Accessor<A> =>
   Bool.match(Atom.isAtom(source), {
-    onTrue: () =>
-      Bool.match(isServer, {
-        onTrue: (): Accessor<A> => () => readLive(source, serverRegistryOf, untrack) as A,
-        onFalse: () => fromAtom(source as Atom.Atom<A>),
-      }),
+    onTrue: () => atomAccessorOf(source as Atom.Atom<A>),
     onFalse: () => source as Accessor<A>,
   })
 
+/** An Atom as an accessor: on a server, read once; on the client, followed. A plain `if`, so a client build drops the server's read (#518). */
+const atomAccessorOf = <A>(atom: Atom.Atom<A>): Accessor<A> => {
+  if (isServer) return () => readLive(atom, serverRegistryOf, untrack) as A
+  return fromAtom(atom)
+}
+
 /**
  * A value mapped from another: through a function, `createTransform(x, (x) => x * 2)`, or through
  * ranges, `createTransform(x, input, output)`: a source at `input[i]` gives `output[i]`, and one between
@@ -225,7 +225,8 @@ const liveOf = <A, R>(runtime: WardicRuntime, live: Effect.Effect<Atom.Atom<A>,
   return carry(fromAtom(out), out)
 }
 
-const SERVER_ZERO: Accessor<number> = () => 0
+/** A server render's value of a Live helper: 0, and no Atom. Internal. */
+export const SERVER_ZERO: Accessor<number> = () => 0
 
 /**
  * A `will-change` for an element's `style`: `"auto"` until the element first animates a transform key,
@@ -270,101 +271,6 @@ export const createAnimationFrame = (callback: (time: number, delta: number) =>
   runtime.runSync(eachFrameOf(runtime, callback).pipe(Scope.provide(scope)))
 }
 
-/** An element, or an accessor of one, such as `() => box` for a ref: read once it's there. */
-export type ElementSource = Element | Accessor<Element | undefined>
-
-/** `createScroll`'s options, as Motion's `useScroll`'s. */
-export interface ScrollOptions {
-  /** The scrolling element, as an accessor of its ref: `() => box`. The page's scroll when left out. */
-  readonly container?: ElementSource
-  /** An element whose way through the container the progress reads, between the `offset`s. */
-  readonly target?: ElementSource
-  /**
-   * Where the progress runs, as Motion's: each stop pairs an edge of the target with an edge of the
-   * container, `["start end", "end start"]`, 0 at the first and 1 at the last. An edge is `start`,
-   * `center` or `end`, a fraction, or a length. With a target, `["start start", "end end"]` by default.
-   */
-  // The DOM's syntax (`@wardic/dom/ScrollOffset`); with a target and none given, its `All`.
-  readonly offset?: ScrollOffset.ScrollOffset
-  /** The axis `target` and `offset` read: `"y"` (the default) or `"x"`. */
-  readonly axis?: "x" | "y"
-}
-
-/** `createScroll`'s values, Motion's four, each an accessor. */
-export interface ScrollValues {
-  /** How far it's scrolled across, in pixels. */
-  readonly scrollX: Accessor<number>
-  /** How far it's scrolled down, in pixels. */
-  readonly scrollY: Accessor<number>
-  /** Its progress across, from 0 to 1: through its range, or, with a `target` or `offset`, through theirs. */
-  readonly scrollXProgress: Accessor<number>
-  /** Its progress down, from 0 to 1: through its range, or, with a `target` or `offset`, through theirs. */
-  readonly scrollYProgress: Accessor<number>
-}
-
-const SERVER_SCROLL: ScrollValues = { scrollX: SERVER_ZERO, scrollY: SERVER_ZERO, scrollXProgress: SERVER_ZERO, scrollYProgress: SERVER_ZERO }
-
-/** An element source read now: `None` for an accessor whose ref hasn't arrived. */
-const elementOf = (source: ElementSource): Option.Option<Element> =>
-  Bool.match(Predicate.isFunction(source), {
-    onTrue: () => Option.fromUndefinedOr((source as Accessor<Element | undefined>)()),
-    onFalse: () => Option.some(source as Element),
-  })
-
-/**
- * A scroll as values: `scrollX` and `scrollY`, how far it's scrolled, in pixels, and `scrollXProgress`
- * and `scrollYProgress`, from 0 to 1 through its range. The page's, or a `container`'s. With a
- * `target`, the progress is the target's way through, between two `offset`s, on `axis`. Each is set in
- * the scroll's own event, so a value derived from one paints in the frame that shows the scroll. A
- * `container` or `target` given as an accessor of a ref reads 0s until the ref is there. 0s on a
- * server. Motion's `useScroll`.
- *
- * @example
- * let box!: HTMLDivElement
- * const { scrollYProgress } = createScroll({ container: () => box })
- * <div ref={box}>…</div>
- * <w.div style={{ scaleX: scrollYProgress }} />
- * @see https://wardic.dev/reference/solid/live-values/create-scroll
- */
-// #234. An accessor `container` or `target` is read in an effect, and a change of either follows the
-// new one.
-export const createScroll = (options: ScrollOptions = {}): ScrollValues => {
-  const runtime = useWardicRuntime()
-  if (isServer) return SERVER_SCROLL
-  const [scrollX, setScrollX] = createSignal(0)
-  const [scrollY, setScrollY] = createSignal(0)
-  const [scrollXProgress, setScrollXProgress] = createSignal(0)
-  const [scrollYProgress, setScrollYProgress] = createSignal(0)
-  createEffect(() => {
-    const container = UndefinedOr.match(options.container, { onUndefined: () => Option.some(undefined), onDefined: elementOf })
-    const target = UndefinedOr.match(options.target, { onUndefined: () => Option.some(undefined), onDefined: elementOf })
-    // A ref not there yet: the values hold until it is.
-    if (Bool.or(Option.isNone(container), Option.isNone(target))) return
-    const registry = runtime.runSync(AtomRegistry.AtomRegistry)
-    const scope = OwnerScope.open(runtime)
-    onCleanup(() => OwnerScope.close(runtime, scope, CLOSE_FAILED))
-    const values = runtime.runSync(
-      LiveValue.scroll({
-        ...UndefinedOr.match(Option.getOrUndefined(container), { onUndefined: () => ({}), onDefined: (element) => ({ container: element }) }),
-        ...UndefinedOr.match(Option.getOrUndefined(target), { onUndefined: () => ({}), onDefined: (element) => ({ target: element }) }),
-        ...UndefinedOr.match(options.offset, { onUndefined: () => ({}), onDefined: (offset) => ({ offset }) }),
-        ...UndefinedOr.match(options.axis, { onUndefined: () => ({}), onDefined: (axis) => ({ axis }) }),
-      }).pipe(Scope.provide(scope)),
-    )
-    // Each derived Atom is read at once: it tracks the scroll only once it's been read.
-    const stops = Arr.map(
-      [
-        [values.scrollX, setScrollX],
-        [values.scrollY, setScrollY],
-        [values.scrollXProgress, setScrollXProgress],
-        [values.scrollYProgress, setScrollYProgress],
-      ] as const,
-      ([atom, set]) => registry.subscribe(atom, (v) => void set(v), { immediate: true }),
-    )
-    onCleanup(() => Arr.forEach(stops, (stop) => stop()))
-  })
-  return { scrollX, scrollY, scrollXProgress, scrollYProgress }
-}
 
 /** An accessor as an Atom, set as it changes, and held in `registry` until its owner's disposal. */
 const mirrorOf = <A>(accessor: Accessor<A>, registry: AtomRegistry.AtomRegistry): Atom.Writable<A> => {
@@ -375,4 +281,4 @@ const mirrorOf = <A>(accessor: Accessor<A>, registry: AtomRegistry.AtomRegistry)
 }
 
 /** What a helper's Scope reports when one of its finalizers fails as its owner goes. */
-const CLOSE_FAILED = "wardic.liveValue: a finalizer failed"
+export const CLOSE_FAILED = "wardic.liveValue: a finalizer failed"

package/src/reorder.tsx

@@ -324,6 +324,16 @@ const itemInternals = <V,>(group: ItemGroup<V>, value: V, element: Accessor<HTML
   }
 }
 
+/**
+ * An item's internals: on a server, the drag defaults with its group's touch-action, joining no
+ * controller (ADR-0021); on the client, `itemInternals`. A plain `if`, so a client build drops the
+ * server's (#518).
+ */
+const internalsOf = <V,>(group: ItemGroup<V>, value: V, element: Accessor<HTMLElement | undefined>, listens: boolean): SpineInternals => {
+  if (isServer) return { brings: ITEM_BRINGS, dragAxis: () => true, baseStyle: touchActionOf(group, listens) }
+  return itemInternals(group, value, element, useWardicRuntime(), listens)
+}
+
 /**
  * What an item adds to its element for the keyboard reorder (ADR-0037): `tabindex="0"` while the
  * group's keyboard is on and the app gave no `tabIndex` of its own, and `aria-describedby` with
@@ -378,12 +388,7 @@ export function createReorderItem<V>(group: ReorderGroup<V>, config: ReorderItem
   const value = untrack(cfg).value
   const listens = untrack(cfg).dragListener !== false
   const [element, setElement] = createSignal<HTMLElement>()
-  // On a server the item renders the drag defaults with its group's touch-action and
-  // joins no controller (ADR-0021).
-  const internals: SpineInternals = Bool.match(isServer, {
-    onTrue: (): SpineInternals => ({ brings: ITEM_BRINGS, dragAxis: () => true, baseStyle: touchActionOf(group, listens) }),
-    onFalse: () => itemInternals(group, value, element, useWardicRuntime(), listens),
-  })
+  const internals = internalsOf(group, value, element, listens)
   const ward = createWardWith(() => ({ ...withoutValue(cfg()), layout: itemLayoutOf(cfg().layout) }), internals)
   // The instructions element exists on the client only, so `aria-describedby` waits for the mount.
   const [describedBy, setDescribedBy] = createSignal<string>()

package/src/runtime.ts

@@ -30,7 +30,7 @@ import * as Layer from "effect/Layer"
 import * as ManagedRuntime from "effect/ManagedRuntime"
 import * as Option from "effect/Option"
 import * as Predicate from "effect/Predicate"
-import { AtomRegistry } from "effect/reactivity"
+import * as AtomRegistry from "effect/reactivity/AtomRegistry"
 import * as Result from "effect/Result"
 import * as UndefinedOr from "effect/UndefinedOr"
 import type { ServerAppear } from "./appear.ts"

package/src/spine.ts

@@ -48,7 +48,7 @@ import * as Match from "effect/Match"
 import * as Option from "effect/Option"
 import * as Predicate from "effect/Predicate"
 import * as Rec from "effect/Record"
-import { AtomRegistry } from "effect/reactivity"
+import * as AtomRegistry from "effect/reactivity/AtomRegistry"
 import * as UndefinedOr from "effect/UndefinedOr"
 import { enterServer, type Handoff, keyOf, type MountAnimation, repeatsForever, type ServerAppear, skippedField, startAtOf } from "./appear.ts"
 import type {

package/src/unstable/v2/bridge.ts

@@ -9,7 +9,8 @@
  */
 import * as Effect from "effect/Effect"
 import * as Predicate from "effect/Predicate"
-import { AtomRegistry, type Atom } from "effect/reactivity"
+import type * as Atom from "effect/reactivity/Atom"
+import * as AtomRegistry from "effect/reactivity/AtomRegistry"
 import * as Stream from "effect/Stream"
 import { isServer } from "@solidjs/web"
 import { type Accessor, createSignal, isHydrating, onCleanup } from "solid-js"

package/src/unstable/v2/index.ts

@@ -24,11 +24,12 @@ export {
  * only those it uses; a Complete element (`wardic.*`, `ward()`) has every one. `colors`: every CSS
  * colour space beyond a hex, `rgb()`, `hsl()` and the colour names. `layout`: layout animations, the
  * props `layout`, `layoutId`, `layoutScroll` and `layoutRoot` (`LayoutGroup` and `Reorder` bring it
- * themselves).
+ * themselves). `scroll`: a container's scroll, which `createScroll` brings itself (#518).
  */
 export type { Feature, FeatureLoad, Features, FeaturesProp } from "../../feature.ts"
 export { colors } from "../../features/colors.ts"
 export { layout } from "../../features/layout.ts"
+export { scroll } from "../../features/scroll.ts"
 /**
  * The gestures (#511, ADR-0067 decision 3), a Feature each: `hover`, `press` (its Keyboard presses
  * included), `focus`, `inView`, `pan` and `drag` (`dragControls` and the release's inertia included).
@@ -209,16 +210,13 @@ export { createAnimationControls, type WardicAnimationControls, type WardicContr
 export {
   createAnimationFrame,
   createFollowValue,
-  createScroll,
   createSpring,
   createTime,
   createTransform,
   createVelocity,
   createWillChange,
-  type ElementSource,
-  type ScrollOptions,
-  type ScrollValues,
 } from "./live-value.ts"
+export { createScroll, type ElementSource, type ScrollOptions, type ScrollValues } from "./live-scroll.ts"
 export type { FollowAccessor, FollowValueOptions, Live, LiveSource, SpringAccessor, WillChange } from "../../live-style.ts"
 
 /**

package/src/unstable/v2/layout.tsx

@@ -67,7 +67,7 @@ export function LayoutGroup(props: LayoutGroupProps): JSX.Element {
   const id = untrack(() => layoutGroupIdOf(outer, props.id, props.inherit))
   // A server render has no projection system to re-measure (ADR-0021). Not at mount: nodes measure
   // themselves as they register.
-  if (Bool.not(isServer)) {
+  if (!isServer) {
     const projection = useWardicProjection()
     // Compared before it measures, as Motion's is: an effect never compares (#618).
     const dependency = createMemo(() => props.layoutDependency, CLIENT_ONLY)

package/src/unstable/v2/live-scroll.ts

@@ -0,0 +1,137 @@
+/**
+ * `createScroll` (#518): in a module of its own, so it brings the `scroll` Feature only to an app that
+ * reads a scroll, and on the pages that do (ADR-0067, *Amendments (#548, #518)*).
+ *
+ * @module
+ */
+import * as LiveValue from "@wardic/core/LiveValue"
+import * as ScrollSource from "@wardic/core/ScrollSource"
+import type * as ScrollOffset from "@wardic/dom/ScrollOffset"
+import * as Arr from "effect/Array"
+import * as Bool from "effect/Boolean"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import * as Atom from "effect/reactivity/Atom"
+import * as AtomRegistry from "effect/reactivity/AtomRegistry"
+import * as Rec from "effect/Record"
+import * as Scope from "effect/Scope"
+import * as UndefinedOr from "effect/UndefinedOr"
+import { isServer } from "@solidjs/web"
+import { type Accessor, createEffect, createSignal, onCleanup } from "solid-js"
+import type { Feature } from "../../feature.ts"
+import { scroll } from "../../features/scroll.ts"
+import { serviceOf } from "../../gesture-features.ts"
+import * as OwnerScope from "../../owner-scope.ts"
+import { followAtom } from "./bridge.ts"
+import { CLOSE_FAILED, SERVER_ZERO } from "./live-value.ts"
+import { useBrought, useWardicRuntime } from "./provider.tsx"
+import { CLIENT_ONLY, onSettledClientOnly } from "./solid-reactivity.ts"
+
+/** What it brings (ADR-0067 decision 12): the `scroll` Feature, whatever its section has (#518). */
+const SCROLL: ReadonlyArray<Feature> = [scroll]
+
+/** An element, or an accessor of one, such as `() => box` for a ref: read once it's there. */
+export type ElementSource = Element | Accessor<Element | undefined>
+
+/** `createScroll`'s options, as Motion's `useScroll`'s. */
+export interface ScrollOptions {
+  /** The scrolling element, as an accessor of its ref: `() => box`. The page's scroll when left out. */
+  readonly container?: ElementSource
+  /** An element whose way through the container the progress reads, between the `offset`s. */
+  readonly target?: ElementSource
+  /**
+   * Where the progress runs, as Motion's: each stop pairs an edge of the target with an edge of the
+   * container, `["start end", "end start"]`, 0 at the first and 1 at the last. An edge is `start`,
+   * `center` or `end`, a fraction, or a length. With a target, `["start start", "end end"]` by default.
+   */
+  // The DOM's syntax (`@wardic/dom/ScrollOffset`); with a target and none given, its `All`.
+  readonly offset?: ScrollOffset.ScrollOffset
+  /** The axis `target` and `offset` read: `"y"` (the default) or `"x"`. */
+  readonly axis?: "x" | "y"
+}
+
+/** `createScroll`'s values, Motion's four, each an accessor. */
+export interface ScrollValues {
+  /** How far it's scrolled across, in pixels. */
+  readonly scrollX: Accessor<number>
+  /** How far it's scrolled down, in pixels. */
+  readonly scrollY: Accessor<number>
+  /** Its progress across, from 0 to 1: through its range, or, with a `target` or `offset`, through theirs. */
+  readonly scrollXProgress: Accessor<number>
+  /** Its progress down, from 0 to 1: through its range, or, with a `target` or `offset`, through theirs. */
+  readonly scrollYProgress: Accessor<number>
+}
+
+const SCROLL_KEYS = ["scrollX", "scrollY", "scrollXProgress", "scrollYProgress"] as const
+/** `createScroll`'s elements before the render has settled: none yet. */
+const NOT_YET = { container: Option.none(), target: Option.none() } as const
+const SERVER_SCROLL: ScrollValues = { scrollX: SERVER_ZERO, scrollY: SERVER_ZERO, scrollXProgress: SERVER_ZERO, scrollYProgress: SERVER_ZERO }
+
+/** An element source read now: `None` for an accessor whose ref hasn't arrived. */
+const elementOf = (source: ElementSource | undefined): Option.Option<Element | undefined> =>
+  Bool.match(Predicate.isFunction(source), {
+    onTrue: () => Option.fromUndefinedOr((source as Accessor<Element | undefined>)()),
+    onFalse: () => Option.some(source as Element | undefined),
+  })
+
+/**
+ * A scroll as values: `scrollX` and `scrollY`, how far it's scrolled, in pixels, and `scrollXProgress`
+ * and `scrollYProgress`, from 0 to 1 through its range. The page's, or a `container`'s. With a
+ * `target`, the progress is the target's way through, between two `offset`s, on `axis`. Each is set in
+ * the scroll's own event, so a value derived from one paints in the frame that shows the scroll. A
+ * `container` or `target` given as an accessor of a ref reads 0s until the ref is there. 0s on a
+ * server. Motion's `useScroll`.
+ *
+ * @example
+ * let box!: HTMLDivElement
+ * const { scrollYProgress } = createScroll({ container: () => box })
+ * <div ref={box}>…</div>
+ * <w.div style={{ scaleX: scrollYProgress }} />
+ * @see https://wardic.dev/reference/solid/live-values/create-scroll
+ */
+// #234. An accessor `container` or `target` is read in an effect, and a change of either follows the
+// new one. Each value carries one Atom for its life.
+export const createScroll = (options: ScrollOptions = {}): ScrollValues => {
+  if (isServer) return SERVER_SCROLL
+  const runtime = useWardicRuntime()
+  const services = useBrought(SCROLL)
+  const registry = runtime.runSync(AtomRegistry.AtomRegistry)
+  // Its own four Atoms, set from the scroll of the elements there now.
+  const outs = Rec.fromIterableWith(SCROLL_KEYS, (key) => [key, Atom.make(0)] as const)
+  Arr.forEach(SCROLL_KEYS, (key) => onCleanup(registry.mount(outs[key])))
+  // Its elements are read once the render has settled: a ref given as `() => box` is set during the
+  // render, after this effect's first compute, and isn't a signal, so nothing would read it again.
+  const [settled, setSettled] = createSignal(false)
+  onSettledClientOnly(() => {
+    setSettled(true)
+  })
+  createEffect(
+    () =>
+      Bool.match(settled(), {
+        onTrue: () => ({ container: elementOf(options.container), target: elementOf(options.target) }),
+        onFalse: () => NOT_YET,
+      }),
+    ({ container, target }) => {
+      // A ref not there yet: the values hold until it is.
+      if (Bool.or(Option.isNone(container), Option.isNone(target))) return undefined
+      const scope = OwnerScope.open(runtime)
+      const values = runtime.runSync(
+        LiveValue.scroll({
+          ...UndefinedOr.match(Option.getOrUndefined(container), { onUndefined: () => ({}), onDefined: (element) => ({ container: element }) }),
+          ...UndefinedOr.match(Option.getOrUndefined(target), { onUndefined: () => ({}), onDefined: (element) => ({ target: element }) }),
+          ...UndefinedOr.match(options.offset, { onUndefined: () => ({}), onDefined: (offset) => ({ offset }) }),
+          ...UndefinedOr.match(options.axis, { onUndefined: () => ({}), onDefined: (axis) => ({ axis }) }),
+        }).pipe(Effect.provideService(ScrollSource.ScrollSource, serviceOf(services(), ScrollSource.ScrollSource)), Scope.provide(scope)),
+      )
+      // Each derived Atom is read at once: it tracks the scroll only once it's been read.
+      const stops = Arr.map(SCROLL_KEYS, (key) => registry.subscribe(values[key], (v) => registry.set(outs[key], v), { immediate: true }))
+      return () => {
+        Arr.forEach(stops, (stop) => stop())
+        OwnerScope.close(runtime, scope, CLOSE_FAILED)
+      }
+    },
+    CLIENT_ONLY,
+  )
+  return Rec.map(outs, (atom) => followAtom(registry, atom)) as unknown as ScrollValues
+}