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

package/src/features/layout.ts

@@ -0,0 +1,54 @@
+/**
+ * The **`layout` Feature** (#511, ADR-0067 decisions 3 and 15): the projection system (ADR-0009), in a
+ * module of its own, so an app that never imports it ships none of it. It's what a Slim element's
+ * `layout`, `layoutId` and `layoutScroll` need, and the shared-element crossfades and Switches between
+ * `layoutId` twins (ADR-0010). Its top-level calls are marked pure, as `colors`' are.
+ *
+ * @module
+ */
+import type * as Announcer from "@wardic/core/Announcer"
+import * as DomProjectionSystem from "@wardic/dom/DomProjectionSystem"
+import * as FlushGate from "@wardic/dom/FlushGate"
+import * as ProjectionSystem from "@wardic/dom/ProjectionSystem"
+import type * as ReorderController from "@wardic/dom/ReorderController"
+import type * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as UndefinedOr from "effect/UndefinedOr"
+import type { Feature } from "../feature.ts"
+import { ProjectionOptions, projectionIn, type WardicContextValue } from "../runtime.ts"
+
+/**
+ * Layout animations: a provider's projection system, built once for the provider, over its
+ * flush gate and with its reduced motion and scale correctors. Every section with it shares it, as the
+ * projection tree is the page's: a `layoutId` pair in two sections still crossfades.
+ */
+export const layout: Feature<ProjectionSystem.ProjectionSystem, ProjectionSystem.Shape> = {
+  name: "layout",
+  key: ProjectionSystem.ProjectionSystem,
+  // The engine, and what its Reorder controllers hear each Measure pass by, beside it (#618).
+  layer: /*#__PURE__*/ Layer.effectContext(
+    /*#__PURE__*/ Effect.flatMap(FlushGate.FlushGate, (gate) => Effect.flatMap(ProjectionOptions, (options) => DomProjectionSystem.make(gate, options))),
+  ),
+}
+
+/** What `layout` brings: the projection system, and what a Reorder controller over it takes beside it. */
+export type LayoutServices = Exclude<ReorderController.Services, Announcer.Announcer>
+
+/** What a component that brings `layout` asks its provider for: one list, so the provider joins it once. */
+const BRINGS: ReadonlyArray<Feature> = [layout]
+
+/**
+ * The projection system of `value`'s provider, its `layout` Feature built now if nothing has built it
+ * yet (#511, decision 12): what a component that brings it works with (`LayoutGroup`, `Reorder`,
+ * `createProjectionNode`), whatever its section has. A clear error during a server render, which builds
+ * none (ADR-0021).
+ */
+export const projectionBrought = (value: WardicContextValue): ProjectionSystem.Shape =>
+  UndefinedOr.getOrThrowWith(projectionIn(value.features.build(BRINGS)), () => new Error("useWardicProjection: there is no projection system during a server render (ADR-0021)"))
+
+/** {@link projectionBrought}'s services, all of them: what a Reorder controller is built with (#618). */
+export const layoutBrought = (value: WardicContextValue): Context.Context<LayoutServices> => {
+  projectionBrought(value)
+  return value.features.build(BRINGS) as Context.Context<LayoutServices>
+}

package/src/features/pan.ts

@@ -0,0 +1,17 @@
+/**
+ * The **`pan` Feature** (#511, ADR-0067 decision 3): an element's pan (`onPan`, `onPanStart`, `onPanSessionStart`, `onPanEnd`; Solid 2's `"pan"` events), in a module of its own, so an app that
+ * never imports it ships none of it. Its top-level calls are marked pure, as every Feature module's are.
+ *
+ * @module
+ */
+import * as DragRecognizer from "@wardic/core/DragRecognizer"
+import type { Feature } from "../feature.ts"
+import { PanGesture } from "./keys.ts"
+import { gestureLayer, withInput } from "./input.ts"
+
+/** Pan gestures: the pan callbacks. */
+export const pan: Feature<PanGesture, PanGesture["Service"]> = {
+  name: "pan",
+  key: PanGesture,
+  layer: /*#__PURE__*/ gestureLayer(PanGesture, (source) => ({ watch: withInput(source, DragRecognizer.watchPan) })),
+}

