solidjs-motion 0.1.0

package/src/primitives/createDragControls.ts

@@ -0,0 +1,101 @@
+import type { DragControls, DragControlsStartOptions } from "../types"
+
+// ---------------------------------------------------------------------------
+// createDragControls — imperative drag-controls factory (Q9).
+//
+// Architecture:
+// - A controls instance has one public method: `start(event, options?)`.
+// - createDrag (when its `opts.dragControls === thisInstance`) registers a
+//   handler via the symbol-keyed internal property defined below. The
+//   handler synthesizes a drag session from the externally-captured pointer
+//   event, bypassing the usual threshold gate.
+// - One controls instance binds to one motion element at a time (Q9d).
+//   When a second element registers, the first is silently replaced. On
+//   unmount, only unregister if we're still the registered handler — avoid
+//   clobbering a later registration.
+//
+// Internal registration:
+// - We attach a `_register(handler)` method to a non-enumerable symbol-keyed
+//   property (Q9e), keeping the public `DragControls` type clean. The
+//   symbol is exported as `DRAG_CONTROLS_REGISTER` for createDrag to find,
+//   but users importing only `DragControls` never see it.
+// ---------------------------------------------------------------------------
+
+/**
+ * Symbol used to attach the registration method on the controls object.
+ * `createDrag` imports this symbol to find/register its handler. Userland
+ * code never touches it — exported only for library-internal use.
+ */
+export const DRAG_CONTROLS_REGISTER = Symbol("solidjs-motion.dragControls.register")
+
+/**
+ * Internal registration signature — the handler that createDrag installs.
+ * Returns an unregister function (called on owner disposal).
+ */
+type RegistrationFn = (
+  handler: (event: PointerEvent, options: DragControlsStartOptions) => void,
+) => () => void
+
+/** Public + internal shape of the controls returned by `createDragControls`. */
+type DragControlsInternal = DragControls & {
+  [DRAG_CONTROLS_REGISTER]: RegistrationFn
+}
+
+/**
+ * Create a controls instance for imperatively starting a drag on a motion
+ * element from a different element (e.g., a drag-handle button).
+ *
+ * Pattern (Q9):
+ *
+ * @example
+ * function Card() {
+ *   const controls = createDragControls()
+ *   const m = useMotion({ drag: "y", dragControls: controls })
+ *   return (
+ *     <div {...m()}>
+ *       <button onPointerDown={(e) => controls.start(e)}>handle</button>
+ *       Card body
+ *     </div>
+ *   )
+ * }
+ *
+ * The handle's pointerdown fires `controls.start(event)`. createDrag is
+ * registered with the controls and translates the call into a pan-session
+ * synthesized from the handle's event, bypassing the threshold gate.
+ */
+export function createDragControls(): DragControls {
+  let handler: ((event: PointerEvent, options: DragControlsStartOptions) => void) | null = null
+
+  // Public surface — `start` is the only enumerable property.
+  const controls: DragControlsInternal = {
+    start(event: PointerEvent, options: DragControlsStartOptions = {}) {
+      // No-op when no motion element is currently registered. Matches
+      // motion/react's behavior: the user's pointerdown handler can be
+      // attached unconditionally, and start() is harmless until binding.
+      handler?.(event, options)
+    },
+    // Placeholder — filled in immediately below via Object.defineProperty
+    // so the property is non-enumerable.
+    [DRAG_CONTROLS_REGISTER]: undefined as unknown as RegistrationFn,
+  }
+
+  // Q9e — registration internals on a non-enumerable property keyed by
+  // Symbol. Type-level the property is on DragControlsInternal, but the
+  // public DragControls type omits it — userland sees only `.start`.
+  Object.defineProperty(controls, DRAG_CONTROLS_REGISTER, {
+    value: ((newHandler) => {
+      handler = newHandler
+      // Q9d — return an unregister that only nulls out if we're still the
+      // active handler. Prevents a stale unmount from clobbering a later
+      // registration on the same controls instance.
+      return () => {
+        if (handler === newHandler) handler = null
+      }
+    }) satisfies RegistrationFn,
+    enumerable: false,
+    writable: false,
+    configurable: false,
+  })
+
+  return controls
+}

package/src/primitives/createGestures.ts

