solidjs-motion 0.1.0

package/src/primitives/motion-value.ts

@@ -0,0 +1,328 @@
+import {
+  cancelFrame,
+  frame,
+  isMotionValue,
+  type MotionValue,
+  transform as motionTransform,
+  motionValue,
+  type SpringOptions,
+  springValue,
+} from "motion"
+import { type Accessor, createComputed, createSignal, onCleanup } from "solid-js"
+import type { MotionValueAccessor } from "../types"
+
+// ---------------------------------------------------------------------------
+// MotionValue events the engine can fire — kept narrow so TypeScript autocomplete
+// surfaces only the documented surface.
+// ---------------------------------------------------------------------------
+
+type MotionValueEvent = "change" | "animationStart" | "animationComplete" | "animationCancel"
+
+// ---------------------------------------------------------------------------
+// makeAccessor — wrap a raw motion.MotionValue as a callable hybrid. Invoking
+// `mv()` returns a Solid-tracked read; every MotionValue method (.get, .set,
+// .jump, .on, .getVelocity, etc.) forwards to the underlying value. Both
+// `isMotionValue(mv)` (duck-typed on .getVelocity) and `typeof mv === "function"`
+// are true; createMotion's splitTarget checks isMotionValue first, so the engine
+// treats hybrids as MotionValues.
+// ---------------------------------------------------------------------------
+
+function makeAccessor<T>(mv: MotionValue<T>): MotionValueAccessor<T> {
+  // Solid signal bridge — kept in sync via `mv.on("change", ...)`.
+  const [signal, setSignal] = createSignal<T>(mv.get())
+  // Wrap in updater form so Setter accepts T regardless of its shape (T could
+  // include Function for callback-like motion values).
+  onCleanup(mv.on("change", (v) => setSignal(() => v)))
+
+  // The callable: invoking returns the tracked signal value.
+  const fn = (() => signal()) as MotionValueAccessor<T>
+
+  return new Proxy(fn, {
+    get(target, prop, receiver) {
+      // Function intrinsics (call/apply/bind) stay on the function itself so
+      // `fn.call(...)` etc. behave normally.
+      if (prop === "call" || prop === "apply" || prop === "bind") {
+        return Reflect.get(target, prop, receiver)
+      }
+      // If we ever attach our own properties to `fn`, prefer those.
+      if (Reflect.has(target, prop)) return Reflect.get(target, prop, receiver)
+      // Forward to the MotionValue. Methods are bound so `this` is the MV.
+      const value = Reflect.get(mv as object, prop, mv)
+      return typeof value === "function" ? value.bind(mv) : value
+    },
+    has(target, prop) {
+      return Reflect.has(target, prop) || prop in (mv as object)
+    },
+  })
+}
+
+// ---------------------------------------------------------------------------
+// createMotionValue — callable-hybrid MotionValue auto-disposed on cleanup.
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a {@link MotionValueAccessor} bound to the current reactive scope.
+ *
+ * The returned value has two access patterns:
+ *
+ * - `mv()` — invoke as a Solid Accessor. Tracks in JSX, `createEffect`,
+ *   `createMemo`, etc.
+ * - `mv.get()` / `mv.set(v)` / `mv.jump(v)` / `mv.on(...)` — the full upstream
+ *   {@link MotionValue} surface. Matches motion/react idioms.
+ *
+ * The same value can be passed as a target in
+ * `useMotion({ animate: { x: mv } })` (motion engine sees `.getVelocity` via
+ * the Proxy and treats it as a motion value) or directly as the target of
+ * `animate(mv, 100)`.
+ *
+ * Auto-destroyed via `onCleanup` when the owner is disposed.
+ *
+ * @example
+ * const x = createMotionValue(0)
+ * x.set(100)
+ * animate(x, 200, { duration: 0.5 })
+ * <p>{x()}</p>           // reactive read in JSX
+ */
+export function createMotionValue<T>(initial: T): MotionValueAccessor<T> {
+  const mv = motionValue(initial)
+  const accessor = makeAccessor(mv)
+  // Route the cleanup call through the accessor so test-time spies on
+  // `accessor.destroy` are invoked (the Proxy forwards to the underlying mv).
+  onCleanup(() => accessor.destroy())
+  return accessor
+}
+
+// ---------------------------------------------------------------------------
+// toSignal — adapt any raw MotionValue (e.g. from motion's `motionValue()`
+// factory) to a Solid Accessor. Useful when interoperating with motion APIs
+// that return raw MotionValues outside our hybrid factories.
+// ---------------------------------------------------------------------------
+
+/**
+ * Bridge a raw {@link MotionValue} (from motion's `motionValue()` factory or
+ * any other motion API that doesn't return our hybrid) to a Solid
+ * {@link Accessor}. Seeds with the current value and updates on every
+ * `change` event.
+ *
+ * **You usually don't need this.** Values returned by `createMotionValue`,
+ * `createTransform`, `createSpring`, `createTime`, `createVelocity`, and
+ * `createTemplate` are already callable — you can do `mv()` directly. Reach
+ * for `toSignal` only when you receive a raw MotionValue from an external API.
+ *
+ * @example
+ * import { motionValue } from "motion"
+ * const rawMv = motionValue(0)
+ * const xSignal = toSignal(rawMv)
+ */
+export function toSignal<T>(mv: MotionValue<T>): Accessor<T> {
+  const [value, setValue] = createSignal<T>(mv.get())
+  onCleanup(mv.on("change", (v) => setValue(() => v)))
+  return value
+}
+
+// ---------------------------------------------------------------------------
+// createMotionValueEvent — register a listener with automatic cleanup.
+// ---------------------------------------------------------------------------
+
+/**
+ * Subscribe to a {@link MotionValue} event with automatic cleanup. Convenience
+ * wrapper around `mv.on(event, cb)` for parity with motion/react's
+ * `useMotionValueEvent`. For per-change reactivity, prefer
+ * `createComputed(() => fn(mv()))` since hybrids are directly callable.
+ *
+ * @example
+ * const x = createMotionValue(0)
+ * createMotionValueEvent(x, "animationComplete", () => console.log("done"))
+ */
+export function createMotionValueEvent<T>(
+  mv: MotionValue<T>,
+  event: MotionValueEvent,
+  callback: (latest: T) => void,
+): void {
+  onCleanup(mv.on(event, callback))
+}
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+function readInputValue<T>(input: MotionValue<T> | Accessor<T>): T {
+  if (isMotionValue(input)) return (input as MotionValue<T>).get()
+  return (input as Accessor<T>)()
+}
+
+function subscribeInput<T>(
+  input: MotionValue<T> | Accessor<T>,
+  onChange: (value: T) => void,
+): void {
+  if (isMotionValue(input)) {
+    onCleanup((input as MotionValue<T>).on("change", onChange))
+  } else {
+    createComputed(() => onChange((input as Accessor<T>)()))
+  }
+}
+
+// ---------------------------------------------------------------------------
+// createTransform — interpolate one MotionValue/Accessor through a range.
+// Returns a MotionValueAccessor so callable behavior is preserved end-to-end.
+// ---------------------------------------------------------------------------
+
+type TransformOptions = NonNullable<Parameters<typeof motionTransform>[2]>
+
+/**
+ * Create a {@link MotionValueAccessor} that maps an input through a range/
+ * output pair. Mirrors motion/react's `useTransform`. The input can be a
+ * MotionValue, our hybrid, or any Solid Accessor; the output composes with
+ * `animate()`, `useMotion`'s targets, and JSX reactivity.
+ *
+ * @example
+ * const { scrollY } = createScroll()
+ * const opacity = createTransform(scrollY, [0, 200], [1, 0])
+ * <div style={{ opacity: opacity() }}>...</div>
+ */
+export function createTransform<I extends number, O>(
+  input: MotionValue<I> | Accessor<I>,
+  inputRange: I[],
+  outputRange: O[],
+  options?: TransformOptions,
+): MotionValueAccessor<O> {
+  const mapper = motionTransform(inputRange, outputRange, options)
+  const mv = motionValue(mapper(readInputValue(input)))
+  onCleanup(() => mv.destroy())
+  subscribeInput(input, (v) => mv.set(mapper(v)))
+  return makeAccessor(mv)
+}
+
+// ---------------------------------------------------------------------------
+// createSpring — produce a MotionValueAccessor that spring-tracks an input.
+// ---------------------------------------------------------------------------
+
+/**
+ * Spring-smoothed mirror of a numeric input. Returns a
+ * {@link MotionValueAccessor} that tracks the source with physics-based easing.
+ *
+ * @example
+ * const x = createMotionValue(0)
+ * const smoothX = createSpring(x, { stiffness: 100, damping: 20 })
+ */
+export function createSpring(
+  source: MotionValue<number> | Accessor<number>,
+  options?: SpringOptions,
+): MotionValueAccessor<number> {
+  if (isMotionValue(source)) {
+    const mv = springValue(source as MotionValue<number>, options)
+    onCleanup(() => mv.destroy())
+    return makeAccessor(mv)
+  }
+  // Accessor input — bridge through an intermediate MotionValue that mirrors it.
+  const bridge = motionValue((source as Accessor<number>)())
+  onCleanup(() => bridge.destroy())
+  createComputed(() => bridge.set((source as Accessor<number>)()))
+  const mv = springValue(bridge, options)
+  onCleanup(() => mv.destroy())
+  return makeAccessor(mv)
+}
+
+// ---------------------------------------------------------------------------
+// createTime — MotionValueAccessor that advances each frame with elapsed ms.
+// ---------------------------------------------------------------------------
+
+/**
+ * {@link MotionValueAccessor} that advances every animation frame, holding
+ * the milliseconds elapsed since this primitive was called. Driver for
+ * time-based animations and {@link createTransform}-derived values.
+ *
+ * @example
+ * const t = createTime()
+ * const wobble = createTransform(t, [0, 1000, 2000], [0, 10, 0])
+ */
+export function createTime(): MotionValueAccessor<number> {
+  const mv = motionValue(0)
+  onCleanup(() => mv.destroy())
+  const startedAt = performance.now()
+  const tick = () => mv.set(performance.now() - startedAt)
+  frame.update(tick, true)
+  onCleanup(() => cancelFrame(tick))
+  return makeAccessor(mv)
+}
+
+// ---------------------------------------------------------------------------
+// createVelocity — MotionValueAccessor mirroring an input's instantaneous velocity.
+// ---------------------------------------------------------------------------
+
+/**
+ * {@link MotionValueAccessor} reporting the velocity of a source motion value.
+ * Updated whenever the source changes.
+ *
+ * @example
+ * const x = createMotionValue(0)
+ * const xVelocity = createVelocity(x)
+ */
+export function createVelocity(source: MotionValue<number>): MotionValueAccessor<number> {
+  const mv = motionValue(source.getVelocity())
+  onCleanup(() => mv.destroy())
+  onCleanup(source.on("change", () => mv.set(source.getVelocity())))
+  return makeAccessor(mv)
+}
+
+// ---------------------------------------------------------------------------
+// createTemplate — tagged template producing a MotionValueAccessor<string>.
+// ---------------------------------------------------------------------------
+
+// biome-ignore lint/suspicious/noExplicitAny: MotionValue is invariant in T; `any` lets the template accept MotionValues of any value type.
+type TemplateInput = MotionValue<any> | Accessor<unknown> | string | number
+
+/**
+ * Tagged template producing a {@link MotionValueAccessor}\<string\>.
+ * Interpolated {@link MotionValue}s, hybrids, and Solid Accessors recompute
+ * the output string on change; primitives and static strings are baked in.
+ *
+ * @example
+ * const x = createMotionValue(0)
+ * const y = createMotionValue(0)
+ * const transform = createTemplate`translate(${x}px, ${y}px) scale(1.1)`
+ * <div style={{ transform: transform() }} />
+ */
+export function createTemplate(
+  strings: TemplateStringsArray,
+  ...values: TemplateInput[]
+): MotionValueAccessor<string> {
+  const compute = (): string => {
+    let out = ""
+    for (let i = 0; i < strings.length; i++) {
+      out += strings[i]
+      if (i < values.length) {
+        const v = values[i]
+        if (isMotionValue(v)) {
+          out += String((v as MotionValue<unknown>).get())
+        } else if (typeof v === "function") {
+          out += String((v as Accessor<unknown>)())
+        } else {
+          out += String(v)
+        }
+      }
+    }
+    return out
+  }
+
+  const mv = motionValue(compute())
+  onCleanup(() => mv.destroy())
+
+  for (const v of values) {
+    if (isMotionValue(v)) {
+      onCleanup((v as MotionValue<unknown>).on("change", () => mv.set(compute())))
+    }
+  }
+
+  const hasAccessor = values.some((v) => typeof v === "function" && !isMotionValue(v))
+  if (hasAccessor) {
+    createComputed(() => {
+      for (const v of values) {
+        if (typeof v === "function" && !isMotionValue(v)) (v as Accessor<unknown>)()
+      }
+      mv.set(compute())
+    })
+  }
+
+  return makeAccessor(mv)
+}