package/src/features/press.ts

@@ -0,0 +1,17 @@
+/**
+ * The **`press` Feature** (#511, ADR-0067 decision 3): an element's press, its Keyboard presses included (`whileTap`, `onTap…`; Solid 2's `"tap"` events), in a module of its own, so an app that
+ * never imports it ships none of it. Its top-level calls are marked pure, as every Feature module's are.
+ *
+ * @module
+ */
+import type { Feature } from "../feature.ts"
+import { PressGesture } from "./keys.ts"
+import { watchPressOn } from "../press.ts"
+import { gestureLayer, withInput } from "./input.ts"
+
+/** Press gestures, a pointer's and the keyboard's: `whileTap` and the tap callbacks. */
+export const press: Feature<PressGesture, PressGesture["Service"]> = {
+  name: "press",
+  key: PressGesture,
+  layer: /*#__PURE__*/ gestureLayer(PressGesture, (source) => ({ watch: withInput(source, watchPressOn) })),
+}

package/src/focus-sensor.ts

@@ -0,0 +1,32 @@
+/**
+ * `createFocus` (#548): in a module of its own, so it brings the `focus` Feature only to an app that uses it,
+ * and on the pages that do (ADR-0067, *Amendment (#548)*).
+ *
+ * @module
+ */
+import type { Accessor } from "solid-js"
+import { watchToSignal } from "./bridge.ts"
+import type { Feature } from "./feature.ts"
+import { focus } from "./features/focus.ts"
+import { FocusGesture } from "./features/keys.ts"
+import { serviceOf } from "./gesture-features.ts"
+import { useBrought } from "./provider.tsx"
+
+/** What it brings (ADR-0067 decision 12): its gesture's Feature, whatever its section has (#511). */
+const FOCUS: ReadonlyArray<Feature> = [focus]
+
+/**
+ * `true` while `target` has focus, `false` once it loses it, however it got it: a pointer's click
+ * counts, where `whileFocus` counts only a focus the browser shows. `target` is the element itself, so
+ * call it where it exists.
+ *
+ * @example
+ * const focused = createFocus(props.input)
+ * <p class="hint" hidden={!focused()}>Press Enter to search</p>
+ * @see https://wardic.dev/reference/solid/gestures/create-focus
+ */
+// The core focus watch (#318), not `visible` only. `false` until its first transition.
+export const createFocus = (target: unknown): Accessor<boolean> => {
+  const services = useBrought(FOCUS)
+  return watchToSignal<boolean>((handlers) => serviceOf(services(), FocusGesture).watch(target, {}, handlers), false)
+}

package/src/frame-time.ts

@@ -0,0 +1,45 @@
+/**
+ * The time a key's velocity is read against (#464, Motion's `sync-time.ts`): its provider's Clock's
+ * `now` (#460, Q7), read once per synchronous block and kept until a microtask clears it, so every
+ * sink a tick runs, and a Retarget in the same task, read one time. A browser's is `performance.now()`;
+ * a test Environment's, its own advances.
+ *
+ * @module
+ */
+import * as Clock from "@wardic/core/Clock"
+import * as Effect from "effect/Effect"
+import * as Predicate from "effect/Predicate"
+import type { WardicRuntime } from "./runtime.ts"
+
+/**
+ * How long a key's velocity holds once nothing has moved it, in ms (Motion's `MAX_VELOCITY_DELTA`):
+ * past it, the key is at rest. A velocity worked out from two frames further apart takes this as their
+ * time apart.
+ */
+export const MAX_VELOCITY_DELTA = 30
+
+/** A frame at 60 Hz, in ms: the time a leg's first frame is read over, from where it started (Motion's first-frame delta). */
+export const NOMINAL_FRAME = 1000 / 60
+
+/**
+ * The time now, in ms: the same for the rest of this synchronous block (core's `Clock.syncNow`).
+ * Per frame: a check, and a read once a tick. A Snapshot's time until its spine gives it its
+ * provider's ({@link clockNowOf}).
+ */
+export const frameNow: () => number = Clock.syncNow(() => performance.now())
+
+/** Each runtime's Clock's `now`, read once. */
+// Module state (#460, Q7): each runtime's clock, held weakly by the runtime.
+const clockNows = new WeakMap<WardicRuntime, () => number>()
+
+/**
+ * The time a provider's elements read their velocities against (#460, Q7): its Environment's Clock's
+ * `now` (#464's sync time in a browser; a test Environment's own advances), kept per runtime.
+ */
+export const clockNowOf = (runtime: WardicRuntime): (() => number) => {
+  const kept = clockNows.get(runtime)
+  if (Predicate.isNotUndefined(kept)) return kept
+  const read = runtime.runSync(Clock.Clock.use((clock) => Effect.succeed(clock.now)))
+  clockNows.set(runtime, read)
+  return read
+}