@@ -0,0 +1,145 @@
+import { addDomEvent, hover, press } from "motion-dom"
+import { createEffect, onCleanup } from "solid-js"
+import type { MotionElement, MotionOptions } from "../types"
+import { createInView } from "./createInView"
+import type { SetActive } from "./gesture-state"
+
+// ---------------------------------------------------------------------------
+// createGestures — wires pointer-driven gestures (hover, press, focus, inView)
+// to the gesture state machine's `setActive`. Phase 2 Commit 2 wires hover and
+// press only; focus and inView land in Commit 3.
+//
+// Q1/C — hover and press are routed through motion-dom's primitives directly,
+// not re-implemented. ADR 0001 documents the dependency.
+//
+// Q13/a — listeners attach unconditionally on mount and clean up on owner
+// disposal. We do NOT re-attach when `opts.hover` / `opts.press` flip between
+// defined and undefined: the state machine's per-key winners memo naturally
+// produces an empty diff when an active state has no target, so the extra
+// DOM listener pair costs nothing in practice.
+// ---------------------------------------------------------------------------
+
+/**
+ * Bind pointer-event-driven gestures (hover, press) to the motion element.
+ * Toggles the state machine's `whileHover` / `whilePress` flags and forwards
+ * events to the user's `MotionCallbacks`.
+ */
+export function createGestures(
+  el: MotionElement,
+  getOpts: () => MotionOptions,
+  setActive: SetActive,
+): void {
+  // ---------- Hover ----------
+  // motion-dom's hover(): start callback shape is `(element, event) => onEnd?`.
+  // We ignore `element` (always equal to `el` since we pass the element rather
+  // than a selector). The optional returned function fires on hover-end.
+  //
+  // Why motion-dom's hover() rather than addEventListener("pointerenter")?
+  // Subtle behaviors handled inside motion-dom we'd otherwise re-derive:
+  //   - Press-in-progress defers hover-end until pointer-up (mobile UX).
+  //   - Secondary pointer events filtered via isPrimaryPointer.
+  //   - pointercancel cleanup parallel to pointerup.
+  const stopHover = hover(el, (_element, event) => {
+    setActive("whileHover", true)
+    getOpts().onHoverStart?.(event)
+    return (event) => {
+      setActive("whileHover", false)
+      getOpts().onHoverEnd?.(event)
+    }
+  })
+  onCleanup(stopHover)
+
+  // ---------- Press ----------
+  // motion-dom's press(): same callback shape, plus the end callback receives
+  // `(event, { success: boolean })`. `success === true` when the pointer was
+  // still over the element at pointer-up (completed press); `false` when it
+  // moved away or was cancelled.
+  //
+  // Q13/c — branch on `info.success`:
+  //   onPressStart fires at pointerdown (no success info yet — Q13 tightened
+  //     the signature to drop the info param).
+  //   onPress fires on completed press.
+  //   onPressCancel fires on aborted press.
+  const stopPress = press(el, (_element, event) => {
+    setActive("whilePress", true)
+    getOpts().onPressStart?.(event)
+    return (event, info) => {
+      setActive("whilePress", false)
+      if (info.success) {
+        getOpts().onPress?.(event, info)
+      } else {
+        getOpts().onPressCancel?.(event, info)
+      }
+    }
+  })
+  onCleanup(stopPress)
+
+  // ---------- Focus (Q12) ----------
+  // Activation (`whileFocus` state) is gated by `:focus-visible` — mouse
+  // clicks that incidentally focus an element should NOT trigger the visual
+  // state, only keyboard navigation does. The native `onFocus`/`onBlur`
+  // callbacks fire for every focus event regardless (Q12b — programmatic
+  // listeners shouldn't be filtered).
+  //
+  // The `:focus-visible` selector throws in older browsers — we fall back
+  // to always-active, matching motion/react's behavior in that scenario.
+  //
+  // We use motion-dom's `addDomEvent` (rather than el.addEventListener
+  // directly) for consistency with the rest of Phase 2's motion-dom usage,
+  // and because it returns a tidy cleanup function we can hand to onCleanup.
+  let focusActiveByVisible = false
+  const stopFocus = addDomEvent(el, "focus", (event) => {
+    let isFocusVisible = false
+    try {
+      isFocusVisible = el.matches(":focus-visible")
+    } catch {
+      isFocusVisible = true
+    }
+    if (isFocusVisible) {
+      setActive("whileFocus", true)
+      focusActiveByVisible = true
+    }
+    getOpts().onFocus?.(event as FocusEvent)
+  })
+  const stopBlur = addDomEvent(el, "blur", (event) => {
+    if (focusActiveByVisible) {
+      setActive("whileFocus", false)
+      focusActiveByVisible = false
+    }
+    getOpts().onBlur?.(event as FocusEvent)
+  })
+  onCleanup(stopFocus)
+  onCleanup(stopBlur)
+
+  // ---------- inView (Q10/A1) ----------
+  // The gesture reuses `createInView` — same observer setup. The `onChange`
+  // merges into the options object so the gesture's onViewportEnter/Leave
+  // hooks receive the raw entry.
+  //
+  // The element is wrapped in `() => el` because createInView takes a ref
+  // accessor; we pass a constant accessor since `el` is fixed for the
+  // gesture's lifetime. The options are function-form so reactive
+  // inViewOptions changes (e.g., a reactive `root` accessor) re-attach
+  // the observer naturally.
+  //
+  // A createEffect bridges createInView's `isInView` Accessor to the state
+  // machine's setActive. When `once: true`, createInView keeps isInView=true
+  // after first intersection (observer disconnected); the gesture's
+  // whileInView stays active forever — motion/react parity.
+  const view = createInView(
+    () => el,
+    () => ({
+      ...getOpts().inViewOptions,
+      onChange: (entry: IntersectionObserverEntry) => {
+        if (entry.isIntersecting) {
+          getOpts().onViewportEnter?.(entry)
+        } else {
+          getOpts().onViewportLeave?.(entry)
+        }
+      },
+    }),
+  )
+  createEffect(() => {
+    setActive("whileInView", view.isInView())
+  })
+}

