@wardic/solid 0.0.0-stage → 1.0.0-rc.1

package/src/stagger.ts

@@ -0,0 +1,31 @@
+/**
+ * `stagger()` (#436, Motion's): a child's delay from its index and the count, for a transition's
+ * `delayChildren` or `createAnimate`'s `delay`. Solid-free, on both bindings.
+ *
+ * @module
+ */
+import type * as Easing from "@wardic/core/Easing"
+import * as Stagger from "@wardic/core/Stagger"
+import type { WardicStagger } from "./config.ts"
+
+/** `stagger()`'s options (Motion's `StaggerOptions`). */
+export interface WardicStaggerOptions {
+  /** Seconds before the first child's delay. Default 0. */
+  readonly startDelay?: number
+  /** The child the delay grows from: `"first"`, `"last"`, `"center"` or an index. Default the first. */
+  readonly from?: Stagger.Origin
+  /** How the delay grows across the children, eased across `duration × count`, as Motion's. Default linear. */
+  readonly ease?: Easing.Definition
+}
+
+/**
+ * Delays each child by its place: each waits `startDelay`, plus `duration` for each step from `from`,
+ * eased by `ease`. Give it as a transition's `delayChildren`, where it decides each variant child's
+ * whole delay, or as `createAnimate`'s `delay`. Motion's `stagger()`.
+ *
+ * @example
+ * <w.ul animate="shown" variants={list} transition={{ delayChildren: stagger(0.05, { from: "center" }) }}>…</w.ul>
+ * @see https://wardic.dev/reference/solid/transitions/stagger
+ */
+// #436.
+export const stagger = (duration = 0.1, options: WardicStaggerOptions = {}): WardicStagger => Stagger.make(duration, options)

package/src/unstable/v2/bridge.ts