package/src/gesture-callbacks.ts

@@ -0,0 +1,212 @@
+/**
+ * Solid 1's gesture callbacks (#273, ADR-0047): Motion's `onHoverStart`, `onTap`, `onDragEnd` and the
+ * rest, told from the recognizers' events and the drag track's samples. Motion's `(event, info)`: the
+ * platform's own event core carried through (`raw`), then the info (`gesture-info.ts`), its point in
+ * the viewport. Each is read from the config when it's called, at the event. One that throws is
+ * reported (`wardic.gesture: onTap failed`), and the gesture goes on.
+ *
+ * Which gestures an element runs follows Motion's features (`definitions.ts:5-24` @ `16c6122`): the
+ * hover recognizer once `whileHover`, `onHoverStart` or `onHoverEnd` is set, the press recognizer once
+ * `whileTap`, `onTap`, `onTapStart` or `onTapCancel` is, the pan recognizer once a pan callback is.
+ *
+ * @module
+ */
+import type * as Drag from "@wardic/core/Drag"
+import type * as DragRecognizer from "@wardic/core/DragRecognizer"
+import type * as Recognizer from "@wardic/core/Recognizer"
+import * as Report from "@wardic/dom/Report"
+import * as Bool from "effect/Boolean"
+import * as Cause from "effect/Cause"
+import * as Effect from "effect/Effect"
+import * as Match from "effect/Match"
+import * as Predicate from "effect/Predicate"
+import * as UndefinedOr from "effect/UndefinedOr"
+import type { WardConfig, WardicViewport } from "./config.ts"
+import { dragInfoOf, pointInfoOf, pointOfSample, pressInfoOf, type WardicPressEvent } from "./gesture-info.ts"
+import type { WardicRuntime } from "./runtime.ts"
+
+/**
+ * Every key the `wants*` below read (#525): an element given none of them, its keys fixed, can never
+ * want a gesture, so it starts no computation to watch for one. `gesture-keys.ssr.test.tsx` checks
+ * each of them turns its gesture on.
+ */
+export const GESTURE_KEYS = [
+  "whileHover",
+  "onHoverStart",
+  "onHoverEnd",
+  "whileTap",
+  "onTap",
+  "onTapStart",
+  "onTapCancel",
+  "onPan",
+  "onPanStart",
+  "onPanSessionStart",
+  "onPanEnd",
+  "whileInView",
+  "onViewportEnter",
+  "onViewportLeave",
+  "whileFocus",
+] as const satisfies ReadonlyArray<keyof WardConfig>
+
+/**
+ * Whether `config` runs the hover recognizer (Motion's hover feature). Read at every config change of
+ * an element that doesn't run it yet: statement `if`s, no array (ADR-0025).
+ */
+export const wantsHover = (config: WardConfig): boolean => {
+  if (Predicate.isNotUndefined(config.whileHover)) return true
+  if (Predicate.isNotUndefined(config.onHoverStart)) return true
+  return Predicate.isNotUndefined(config.onHoverEnd)
+}
+
+/** Whether `config` runs the press recognizer (Motion's tap feature): as {@link wantsHover}. */
+export const wantsPress = (config: WardConfig): boolean => {
+  if (Predicate.isNotUndefined(config.whileTap)) return true
+  if (Predicate.isNotUndefined(config.onTap)) return true
+  if (Predicate.isNotUndefined(config.onTapStart)) return true
+  return Predicate.isNotUndefined(config.onTapCancel)
+}
+
+/** Whether `config` runs the pan recognizer (Motion's pan feature, #273): as {@link wantsHover}. */
+export const wantsPan = (config: WardConfig): boolean => {
+  if (Predicate.isNotUndefined(config.onPan)) return true
+  if (Predicate.isNotUndefined(config.onPanStart)) return true
+  if (Predicate.isNotUndefined(config.onPanSessionStart)) return true
+  return Predicate.isNotUndefined(config.onPanEnd)
+}
+
+/** Whether `config` runs the in-view recognizer (Motion's inView feature, #273): `whileInView` or a viewport callback. */
+export const wantsInView = (config: WardConfig): boolean => {
+  if (Predicate.isNotUndefined(config.whileInView)) return true
+  if (Predicate.isNotUndefined(config.onViewportEnter)) return true
+  return Predicate.isNotUndefined(config.onViewportLeave)
+}
+
+/** Whether `config` runs the focus recognizer (Motion's focus feature, #273): `whileFocus`. */
+export const wantsFocus = (config: WardConfig): boolean => Predicate.isNotUndefined(config.whileFocus)
+
+/** Motion's `amount` as a share of the element: `"some"` any of it, `"all"` all of it. */
+const amountOf = (amount: "some" | "all" | number | undefined): number | undefined =>
+  Match.value(amount).pipe(
+    Match.when("some", () => 0),
+    Match.when("all", () => 1),
+    Match.orElse((share) => share),
+  )
+
+/** Motion's `viewport` as core's in-view options (#273): its root read now, when the recognizer starts. */
+export const inViewOptionsOf = (viewport: WardicViewport | undefined): Recognizer.InViewOptions =>
+  UndefinedOr.match(viewport, {
+    onUndefined: () => ({}),
+    onDefined: (v) => ({
+      once: v.once,
+      margin: v.margin,
+      amount: amountOf(v.amount),
+      ...UndefinedOr.match(v.root, { onUndefined: () => ({}), onDefined: (root) => ({ root: root() }) }),
+    }),
+  })
+
+/** What tells an element's gestures to its config's callbacks. */
+export interface GestureCallbacks {
+  readonly hovered: (edge: Recognizer.Edge) => void
+  readonly pressed: (press: Recognizer.PressEvent, element: Element) => void
+  readonly dragged: (sample: Drag.Sample) => void
+  /** The drag's release came to rest on its own. */
+  readonly released: () => void
+  readonly panned: (sample: DragRecognizer.PanSample) => void
+  /** An in-view edge: `onViewportEnter` or `onViewportLeave`, with the platform's entry. */
+  readonly viewed: (edge: Recognizer.ViewEdge) => void
+}
+
+/** Each press phase's callback: a press a drag took over has none (Motion tells neither). */
+const PRESS_CALLBACK = { start: "onTapStart", tap: "onTap", cancel: "onTapCancel", dragged: undefined } as const
+
+/** Each drag phase's callback, `onDrag` aside. */
+const DRAG_CALLBACK = { start: "onDragStart", move: undefined, end: "onDragEnd" } as const
+
+/** Each pan phase's callback past its session's start, `onPan` aside. */
+const PAN_CALLBACK = { start: "onPanStart", move: undefined, end: "onPanEnd" } as const
+
+/** A drag's or a pan's start or end callback. */
+type MovementCallback = "onDragStart" | "onDragEnd" | "onPanStart" | "onPanEnd"
+
+/** An element's callers, reading `config` at each call; `id` names it in a report. */
+export const gestureCallbacksOf = (runtime: WardicRuntime, id: string, config: () => WardConfig): GestureCallbacks => {
+  // The per-move callbacks whose last call threw (#257 item 4): a run of throws reports at its
+  // first, so one that throws at every move logs once; a call that returns ends the run.
+  let failing: Set<string> | undefined
+  /** Report the app's `name` threw `defect`. */
+  const report = (name: string, defect: unknown): void => {
+    runtime.runFork(Report.failure(`wardic.gesture: ${name} failed`, Cause.die(defect)).pipe(Effect.annotateLogs({ id })))
+  }
+  /** Call the app's `name`, reported if it throws. */
+  const call = <Args extends ReadonlyArray<unknown>>(name: string, callback: ((...args: Args) => void) | undefined, ...args: Args): void => {
+    if (Predicate.isUndefined(callback)) return
+    try {
+      callback(...args)
+    } catch (defect) {
+      report(name, defect)
+    }
+  }
+  /** Call `onDrag` or `onPan`, at every move: a run of throws is reported at its first. */
+  const callPerMove = <Args extends ReadonlyArray<unknown>>(name: string, callback: ((...args: Args) => void) | undefined, ...args: Args): void => {
+    if (Predicate.isUndefined(callback)) return
+    try {
+      callback(...args)
+      UndefinedOr.map(failing, (names) => names.delete(name))
+    } catch (defect) {
+      if (Predicate.isUndefined(failing)) failing = new Set()
+      if (failing.has(name)) return
+      failing.add(name)
+      report(name, defect)
+    }
+  }
+  /**
+   * A drag's or a pan's sample, past a pan's session's start: its start's or its end's callback
+   * (`named`), then `every`, which hears its start and each move (Motion's pan session runs `onMove`
+   * at the start too). The info is built once, for whichever is set.
+   */
+  const moved = (named: MovementCallback | undefined, every: "onDrag" | "onPan", sample: Drag.Sample): void => {
+    const c = config()
+    const own = UndefinedOr.map(named, (key) => c[key])
+    const moving = sample.phase !== "end"
+    const each = c[every]
+    if (Bool.and(Predicate.isUndefined(own), Bool.or(Bool.not(moving), Predicate.isUndefined(each)))) return
+    const raw = sample.raw as PointerEvent
+    const info = dragInfoOf(sample)
+    if (Predicate.isNotUndefined(named)) call(named, own, raw, info)
+    if (moving) callPerMove(every, each, raw, info)
+  }
+  return {
+    hovered: (edge) => {
+      const name = Bool.match(edge.active, { onTrue: () => "onHoverStart" as const, onFalse: () => "onHoverEnd" as const })
+      call(name, config()[name], edge.event.raw as PointerEvent, pointInfoOf(edge.event))
+    },
+    pressed: (press, element) => {
+      const name = PRESS_CALLBACK[press.phase]
+      if (Predicate.isUndefined(name)) return
+      call(name, config()[name], press.event.raw as WardicPressEvent, pressInfoOf(press, element))
+    },
+    dragged: (sample) => {
+      // A drag its controls cancelled (#431) ends untold, as Motion's `cancel` tells no `onDragEnd`.
+      if (sample.cancelled === true) return
+      // A direction-locked drag's lock, at its start, before `onDragStart` (Motion's order).
+      if (sample.phase === "start") {
+        const c = config()
+        if (c.dragDirectionLock === true) call("onDirectionLock", c.onDirectionLock, sample.axis as "x" | "y")
+      }
+      moved(DRAG_CALLBACK[sample.phase], "onDrag", sample)
+    },
+    released: () => call("onDragTransitionEnd", config().onDragTransitionEnd),
+    panned: (sample) => {
+      // Its session's start, at the down: Motion's `onPanSessionStart`, with the point only.
+      if (sample.phase === "session") {
+        call("onPanSessionStart", config().onPanSessionStart, sample.raw as PointerEvent, pointOfSample(sample))
+        return
+      }
+      moved(PAN_CALLBACK[sample.phase], "onPan", sample as Drag.Sample)
+    },
+    viewed: (edge) => {
+      const name = Bool.match(edge.active, { onTrue: () => "onViewportEnter" as const, onFalse: () => "onViewportLeave" as const })
+      call(name, config()[name], edge.raw as IntersectionObserverEntry)
+    },
+  }
+}