package/src/primitives/createInView.ts

@@ -0,0 +1,124 @@
+import { type Accessor, createEffect, createSignal, onCleanup } from "solid-js"
+import type { ViewportOptions } from "../types"
+
+// ---------------------------------------------------------------------------
+// createInView — observe an element's intersection with a viewport.
+//
+// Standalone hook, distinct from the `inView` *gesture* on MotionOptions
+// (which animates a target when in view). Returns a pair of Solid Accessors
+// for the boolean and the raw IntersectionObserverEntry — booleans and
+// objects aren't animate-able, so a MotionValueAccessor would only add weight
+// (compare with createPan, where numeric fields ARE MVs because they're
+// animate-able and composable).
+// ---------------------------------------------------------------------------
+
+export type CreateInViewOptions = ViewportOptions & {
+  /**
+   * Fires with the raw {@link IntersectionObserverEntry} on every
+   * visibility transition (enter AND leave). Convenience hook for callers
+   * who prefer event-driven access to the entry — the entry is also
+   * available reactively via the returned `view.entry()` accessor.
+   */
+  onChange?: (entry: IntersectionObserverEntry) => void
+}
+
+/** Returned by {@link createInView}. Two Solid Accessors — call them to track. */
+export type CreateInViewResult = {
+  /** Solid Accessor; `true` while the element intersects the viewport per the configured threshold. */
+  isInView: Accessor<boolean>
+  /** Solid Accessor; the most recent {@link IntersectionObserverEntry}, or `null` before any. */
+  entry: Accessor<IntersectionObserverEntry | null>
+}
+
+/**
+ * Observe an element via {@link IntersectionObserver} and expose its
+ * in-view state as a pair of Solid Accessors.
+ *
+ * Pass a ref-style accessor that returns the element. The observer
+ * attaches once the accessor returns a non-null element and re-attaches
+ * if it changes. The observer is disconnected on owner disposal.
+ *
+ * Options can be a static object or a function form (matching `useMotion`
+ * and `createPan`'s convention). The function form is tracked inside the
+ * effect — option changes (e.g., switching `root`) re-attach the observer.
+ *
+ * @example Static options
+ * const [el, setEl] = createSignal<HTMLElement>()
+ * const view = createInView(el, { once: true })
+ * createEffect(() => {
+ *   if (view.isInView()) console.log("now in view")
+ * })
+ *
+ * @example Function-form options (reactive)
+ * const [root, setRoot] = createSignal<HTMLElement>()
+ * const view = createInView(el, () => ({ root, margin: "100px" }))
+ *
+ * @example Reading the raw entry reactively
+ * const view = createInView(el)
+ * createEffect(() => {
+ *   const e = view.entry()
+ *   if (e) console.log("ratio:", e.intersectionRatio)
+ * })
+ *
+ * <div ref={setEl}>watch me</div>
+ */
+export function createInView(
+  ref: () => Element | null | undefined,
+  options: CreateInViewOptions | (() => CreateInViewOptions) = {},
+): CreateInViewResult {
+  const [isInView, setIsInView] = createSignal(false)
+  const [entry, setEntry] = createSignal<IntersectionObserverEntry | null>(null)
+
+  // createEffect — Solid-idiomatic for side-effect setup (attaching the
+  // IntersectionObserver). First iteration runs in the next microtask,
+  // which is harmless: a freshly-mounted element can't be in or out of
+  // the viewport before the microtask flushes. Option reads inside the
+  // effect's body are tracked — function-form options that read signals
+  // will re-run the effect (and re-attach the observer) on change.
+  createEffect(() => {
+    const el = ref()
+    if (!el) return
+    const opts = typeof options === "function" ? options() : options
+
+    const threshold = resolveThreshold(opts.amount)
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const e of entries) {
+          // Fire onChange first so callers can synchronously inspect the
+          // entry before any downstream signal-effects see the new state.
+          opts.onChange?.(e)
+          // Update the entry signal either way — consumers reading
+          // `view.entry()` reactively see both enter and leave.
+          setEntry(e)
+          if (e.isIntersecting) {
+            setIsInView(true)
+            if (opts.once) observer.disconnect()
+          } else if (!opts.once) {
+            setIsInView(false)
+          }
+        }
+      },
+      {
+        root: opts.root?.() ?? null,
+        rootMargin: opts.margin ?? "0px",
+        threshold,
+      },
+    )
+    observer.observe(el)
+
+    onCleanup(() => observer.disconnect())
+  })
+
+  return { isInView, entry }
+}
+
+function resolveThreshold(amount: ViewportOptions["amount"]): number | number[] {
+  // Pass arrays through unchanged so callers can request continuous
+  // `intersectionRatio` updates (the underlying IntersectionObserver fires
+  // once per threshold crossing, so a fine array → near-live ratio).
+  if (Array.isArray(amount)) return amount
+  if (typeof amount === "number") return amount
+  if (amount === "all") return 1
+  // "some" or undefined → minimal threshold (any pixel intersecting)
+  return 0
+}