@@ -0,0 +1,79 @@
+/**
+ * Reactive bridges on Solid 2 (#209, ADR-0006), as the Solid 1 binding's: `streamToSignal` runs a
+ * core `Stream` into a signal for as long as its owner lives, and `fromAtom` reads an Effect `Atom`
+ * through the provider's registry. Their signals are written from outside Solid (a fiber, the
+ * registry), so a change shows at Solid 2's next flush. `fromAtom`'s accessor carries its Atom
+ * (#209 PR 3's Q2), so a `style` given it follows the Atom itself, in the frame the Atom is set.
+ *
+ * @module
+ */
+import * as Effect from "effect/Effect"
+import * as Predicate from "effect/Predicate"
+import { AtomRegistry, type Atom } from "effect/reactivity"
+import * as Stream from "effect/Stream"
+import { isServer } from "@solidjs/web"
+import { type Accessor, createSignal, isHydrating, onCleanup } from "solid-js"
+import { carry } from "../../live-style.ts"
+import type { WardicServices } from "../../runtime.ts"
+import { runScoped, useWardicRuntime } from "./provider.tsx"
+import { onSettledClientOnly } from "./solid-reactivity.ts"
+
+/**
+ * A core `Stream` as an accessor: `initial` until its first value, then its latest, the stream run on
+ * the provider's runtime until the owner is cleaned up. Call it where you'd make a signal.
+ *
+ * @example
+ * const point = streamToSignal(pointerMoves, { x: 0, y: 0 })
+ * @see https://wardic.dev/reference/solid/advanced/bridges
+ */
+// `Stream.runForEach` through `runScoped`; `set(() => v)`, so an object or function value is stored as
+// it is. The stream's `R` is the provider runtime's services.
+export const streamToSignal = <A>(stream: Stream.Stream<A, never, WardicServices>, initial: A): Accessor<A> => {
+  const runtime = useWardicRuntime()
+  const [value, setValue] = createSignal<A>(initial as Exclude<A, Function>)
+  runScoped(runtime, Stream.runForEach(stream, (next) => Effect.sync(() => setValue(() => next))))
+  return value
+}
+
+/**
+ * `atom` as an accessor carrying it: a signal set from `registry` at each change, unsubscribed when
+ * the owner is disposed. Every Atom the binding hands to Solid goes through it (a ward's `read`, the
+ * Live-value helpers, `fromAtom`). Call it where you'd make a signal.
+ */
+export const followAtom = <A>(registry: AtomRegistry.AtomRegistry, atom: Atom.Atom<A>): Accessor<A> => {
+  const [value, setValue] = createSignal<A>(registry.get(atom) as Exclude<A, Function>)
+  onCleanup(registry.subscribe(atom, (next) => setValue(() => next as Exclude<A, Function>)))
+  // eslint-disable-next-line solid/reactivity -- the accessor itself is returned, for its caller to read where it tracks
+  return carry(value, atom)
+}
+
+/**
+ * An Effect `Atom` as an accessor: read through the provider's `AtomRegistry`, and followed until the
+ * owner is cleaned up. For a server render, give `serverValue`: the server renders it, and a hydrating
+ * page keeps it until it has settled, then follows the atom. It carries the Atom, so a `style` given it
+ * follows the Atom itself.
+ *
+ * @example
+ * const visible = fromAtom(probe.pageVisible, { serverValue: true })
+ * @see https://wardic.dev/reference/solid/advanced/bridges
+ */
+// Solid's `from`, seeded with the atom's value; `set(() => v)`, so an object or function value is stored
+// as it is. A server builds no registry (ADR-0021); the Hydration hold is decision 8.
+export const fromAtom = <A>(atom: Atom.Atom<A>, options?: { readonly serverValue?: A }): Accessor<A> => {
+  const runtime = useWardicRuntime()
+  const held = Predicate.isNotUndefined(options) && "serverValue" in options
+  if (held && isServer) {
+    const serverValue = options.serverValue as A
+    return () => serverValue
+  }
+  if (held && isHydrating()) {
+    const [value, setValue] = createSignal<A>(options.serverValue as Exclude<A, Function>)
+    onSettledClientOnly(() => {
+      const registry = runtime.runSync(AtomRegistry.AtomRegistry)
+      setValue(() => registry.get(atom))
+      return registry.subscribe(atom, (next) => setValue(() => next))
+    })
+    return value
+  }
+  return followAtom(runtime.runSync(AtomRegistry.AtomRegistry), atom)
+}

package/src/unstable/v2/complete.ts

@@ -0,0 +1,47 @@
+/**
+ * The **Complete element**'s own code on Solid 2 (#511, ADR-0067; #548): what tells a ward it brings
+ * every Feature, and `ward()`, the Complete ward. In a module of its own, apart from the ward every
+ * element shares, so an app whose pages use the Slim element (`w.*`) ships no Feature from here, even
+ * when one of them uses a Complete element (ADR-0067, *Amendment (#548)*).
+ *
+ * @module
+ */
+import * as Predicate from "effect/Predicate"
+import { ALL } from "../../features/all.ts"
+import { internalsOf, type Ward, type WardChecked, type WardConfig, type WardInternals, wardWith, type WardOptions } from "./ward.tsx"
+
+/**
+ * What a **Complete element** tells its ward (#511, ADR-0067): it brings every Feature. Its forms'
+ * (`ward()`, `wardic.*`, `wardic.create`) alone: a Slim element's never name it.
+ */
+export const COMPLETE: WardInternals = { brings: ALL, complete: true }
+
+/** No config: a ward that only listens (#398), `ward()`. */
+const NO_CONFIG: WardConfig = {}
+
+/**
+ * Makes a ward: Wardic's motion for an element of your own. Spread it on the element, `{...card}`, or
+ * give it to a Wardic element's `wardRef`. Each key of `config` is a value or an accessor of it.
+ * `card.read(key)` reads what the element shows, and `card.next("tap")`, `card.when("tap")` hear its
+ * events. With no config, it only listens. This one has every Feature; `w.ward` has its section's.
+ *
+ * @example
+ * const card = ward({ initial: { opacity: 0 }, animate: { opacity: 1 } })
+ * <article {...card} />
+ * @see https://wardic.dev/reference/solid/elements/ward
+ */
+// `config` is read per key (#259): a value, an accessor, a getter, a store's property or a component's
+// prop (`ward(props)`). Made where you'd make a signal, under a WardicProvider. Its config's type is
+// kept, so `read` and `atom` complete the keys it animates. With no config (#398) it listens: spread on
+// a plain element, its gestures' events with no motion; given to `wardRef`, the element's props set it.
+// A Complete element (#511).
+export function ward<const C extends WardConfig>(config: WardChecked<C>, options?: WardOptions): Ward<C>
+export function ward(): Ward<{}>
+export function ward(config: undefined, options: WardOptions): Ward<{}>
+// Overloads, not an optional `config` (#398): a default for `C` left an accessor's literal untyped
+// (`transition: () => ({ type: "tween" })` read `type` as a string), as `C` fell back to it.
+export function ward(config?: WardConfig, options?: WardOptions): Ward {
+  // Plain checks: every ward is made through here, and a match's objects would cost each (#349).
+  if (Predicate.isUndefined(config)) return wardWith(NO_CONFIG, internalsOf(options, COMPLETE))
+  return wardWith(config, internalsOf(options, COMPLETE))
+}