package/src/gesture-features.ts

@@ -0,0 +1,35 @@
+/**
+ * What an element reads of its section's gesture Features (#511, ADR-0067 decision 3): each gesture's
+ * service, `undefined` without its Feature, the gestures' input a section with one has, and the words
+ * development's message on a missing one names. Solid-free, for both bindings; it reaches no Feature's
+ * code, only their keys.
+ *
+ * @module
+ */
+import * as InputSource from "@wardic/core/InputSource"
+import * as Context from "effect/Context"
+import * as Option from "effect/Option"
+
+/** `key`'s service among `services`, or `undefined` when they hold none: its Feature isn't there. */
+export const serviceIn = <I, S>(services: Context.Context<never>, key: Context.Key<I, S>): S | undefined =>
+  Option.getOrUndefined(Context.getOption(services as Context.Context<I>, key))
+
+/** The gestures' input among `services`: a section with any gesture Feature but `inView` has it. */
+export const inputIn = (services: Context.Context<never>): InputSource.InputSource["Service"] =>
+  Context.get(services as Context.Context<InputSource.InputSource>, InputSource.InputSource)
+
+/** What development's word on a missing gesture Feature names, by Feature: what the element asked of it. */
+export const GESTURE_WORDS = {
+  hover: "Its hover (`whileHover`, or a hover event)",
+  press: "Its press (`whileTap`, or a tap event)",
+  focus: "Its focus (`whileFocus`)",
+  inView: "Its view (`whileInView`, or a viewport event)",
+  pan: "Its pan (a pan event)",
+  drag: "Its drag (`drag`)",
+} as const
+
+/** Whether `services` hold `key`'s service: its Feature is there. */
+export const hasService = <I, S>(services: Context.Context<never>, key: Context.Key<I, S>): boolean => Option.isSome(Context.getOption(services as Context.Context<I>, key))
+
+/** `key`'s service among `services`, which hold it: a Feature a hook or component brought. */
+export const serviceOf = <I, S>(services: Context.Context<never>, key: Context.Key<I, S>): S => Context.get(services as Context.Context<I>, key)