package/src/primitives/value-registry.ts

@@ -0,0 +1,114 @@
+import { type MotionValue, motionValue } from "motion"
+
+// ---------------------------------------------------------------------------
+// Per-element value registry.
+//
+// One `ValueRegistry` per element managed by `createMotion`. It maps style /
+// transform-shortcut keys (`scale`, `y`, `opacity`, etc.) to the
+// `MotionValue` that authoritatively drives the corresponding CSS or
+// transform component for that element.
+//
+// This is the motion-react `visualElement.values` shape, slimmed down. It
+// exists to unify two write paths that currently disagree about who owns a
+// CSS key on the element:
+//
+//   1. **User-provided MVs in `style`** — `<motion.div style={{ scale: mv }}>`.
+//      mv is the source of truth for `scale`; subscribing to it and writing
+//      `el.style.transform` is the only way the new value reaches the DOM.
+//   2. **animate-target writes** — `useMotion({ animate: { scale: 1.5 } })`.
+//      Today these go directly via WAA (`animate(el, target, opts)`). After
+//      Stage 3 they will be routed through the registry: if a key has a
+//      registered MV, the animation tweens that MV (which writes the DOM
+//      via its subscription) instead of writing the element directly.
+//
+// Stage 1 introduces only the data structure. No code reads from or writes
+// to it yet — `createMotion` instantiates an empty registry, attaches a
+// disposal hook, and stops there. Subsequent stages wire it up.
+//
+// Two ownership classes:
+//
+// - **External** — MVs the user created via `createMotionValue` / motion's
+//   `motionValue()` and handed us via `style`. The registry tracks them so
+//   we know "this key is MV-backed" but does NOT dispose them. The user
+//   owns their MV's lifetime.
+//
+// - **Transient** — MVs the registry creates internally (Stage 3) because
+//   an animate target referenced a key with no existing MV. The registry
+//   owns these and clears them on `dispose()`. motion's MotionValue has no
+//   imperative teardown method; releasing references is what lets GC
+//   collect them once all subscribers have cleaned up.
+// ---------------------------------------------------------------------------
+
+export type ValueRegistry = {
+  /** Returns the MV registered for `key`, or `undefined` if none. */
+  get(key: string): MotionValue<unknown> | undefined
+  /** Has any MV been registered for `key`? */
+  has(key: string): boolean
+  /**
+   * Number of entries currently registered. Used by `createMotion` to decide
+   * whether the per-element writer can take a specialized single-key path
+   * (size === 1) or needs the general-purpose `applyStaticStyle` walk.
+   */
+  readonly size: number
+  /**
+   * Register a user-provided MV. The registry will NOT dispose it on
+   * teardown. If a transient MV exists for the key, it is replaced (the
+   * external MV becomes the new source of truth).
+   */
+  setExternal(key: string, mv: MotionValue<unknown>): void
+  /**
+   * Get the MV for `key`, creating a transient one initialized to
+   * `fallback` if absent. Transient MVs are disposed on `dispose()`.
+   */
+  getOrCreateTransient(key: string, fallback: unknown): MotionValue<unknown>
+  /** Iterate every (key, MV) pair currently registered. */
+  entries(): IterableIterator<[string, MotionValue<unknown>]>
+  /**
+   * Drop registry-owned (transient) MVs. External MVs are untouched.
+   * Subscription cleanups are owned by whoever called `mv.on(...)`; they
+   * tie to the surrounding Solid owner via `onCleanup` in Stage 2+ so we
+   * don't unsubscribe imperatively here.
+   */
+  dispose(): void
+}
+
+export function createValueRegistry(): ValueRegistry {
+  const values = new Map<string, MotionValue<unknown>>()
+  const transient = new Set<MotionValue<unknown>>()
+
+  return {
+    get(key) {
+      return values.get(key)
+    },
+    has(key) {
+      return values.has(key)
+    },
+    setExternal(key, mv) {
+      const existing = values.get(key)
+      if (existing && transient.has(existing)) {
+        // Replacing a transient with an external takes the transient out
+        // of the owned-set so dispose() doesn't pretend to manage it.
+        transient.delete(existing)
+      }
+      values.set(key, mv)
+    },
+    getOrCreateTransient(key, fallback) {
+      const existing = values.get(key)
+      if (existing) return existing
+      const mv = motionValue(fallback) as MotionValue<unknown>
+      values.set(key, mv)
+      transient.add(mv)
+      return mv
+    },
+    entries() {
+      return values.entries()
+    },
+    get size() {
+      return values.size
+    },
+    dispose() {
+      transient.clear()
+      values.clear()
+    },
+  }
+}