package/src/unstable/v2/config-view.ts

@@ -0,0 +1,156 @@
+/**
+ * A config read per key (#259, ADR-0045 *Amendment (#259)*): what the Solid 2 binding's `ward()`,
+ * `reorderGroup()` and `reorderItem()` read their config through.
+ *
+ * - **Per key.** Reading a key of the view reads that key of the source, so Solid tracks it alone: a
+ *   getter, a store's property or a component's prop is tracked as it's read. A change re-runs only
+ *   the computations that read that key, where an accessor of the whole config re-ran them all.
+ * - **A function is an accessor,** called as it's read (so tracked too): `ward({ animate: () => … })`.
+ *   The callback keys (`onUpdate`, `onReorder`…) hold functions as their values, and are read as they are.
+ * - **A plain value is a constant,** as a literal prop is.
+ *
+ * The view is one object over the source, its getters on a prototype made once per kind of config,
+ * so making one allocates no getters. It has no keys of its own: it is read, never spread. A setup
+ * read (a read-once key: `initial`, `drag`, `layout`) goes through {@link snapshotOf}, untracked, or
+ * {@link setupOf}, which notes the keys still loading rather than throwing (#257 item 1).
+ *
+ * An accessor that returns a promise is an error naming its key (#257 item 1, Q3): an accessor is
+ * called at every read of its key, so it would fetch again at each; an async memo (`createMemo(() =>
+ * fetch…)`) caches it, and is read as any other accessor.
+ *
+ * @module
+ */
+import * as Arr from "effect/Array"
+import * as Bool from "effect/Boolean"
+import { identity } from "effect/Function"
+import * as Predicate from "effect/Predicate"
+import * as UndefinedOr from "effect/UndefinedOr"
+import { latest, NotReadyError, runWithOwner, untrack } from "solid-js"
+import type { Accessor } from "solid-js"
+
+/**
+ * A config whose keys may each be an accessor (#259): a key's value, or a function returning it,
+ * except the callback keys `K`, whose values are functions themselves.
+ */
+export type PerKey<C, K extends keyof C = never> = {
+  readonly [P in keyof C]: P extends K ? C[P] : C[P] | Accessor<C[P]>
+}
+
+/**
+ * {@link PerKey}, declared apart, its rule and its accessor written out again: the same config, a
+ * type of its own. A ward's config checks its other keys against it (`WardChecked`, #306). Against
+ * `PerKey`'s own type, which the config is also bound by, TS met each key's type while it was still
+ * working it out, read it as `any`, and an editor completed nothing inside `style` or `viewport`.
+ * A rule or an `Accessor<…>` shared between the two did the same, as TS shares their instantiations.
+ */
+export type PerKeyApart<C, K extends keyof C = never> = {
+  readonly [P in keyof C]: P extends K ? C[P] : C[P] | (() => C[P])
+}
+
+/** A view's state: the source it reads, and the values it fixes over it. */
+class View {
+  constructor(
+    readonly source: Readonly<Record<string, unknown>>,
+    readonly fixed: Readonly<Record<string, unknown>> | undefined,
+  ) {}
+}
+
+/** `key`'s value in a view: its fixed one, else its source's. */
+const valueAt = (view: View, key: string): unknown => {
+  const fixed = view.fixed
+  if (Predicate.isNotUndefined(fixed)) {
+    if (Object.hasOwn(fixed, key)) return fixed[key]
+  }
+  return view.source[key]
+}
+
+/** A config's values fixed over a source's: each a value or an accessor of it, read as the source's are. */
+export type Fixed<C> = { readonly [K in keyof C]?: C[K] | Accessor<C[K]> }
+
+/** How to make and copy one kind of config's views: its keys, read per key. */
+export interface ConfigView<C> {
+  /**
+   * A view of `source`, with `fixed`'s values over it (a key it fixes isn't read from the source),
+   * each read as the source's are. Its reads are tracked where they're read.
+   */
+  readonly of: (source: object, fixed?: Fixed<C>) => C
+  /** A plain copy of a view's keys as they are now, read untracked: the config at setup. */
+  readonly snapshotOf: (view: C) => C
+  /**
+   * {@link snapshotOf}, a key still loading left out of the copy and named in `pending` (#257 item 1):
+   * its read threw Solid's `NotReadyError`. Read with no reader, so nothing re-runs when it lands;
+   * the ward's tracked reads of it (its target, its style) wait on it instead.
+   */
+  readonly setupOf: (view: C) => Setup<C>
+}
+
+/** A config at setup: the keys read, and those still loading (#257 item 1). */
+export interface Setup<C> {
+  readonly config: C
+  readonly pending: ReadonlyArray<keyof C & string>
+}
+
+/** No key still loading: most setups. */
+const NONE_PENDING: ReadonlyArray<never> = []
+
+/** The error for an accessor that returned a promise (#257 item 1, Q3). */
+const promiseError = (key: string): Error =>
+  new Error(`\`${key}\`'s accessor returned a promise: give it an async memo instead, \`${key}: createMemo(() => …)\`. An accessor is called at every read of its key, so it would fetch at each.`)
+
+
+/**
+ * The views of a config with `keys`, its `callbacks` read as they are: a class of {@link View}
+ * whose prototype has a getter a key, made once per kind, at module load.
+ */
+export const configView = <C extends object>(keys: ReadonlyArray<keyof C & string>, callbacks: ReadonlyArray<keyof C & string>): ConfigView<C> => {
+  class KindView extends View {}
+  Arr.forEach(keys, (key) => {
+    const called = Bool.not(Arr.contains(callbacks, key))
+    Object.defineProperty(KindView.prototype, key, {
+      enumerable: true,
+      get(this: View): unknown {
+        const value = valueAt(this, key)
+        if (Bool.not(Bool.and(called, Predicate.isFunction(value)))) return value
+        const result = (value as () => unknown)()
+        if (Predicate.isPromiseLike(result)) throw promiseError(key)
+        return result
+      },
+    })
+  })
+  const snapshot = (view: C): C =>
+    Arr.reduce(keys, {} as Record<string, unknown>, (copy, key) => {
+      const value = (view as Record<string, unknown>)[key]
+      if (Predicate.isNotUndefined(value)) copy[key] = value
+      return copy
+    }) as C
+  // The setup copy: a key whose read throws `NotReadyError` is left out and named.
+  const setup = (view: C): Setup<C> => {
+    let pending: Array<keyof C & string> | undefined
+    const config = Arr.reduce(keys, {} as Record<string, unknown>, (copy, key) => {
+      let value: unknown
+      try {
+        value = (view as Record<string, unknown>)[key]
+      } catch (error) {
+        if (Bool.not(error instanceof NotReadyError)) throw error
+        if (Predicate.isUndefined(pending)) pending = []
+        pending.push(key)
+        return copy
+      }
+      if (Predicate.isNotUndefined(value)) copy[key] = value
+      return copy
+    }) as C
+    return { config, pending: UndefinedOr.match(pending, { onUndefined: () => NONE_PENDING, onDefined: identity }) }
+  }
+  return {
+    of: (source, fixed) => new KindView(source as Record<string, unknown>, fixed as Record<string, unknown> | undefined) as unknown as C,
+    snapshotOf: (view) => untrack(() => snapshot(view)),
+    // With no reader, and untracked: Solid links a pending node to the reader of an untracked read,
+    // re-running it when the node settles, so a component's body read would re-run the render that
+    // made it, making its async source again (#257 item 1). With none, the read just throws.
+    // `untrack` also lifts the dev build's strict read of a component body, which would throw first.
+    // And under `latest` (#335): a read outside the update's owner tree sees the values from before
+    // it, so a `<Show>`'s narrowed accessor read `undefined`; `latest` reads the in-flight ones, as
+    // the element's own render does.
+    setupOf: (view) => runWithOwner(null, () => untrack(() => latest(() => setup(view)))),
+  }
+}