package/src/gesture-info.ts

@@ -0,0 +1,81 @@
+/**
+ * The info a gesture event hands over (#257, #273): Motion's `EventInfo` / `TapInfo` and `PanInfo` (a
+ * drag's and a pan's), with the pointer's `point` in the viewport (`clientX` / `clientY`, as
+ * `getBoundingClientRect()` measures), not the page as Motion's: both bindings, grilled B on each
+ * (ADR-0046, ADR-0047). Solid 1's callbacks and Solid 2's `next(name)` both build it here.
+ *
+ * @module
+ */
+import type * as Drag from "@wardic/core/Drag"
+import type * as InputSource from "@wardic/core/InputSource"
+import type * as Recognizer from "@wardic/core/Recognizer"
+
+/** A point in the viewport. */
+export interface WardicPoint {
+  readonly x: number
+  readonly y: number
+}
+
+/** A hover's or a press's event: where the pointer was, in the viewport. */
+export interface WardicPointInfo {
+  readonly point: WardicPoint
+}
+
+/**
+ * A drag's event: where the pointer was, in the viewport, and the drag's `offset` from its down, its
+ * last `delta` and its `velocity` (px/s). A scroll during the drag counts as movement in `offset`, as
+ * Motion's does; `point` stays where the pointer is on the screen. A one-axis drag's are zeroed off
+ * its axis.
+ */
+export interface WardicDragInfo {
+  readonly point: WardicPoint
+  readonly offset: WardicPoint
+  readonly delta: WardicPoint
+  readonly velocity: WardicPoint
+}
+
+/** How a press was made: by a pointer, or a **Keyboard press**. */
+export type WardicPressInput = "pointer" | "keyboard"
+
+/**
+ * A press's event: where it was, in the viewport, and how it was made. A **Keyboard
+ * press**'s point is its element's centre, measured at the key, so code that places something at a
+ * press works for one.
+ */
+export interface WardicPressInfo extends WardicPointInfo {
+  readonly input: WardicPressInput
+}
+
+/**
+ * The platform's event a press's callback hears: a pointer's; a **Keyboard press**'s key, or
+ * the blur that cancelled it.
+ */
+export type WardicPressEvent = PointerEvent | KeyboardEvent | FocusEvent
+
+/** A press's info (#427): a pointer's point less the scroll its hold counted into it, or a **Keyboard press**'s element's centre. */
+export const pressInfoOf = (press: Recognizer.PressEvent, element: Element): WardicPressInfo => {
+  if (press.input === "pointer") return { point: { x: press.event.x - press.event.scroll.x, y: press.event.y - press.event.scroll.y }, input: "pointer" }
+  const box = element.getBoundingClientRect()
+  return { point: { x: box.left + box.width / 2, y: box.top + box.height / 2 }, input: "keyboard" }
+}
+
+/** A hover's or a press's info: its event's point less the scroll its hold counted into it. */
+export const pointInfoOf = (event: InputSource.PointerLikeEvent): WardicPointInfo => ({
+  point: { x: event.x - event.scroll.x, y: event.y - event.scroll.y },
+})
+
+/** What a drag's or a pan's sample carries for its info. */
+type Sampled = Pick<Drag.Sample, "point" | "scroll" | "offset" | "delta" | "velocity">
+
+/** A drag sample's info: its point less the scroll its hold counted into it, and its own offset, delta and velocity. */
+export const dragInfoOf = (sample: Sampled): WardicDragInfo => ({
+  point: { x: sample.point.x - sample.scroll.x, y: sample.point.y - sample.scroll.y },
+  offset: sample.offset,
+  delta: sample.delta,
+  velocity: sample.velocity,
+})
+
+/** A sample's point alone, as a hover's or a press's info (a pan's session's start, #273). */
+export const pointOfSample = (sample: Sampled): WardicPointInfo => ({
+  point: { x: sample.point.x - sample.scroll.x, y: sample.point.y - sample.scroll.y },
+})