package/src/reduced-motion.ts

@@ -0,0 +1,51 @@
+import { type Accessor, from } from "solid-js"
+
+/**
+ * A reactive `Accessor<boolean>` tracking the user's
+ * `prefers-reduced-motion: reduce` media query.
+ *
+ * Returns `false` server-side (no `window.matchMedia`). On the client, it seeds
+ * with the current match state and updates as the system preference toggles.
+ * The matchMedia listener is removed automatically on owner disposal via
+ * `from`'s teardown callback.
+ *
+ * @example
+ * const reduced = createReducedMotion()
+ * createEffect(() => {
+ *   if (reduced()) console.log("user prefers reduced motion")
+ * })
+ */
+export function createReducedMotion(): Accessor<boolean> {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return () => false
+  }
+  const mql = window.matchMedia("(prefers-reduced-motion: reduce)")
+  // `from` produces an Accessor<T | undefined>; we seed synchronously inside the
+  // producer so the cast to Accessor<boolean> is sound.
+  return from<boolean>((set) => {
+    set(mql.matches)
+    const handler = (e: MediaQueryListEvent) => set(e.matches)
+    mql.addEventListener("change", handler)
+    return () => mql.removeEventListener("change", handler)
+  }) as Accessor<boolean>
+}
+
+/**
+ * Compute the effective reduced-motion state by combining a {@link MotionConfig}
+ * `reducedMotion` setting with the system preference.
+ *
+ * - `"always"` — forced reduced, regardless of system pref
+ * - `"never"` — never reduced, regardless of system pref
+ * - `"user"` — respect system pref
+ *
+ * @example
+ * const reduced = shouldReduceMotion("user", createReducedMotion()())
+ */
+export function shouldReduceMotion(
+  configValue: "always" | "never" | "user",
+  systemReduced: boolean,
+): boolean {
+  if (configValue === "always") return true
+  if (configValue === "never") return false
+  return systemReduced
+}