package/src/unstable/v2/create-animate.ts

@@ -0,0 +1,123 @@
+/**
+ * `createAnimate()` on Solid 2 (#433, Motion's `useAnimate`): the Solid 1 binding's, its **Animation
+ * scope** with an async value of its own, `scope.settled()` (#433's Q8): pending while any animation
+ * it started is in flight, so `isPending(() => scope.settled())` reads "animating", as a ward's
+ * `settled()` does (ADR-0046).
+ *
+ * @module
+ */
+import { isServer } from "@solidjs/web"
+import * as Predicate from "effect/Predicate"
+import * as UndefinedOr from "effect/UndefinedOr"
+import { type Accessor, createMemo, createSignal, getOwner, onCleanup, runWithOwner } from "solid-js"
+import {
+  type AnimateEnv,
+  type AnimationWatch,
+  scopedAnimate,
+  scopeOf,
+  serverAnimate,
+  type WardicAnimate,
+  type WardicAnimationScope,
+  type WardicPlaybackControls,
+} from "../../imperative.ts"
+import { useWardicDefaultTransition, useWardicGate, useWardicPositionalKeys, useWardicReducedMotion, useWardicRuntime, useWardicSkipAnimations } from "./provider.tsx"
+import { CLIENT_ONLY } from "./solid-reactivity.ts"
+
+/** A scope's landing: the animation that landed last, as `scope.settled()` gives it. */
+// #433's Q8: held in an object, as the controls are awaitable, which an async value would wait on
+// rather than hold.
+export interface WardicScopeLanding {
+  readonly animation: WardicPlaybackControls
+}
+
+/** An animation scope on Solid 2: Solid 1's, with `settled()`. */
+// #433.
+export interface WardicAnimationScopeV2<T extends Element = HTMLElement> extends WardicAnimationScope<T> {
+  /**
+   * Its last landing, `undefined` before the first: an async value, pending while any animation it
+   * started is in flight, as a ward's `settled()` is, so `isPending(() => scope.settled())` reads
+   * "animating". One stopped or cancelled ends its flight without landing.
+   */
+  readonly settled: () => WardicScopeLanding | undefined
+}
+
+/** `scope.settled()` (#433's Q8): its animations in flight, counted, made reactive at its first read. */
+const settledOf = (): { readonly watch: AnimationWatch; readonly read: () => WardicScopeLanding | undefined } => {
+  const owner = getOwner()
+  let flying = 0
+  let last: WardicScopeLanding | undefined
+  let setCount: ((count: number) => void) | undefined
+  let memo: Accessor<WardicScopeLanding | undefined> | undefined
+  let waiting: ((landed: WardicScopeLanding | undefined) => void) | undefined
+  const tell = (): void => {
+    UndefinedOr.map(setCount, (set) => set(flying))
+  }
+  // Its count starts at none in flight, so its first read is never pending; one in flight then is
+  // set from a microtask, as a ward's Retarget in flight is: a start comes in Solid's flush.
+  const make = (): Accessor<WardicScopeLanding | undefined> => {
+    const [count, set] = createSignal(0)
+    setCount = set
+    const made = createMemo((): WardicScopeLanding | undefined | PromiseLike<WardicScopeLanding | undefined> => {
+      if (count() === 0) return last
+      return new Promise<WardicScopeLanding | undefined>((resolve) => {
+        waiting = resolve
+      })
+    }, CLIENT_ONLY)
+    if (flying > 0) queueMicrotask(tell)
+    return made
+  }
+  const watch: AnimationWatch = {
+    started: () => {
+      flying++
+      if (Predicate.isNotUndefined(setCount)) queueMicrotask(tell)
+    },
+    ended: (controls, landed) => {
+      flying--
+      if (landed) last = { animation: controls }
+      if (flying > 0) return
+      const resolve = waiting
+      waiting = undefined
+      UndefinedOr.map(resolve, (done) => done(last))
+      tell()
+    },
+  }
+  const read = (): WardicScopeLanding | undefined => {
+    if (Predicate.isUndefined(memo)) memo = runWithOwner(owner, make)
+    return (memo as Accessor<WardicScopeLanding | undefined>)()
+  }
+  return { watch, read }
+}
+
+/**
+ * Animates elements from code, Wardic's and plain ones alike: returns a scope, given to an element's
+ * `ref`, and `animate`. `animate(subject, target, options?)` animates an element, the elements a
+ * selector finds inside the scope, or a list; `animate(sequence)` plays a sequence. Each returns its
+ * playback controls, which can be awaited. `scope.settled()` is pending while its animations are in
+ * flight. Call it in a component under a `WardicProvider`; the component's cleanup stops its
+ * animations. Motion's `useAnimate`.
+ *
+ * @example
+ * const [scope, animate] = createAnimate()
+ * const reveal = () => animate("li", { opacity: [0, 1] }, { delay: stagger(0.05) })
+ * <button disabled={isPending(() => scope.settled())} onClick={reveal}>Reveal</button>
+ * <ul ref={scope}>…</ul>
+ * @see https://wardic.dev/reference/solid/animation/create-animate
+ */
+// #433, as Solid 1's; `settled()` is #433's Q8, as a ward's (ADR-0046).
+export function createAnimate<T extends Element = HTMLElement>(): readonly [WardicAnimationScopeV2<T>, WardicAnimate] {
+  const settled = settledOf()
+  const made = scopeOf<T>(settled.watch)
+  const scope = Object.defineProperty(made.scope, "settled", { value: settled.read }) as WardicAnimationScopeV2<T>
+  // A server animates nothing (#433's defaults).
+  if (isServer) return [scope, serverAnimate] as const
+  const env: AnimateEnv = {
+    runtime: useWardicRuntime(),
+    gate: useWardicGate(),
+    reducedMotion: useWardicReducedMotion(),
+    skipAnimations: useWardicSkipAnimations(),
+    positionalKeys: useWardicPositionalKeys(),
+    defaultTransition: useWardicDefaultTransition(),
+  }
+  onCleanup(made.stopAll)
+  return [scope, scopedAnimate(env, () => scope.current, made.watch)] as const
+}