package/src/hover-sensor.ts

@@ -0,0 +1,32 @@
+/**
+ * `createHover` (#548): in a module of its own, so it brings the `hover` Feature only to an app that uses it,
+ * and on the pages that do (ADR-0067, *Amendment (#548)*).
+ *
+ * @module
+ */
+import type { Accessor } from "solid-js"
+import { watchToSignal } from "./bridge.ts"
+import type { Feature } from "./feature.ts"
+import { hover } from "./features/hover.ts"
+import { HoverGesture } from "./features/keys.ts"
+import { serviceOf } from "./gesture-features.ts"
+import { useBrought } from "./provider.tsx"
+
+/** What it brings (ADR-0067 decision 12): its gesture's Feature, whatever its section has (#511). */
+const HOVER: ReadonlyArray<Feature> = [hover]
+
+/**
+ * `true` while the pointer is over `target`, `false` once it leaves: a hover as state, for what isn't
+ * an animation, where `whileHover` would do. `target` is the element itself, so call it where it
+ * exists: in a component it's given to. A touch never hovers.
+ *
+ * @example
+ * const hovered = createHover(props.card)
+ * <Show when={hovered()}><p class="hint">Drag to reorder</p></Show>
+ * @see https://wardic.dev/reference/solid/gestures/create-hover
+ */
+// The core hover watch (#318); `false` until its first transition.
+export const createHover = (target: unknown): Accessor<boolean> => {
+  const services = useBrought(HOVER)
+  return watchToSignal<boolean>(({ on, onDefect }) => serviceOf(services(), HoverGesture).watch(target, { on: (transition) => on(transition.active), onDefect }), false)
+}