solidjs-motion 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to `solidjs-motion` / `@solidjs-motion/motion` are documente
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.2] — 2026-05-20
+
+### Fixed
+
+- **Drag now coexists with `initial` / `animate` / `exit`.** A draggable
+  element with an entrance animation (`<motion.X drag initial={{x:-300}}
+  animate={{x:0}}>`) used to break in two ways: animate's `x`/`y` never
+  reached the DOM, and on pointerdown the element snapped back to the
+  initial position. Three linked fixes:
+  - Drag's exclusion of `x`/`y` from the gesture-state winners is now
+    gated on `active.whileDrag` (pointer-engaged) instead of
+    `dragEnabled` (configured), matching motion-react. Animate's `x`/`y`
+    flow normally while drag is configured but idle; drag only claims
+    them during active interaction.
+  - The diff effect's removed-key fallback no longer reverts `x`/`y` to
+    `initial` when drag activates and excludes them. Drag *claiming* a
+    key is not the same as removing it.
+  - `handlePanStart` now syncs the x/y MotionValues to the element's
+    current visible translate (parsed from `getComputedStyle` +
+    `el.style.transform`) before capturing `dragStart`. motion's
+    `animate(el, target)` interpolates style.transform via WAAPI but
+    doesn't keep the visualElement's MVs in sync, so the MV would still
+    hold the entrance start value when drag began.
+
+## [0.1.1] — 2026-05-20
+
+### Docs
+
+- Expanded README with a 12-recipe "Recipes" section covering the full v0.1
+  surface: reactive `useMotion`, `<motion.X>` proxy + variant cascade,
+  `motion.create` HOC, MotionValues + `createTransform`/`createSpring`,
+  `createScroll`/`createInView`/`createTemplate`, `<Presence>` (single +
+  list + `mode="wait"`), drag with constraints, `<MotionConfig>` +
+  `createReducedMotion`.
+
 ## [0.1.0] — 2026-05-20
 
 First public release. Five phases of the port plan land together: the canonical

package/README.md