package/src/unstable/v2/cycle.ts

@@ -0,0 +1,33 @@
+/**
+ * `createCycle` on Solid 2 (#443, Motion's `useCycle`), as Solid 1's.
+ *
+ * @module
+ */
+import { type Accessor, createSignal } from "solid-js"
+import { nextIndexOf } from "../../cycle-index.ts"
+import type { Cycle } from "../../cycle.ts"
+
+export type { Cycle } from "../../cycle.ts"
+
+/**
+ * One of a list of values at a time: the first to begin with, and `cycle()` steps to the next, the
+ * first after the last. `cycle(i)` goes to index `i`. Two steps in one handler step twice. Motion's
+ * `useCycle`, its value an accessor.
+ *
+ * @example
+ * const [x, cycleX] = createCycle(0, 50, 100)
+ * <w.div animate={{ x: x() }} onClick={() => cycleX()} />
+ * @see https://wardic.dev/reference/solid/utilities/create-cycle
+ */
+// #443. The index is kept outside the signal too, as Motion keeps it in a ref; `cycle(i)` is taken as
+// given, unchecked, and anything but a number steps, as Motion's (`typeof next !== "number"`).
+export const createCycle = <T,>(...items: ReadonlyArray<T>): readonly [Accessor<T>, Cycle] => {
+  let current = 0
+  const [index, setIndex] = createSignal(0)
+  const cycle: Cycle = (next) => {
+    current = nextIndexOf(current, items.length, next)
+    setIndex(current)
+  }
+  // eslint-disable-next-line solid/reactivity -- the accessor itself is returned, for its caller to read where it tracks
+  return [() => items[index()] as T, cycle]
+}