@@ -46,6 +46,297 @@ export function Card() {
 with motion's initial styles; user refs and motion's ref both fire; the initial style is
 serialized into SSR HTML so the first paint is flicker-free.
 
+## Recipes
+
+### 1. Reactive options
+
+Pass a function to `useMotion` to track Solid signals inside the target.
+
+```tsx
+import { useMotion } from "solidjs-motion"
+import { createSignal } from "solid-js"
+
+export function Toggle() {
+  const [open, setOpen] = createSignal(false)
+  const motion = useMotion(() => ({
+    animate: { rotate: open() ? 180 : 0 },
+    transition: { duration: 0.3 },
+  }))
+  return (
+    <button onClick={() => setOpen((p) => !p)} {...motion()}>
+      ↑
+    </button>
+  )
+}
+```
+
+### 2. `<motion.X>` proxy with variants
+
+Every HTML/SVG tag is reachable off `motion`. Variant labels on the parent cascade to
+descendants through `m.Provider` (auto-installed by the proxy).
+
+```tsx
+import { motion } from "solidjs-motion"
+
+const variants = {
+  rest: { y: 0, scale: 1 },
+  lift: { y: -8, scale: 1.04 },
+}
+
+export function Card() {
+  return (
+    <motion.article animate="rest" hover="lift" variants={variants}>
+      <motion.h2 variants={variants}>Inherits lift on hover</motion.h2>
+    </motion.article>
+  )
+}
+```
+
+### 3. `motion.create(Component)` HOC
+
+Wrap a custom component to make it motion-aware. The wrapped component must spread its
+props (including `ref`) onto a single DOM-element root.
+
+```tsx
+import { motion } from "solidjs-motion"
+import type { ComponentProps } from "solid-js"
+
+function Button(props: ComponentProps<"button">) {
+  return <button {...props} class={`btn ${props.class ?? ""}`} />
+}
+
+const MotionButton = motion.create(Button)
+
+export function Stage() {
+  return (
+    <MotionButton hover={{ scale: 1.05 }} press={{ scale: 0.95 }}>
+      Press me
+    </MotionButton>
+  )
+}
+```
+
+### 4. MotionValues + `createTransform`
+
+MotionValues are the source of truth for animated state. They're both Solid Accessors and
+upstream `MotionValue`s — drop them straight into `style`.
+
+```tsx
+import { motion, createMotionValue, createTransform } from "solidjs-motion"
+
+export function FadeSlider() {
+  const x = createMotionValue(0)
+  const opacity = createTransform(x, [-100, 0, 100], [0, 1, 0])
+  return (
+    <motion.div
+      drag="x"
+      dragConstraints={{ left: -100, right: 100 }}
+      style={{ x, opacity }}
+    >
+      Drag me
+    </motion.div>
+  )
+}
+```
+
+### 5. Spring-smoothed pointer
+
+`createSpring` mirrors any numeric input with physics smoothing.
+
+```tsx
+import { motion, createMotionValue, createSpring } from "solidjs-motion"
+import { onCleanup, onMount } from "solid-js"
+
+export function Cursor() {
+  const x = createMotionValue(0)
+  const y = createMotionValue(0)
+  const sx = createSpring(x, { stiffness: 200, damping: 30 })
+  const sy = createSpring(y, { stiffness: 200, damping: 30 })
+
+  onMount(() => {
+    const move = (e: PointerEvent) => {
+      x.set(e.clientX)
+      y.set(e.clientY)
+    }
+    window.addEventListener("pointermove", move)
+    onCleanup(() => window.removeEventListener("pointermove", move))
+  })
+
+  return <motion.div class="cursor" style={{ x: sx, y: sy }} />
+}
+```
+
+### 6. Scroll-linked progress bar
+
+```tsx
+import { motion, createScroll, createTransform } from "solidjs-motion"
+
+export function ProgressBar() {
+  const { scrollYProgress } = createScroll()
+  const width = createTransform(scrollYProgress, [0, 1], ["0%", "100%"])
+  return <motion.div class="progress" style={{ width }} />
+}
+```
+
+### 7. Viewport-triggered fade-in
+
+```tsx
+import { motion } from "solidjs-motion"
+
+export function FadeInOnce() {
+  return (
+    <motion.section
+      initial={{ opacity: 0, y: 40 }}
+      inView={{ opacity: 1, y: 0 }}
+      inViewOptions={{ once: true, margin: "0px 0px -10% 0px" }}
+    >
+      Comes in once, stays.
+    </motion.section>
+  )
+}
+```
+
+### 8. `createTemplate` for interpolated strings
+
+Build a `MotionValue<string>` from interpolated MVs/Accessors — feed it to any string-valued
+CSS property.
+
+```tsx
+import { motion, createMotionValue, createTemplate } from "solidjs-motion"
+
+export function GradientBox() {
+  const angle = createMotionValue(0)
+  const background = createTemplate`linear-gradient(${angle}deg, #f0f, #0ff)`
+  return (
+    <motion.div
+      hover={{ rotate: 360 }}
+      transition={{ duration: 2 }}
+      style={{ background }}
+    />
+  )
+}
+```
+
+### 9. `<Presence>` for exit animations
+
+Wrap a conditionally-rendered child to animate its exit before unmount.
+
+```tsx
+import { motion, Presence } from "solidjs-motion"
+import { Show, createSignal } from "solid-js"
+
+export function Drawer() {
+  const [open, setOpen] = createSignal(false)
+  return (
+    <>
+      <button onClick={() => setOpen((p) => !p)}>Toggle</button>
+      <Presence>
+        <Show when={open()}>
+          <motion.aside
+            initial={{ x: -300 }}
+            animate={{ x: 0 }}
+            exit={{ x: -300 }}
+            transition={{ duration: 0.25 }}
+          >
+            Drawer content
+          </motion.aside>
+        </Show>
+      </Presence>
+    </>
+  )
+}
+```
+
+### 10. `mode="wait"` + list exits
+
+`mode="wait"` plays the outgoing child's `exit` fully before the incoming child enters.
+For lists, `Presence` wraps a `<For>` and animates add/remove together.
+
+```tsx
+import { motion, Presence } from "solidjs-motion"
+import { For, Show, createSignal } from "solid-js"
+
+export function Tabs() {
+  const [tab, setTab] = createSignal("a")
+  return (
+    <Presence mode="wait">
+      <Show when={tab()} keyed>
+        {(t) => (
+          <motion.div
+            initial={{ opacity: 0, y: 8 }}
+            animate={{ opacity: 1, y: 0 }}
+            exit={{ opacity: 0, y: -8 }}
+          >
+            Tab {t}
+          </motion.div>
+        )}
+      </Show>
+    </Presence>
+  )
+}
+
+export function Notifications(props: { items: () => string[] }) {
+  return (
+    <Presence>
+      <For each={props.items()}>
+        {(msg) => (
+          <motion.li
+            initial={{ opacity: 0, x: -16 }}
+            animate={{ opacity: 1, x: 0 }}
+            exit={{ opacity: 0, x: 16 }}
+          >
+            {msg}
+          </motion.li>
+        )}
+      </For>
+    </Presence>
+  )
+}
+```
+
+### 11. Drag with constraints
+
+`dragConstraints` accepts numeric bounds or a parent ref. `dragElastic` controls overshoot.
+
+```tsx
+import { motion } from "solidjs-motion"
+
+export function DraggableCard() {
+  let bounds!: HTMLDivElement
+  return (
+    <div ref={bounds} class="bounds">
+      <motion.div
+        drag
+        dragConstraints={bounds}
+        dragElastic={0.2}
+        whileDrag={{ scale: 1.05 }}
+      >
+        Drag inside
+      </motion.div>
+    </div>
+  )
+}
+```
+
+### 12. `<MotionConfig>` + reduced motion
+
+`<MotionConfig>` flows defaults (transition, reduced-motion mode, CSP nonce) to descendants.
+`createReducedMotion()` reads the system preference directly.
+
+```tsx
+import { MotionConfig, createReducedMotion, motion } from "solidjs-motion"
+
+export function App() {
+  const reduced = createReducedMotion()
+  return (
+    <MotionConfig reducedMotion="user" transition={{ duration: 0.4, ease: "easeOut" }}>
+      <motion.div animate={{ x: 100 }}>Honors `prefers-reduced-motion`</motion.div>
+      <p>System reduced-motion: {String(reduced())}</p>
+    </MotionConfig>
+  )
+}
+```
+
 ## Roadmap
 
 ### Shipped

package/dist/index.js

@@ -871,6 +871,91 @@ function ensureVisualElement(el) {
 	return ve;
 }
 /**
+* Parse the visible translate from an element's transform — reads both
+* `getComputedStyle(el).transform` (which real browsers normalize to
+* matrix form) AND `el.style.transform` (which preserves the raw syntax
+* motion-dom's writer emits, e.g. `translate3d(50px, 0px, 0)`). Used by
+* drag's pan-start to sync the x/y MotionValues to what the user is
+* actually seeing.
+*
+* Why both sources: motion's `animate(el, target)` interpolates style.
+* transform via WAAPI but DOESN'T update the VE's MVs during the tween,
+* so after `initial: {x:-300} → animate: {x:0}` the MV still holds -300.
+* Reading the current transform recovers the truth. We prefer computed
+* (post-animation, post-WAAPI-commit value) and fall back to inline
+* (covers jsdom + cases where motion's writer wrote inline but the
+* browser hasn't run a style-resolve pass yet).
+*
+* Supported syntaxes:
+*   - `"none"` / empty → {0, 0}
+*   - `matrix(a, b, c, d, tx, ty)`
+*   - `matrix3d(..., tx, ty, ...)`
+*   - `translateX(Npx)` / `translateY(Npx)` / `translate(tx, ty)`
+*   - `translate3d(tx, ty, tz)`
+*   - Any of the above mixed with other transform functions (regex-
+*     based extraction picks just the translate components).
+*/
+function readVisibleTranslate(el) {
+	const fromString = (transform) => {
+		if (!transform || transform === "none") return null;
+		if (transform.startsWith("matrix3d(")) {
+			const values = transform.slice(9, -1).split(",");
+			const tx = Number.parseFloat(values[12] ?? "0");
+			const ty = Number.parseFloat(values[13] ?? "0");
+			if (!Number.isFinite(tx) && !Number.isFinite(ty)) return null;
+			return {
+				x: Number.isFinite(tx) ? tx : 0,
+				y: Number.isFinite(ty) ? ty : 0
+			};
+		}
+		if (transform.startsWith("matrix(")) {
+			const values = transform.slice(7, -1).split(",");
+			const tx = Number.parseFloat(values[4] ?? "0");
+			const ty = Number.parseFloat(values[5] ?? "0");
+			if (!Number.isFinite(tx) && !Number.isFinite(ty)) return null;
+			return {
+				x: Number.isFinite(tx) ? tx : 0,
+				y: Number.isFinite(ty) ? ty : 0
+			};
+		}
+		let x = 0;
+		let y = 0;
+		let found = false;
+		const translate3d = transform.match(/translate3d\(\s*([-\d.]+)px\s*,\s*([-\d.]+)px/);
+		if (translate3d) {
+			x = Number.parseFloat(translate3d[1] ?? "0");
+			y = Number.parseFloat(translate3d[2] ?? "0");
+			found = true;
+		} else {
+			const translate2d = transform.match(/translate\(\s*([-\d.]+)px\s*(?:,\s*([-\d.]+)px)?/);
+			if (translate2d) {
+				x = Number.parseFloat(translate2d[1] ?? "0");
+				y = Number.parseFloat(translate2d[2] ?? "0");
+				found = true;
+			}
+			const translateX = transform.match(/translateX\(\s*([-\d.]+)px/);
+			if (translateX) {
+				x = Number.parseFloat(translateX[1] ?? "0");
+				found = true;
+			}
+			const translateY = transform.match(/translateY\(\s*([-\d.]+)px/);
+			if (translateY) {
+				y = Number.parseFloat(translateY[1] ?? "0");
+				found = true;
+			}
+		}
+		if (!found) return null;
+		return {
+			x: Number.isFinite(x) ? x : 0,
+			y: Number.isFinite(y) ? y : 0
+		};
+	};
+	return fromString(getComputedStyle(el).transform) ?? fromString(el.style.transform) ?? {
+		x: 0,
+		y: 0
+	};
+}
+/**
 * Compute the `touch-action` CSS value for an element being dragged.
 * Disabling touch-action prevents the browser from interpreting the gesture
 * as a scroll. Axis-locked drags leave the unused axis available for scroll
@@ -1008,14 +1093,27 @@ function createDrag(el, getOpts, setActive) {
 		for (const ctrl of momentumControls) ctrl.stop();
 		momentumControls = [];
 	}
-	const handlePanStart = (event, info) => {
+	const handlePanStart = (event, info, mvIsAuthoritative = false) => {
 		if (!isDragEnabled()) return;
 		stopMomentum();
 		const ve = ensureVisualElement(el);
 		xMV = ve.getValue("x", 0);
 		yMV = ve.getValue("y", 0);
-		dragStartX = xMV.get();
-		dragStartY = yMV.get();
+		const axis = getOpts().drag;
+		if (mvIsAuthoritative) {
+			dragStartX = xMV.get();
+			dragStartY = yMV.get();
+		} else {
+			const visible = readVisibleTranslate(el);
+			if (axis !== "y") {
+				if (visible.x !== xMV.get()) xMV.set(visible.x);
+				dragStartX = visible.x;
+			} else dragStartX = xMV.get();
+			if (axis !== "x") {
+				if (visible.y !== yMV.get()) yMV.set(visible.y);
+				dragStartY = visible.y;
+			} else dragStartY = yMV.get();
+		}
 		sessionBounds = resolveConstraints(getOpts().dragConstraints, el, dragStartX, dragStartY);
 		savedUserSelect = document.body.style.userSelect;
 		savedTouchAction = el.style.touchAction;
@@ -1184,7 +1282,7 @@ function createDrag(el, getOpts, setActive) {
 				x: 0,
 				y: 0
 			}
-		});
+		}, Boolean(options.snapToCursor));
 		const sessionStartPoint = {
 			x: event.clientX,
 			y: event.clientY
@@ -1493,7 +1591,7 @@ function createGestureStateMachine(deps) {
 	});
 	const winners = createMemo(() => {
 		const targets = stateTargets();
-		const dragEnabled = Boolean(getOpts().drag);
+		const dragActive = active.whileDrag;
 		const out = {};
 		for (const stateName of PRIORITY_HIGH_TO_LOW) {
 			if (!isStateActive(stateName, active, parentVariantCtx)) continue;
@@ -1502,7 +1600,7 @@ function createGestureStateMachine(deps) {
 			for (const key in target) {
 				if (key === "transition") continue;
 				if (key in out) continue;
-				if (!active.exit && dragEnabled && (key === "x" || key === "y")) continue;
+				if (!active.exit && dragActive && (key === "x" || key === "y")) continue;
 				out[key] = {
 					value: target[key],
 					transition: target.transition,
@@ -1545,6 +1643,7 @@ function createGestureStateMachine(deps) {
 			}
 			for (const key in lastApplied) {
 				if (key in next) continue;
+				if (active.whileDrag && (key === "x" || key === "y")) continue;
 				const initialValue = initialTarget && key in initialTarget ? initialTarget[key] : void 0;
 				changes[key] = initialValue !== void 0 ? initialValue : getMotionDefault(key);
 			}