package/src/unstable/v2/drag-sensor.ts

@@ -0,0 +1,44 @@
+/**
+ * `createDrag` (#548): in a module of its own, so it brings the `drag` Feature only to an app that uses it,
+ * and on the pages that do (ADR-0067, *Amendment (#548)*).
+ *
+ * @module
+ */
+import type * as Drag from "@wardic/core/Drag"
+import * as InputSource from "@wardic/core/InputSource"
+import * as Effect from "effect/Effect"
+import { type CreateDragOptions, watchDragSamples } from "../../drag-samples.ts"
+import type { Feature } from "../../feature.ts"
+import { drag } from "../../features/drag.ts"
+import { inputIn } from "../../gesture-features.ts"
+import { transformPagePointOf } from "../../wardic-config-value.ts"
+import { useBrought } from "./provider.tsx"
+import { type Sensor, watchSensorOf } from "./sensors.ts"
+import { useWardicConfig } from "./wardic-config.tsx"
+
+/** What it brings (ADR-0067 decision 12): its gesture's Feature, whatever its section has (#511). */
+const DRAG: ReadonlyArray<Feature> = [drag]
+
+/**
+ * The latest sample of a drag on the element it's given to as a `ref`, `null` before the first: where
+ * the pointer is, how far it has come, its velocity, and the gesture's `phase`. It moves nothing: it
+ * reports, for a drag that drives something else, such as a slider's value. Like an element's own
+ * drag, it takes the element's drag while a gesture is on, unless `claim: false`.
+ *
+ * @example
+ * const drag = createDrag({ axis: "x" })
+ * const value = () => (drag()?.offset.x ?? 0) / 2
+ * <div class="track" ref={drag} />
+ * @see https://wardic.dev/reference/solid/gestures/create-drag
+ */
+// The core drag watch (#379), with `options`' axis, claim and bounds; the element's Drag claim held
+// while a gesture is on.
+export const createDrag = (options?: CreateDragOptions): Sensor<Drag.Sample | null> => {
+  // Its points through the nearest WardicConfig's `transformPagePoint` (#443), read at each down.
+  const pagePoint = transformPagePointOf(useWardicConfig())
+  const services = useBrought(DRAG)
+  return watchSensorOf<Drag.Sample | null>(
+    (target, handlers) => Effect.provideService(watchDragSamples(target, { ...options }, handlers, pagePoint), InputSource.InputSource, inputIn(services())),
+    null,
+  )
+}