solid-drift 0.9.0 → 0.10.0

package/README.md

@@ -467,6 +467,41 @@ const shuffle = () =>
 
 Returns `{ stop, finished }`: `stop()` halts mid-flight and restores the original transform. SSR-safe and reduced-motion safe: the mutation runs with no animation. If the element does not move, no animation runs either.
 
+### `createSharedLayout(ref, options)`
+
+Shared-element transition across mounts, the `layoutId` magic. Give the same `id` to elements that represent the same thing in different places: a tab pill, a card that opens into a detail view, a thumbnail that becomes a hero image. When the old element unmounts its rect is remembered; when the new one mounts it starts at the donor's rect and springs home, sliding and morphing into place. This is cross-mount FLIP: where `animateFlip` inverts the delta around a mutation on one element, `createSharedLayout` inverts the delta between two elements that share an identity. One active carrier per id.
+
+```tsx
+import { createSharedLayout } from "solid-drift"
+
+function TabPill(props: { id: string }) {
+  let pill!: HTMLDivElement
+  const { x, y, scaleX, scaleY } = createSharedLayout(() => pill, {
+    id: props.id,
+  })
+  return (
+    <div
+      ref={pill}
+      style={{
+        transform: `translate(${x()}px, ${y()}px) scale(${scaleX()}, ${scaleY()})`,
+      }}
+    />
+  )
+}
+
+// Only one pill is mounted at a time; it glides between tabs.
+<Show when={tab() === "a"}><TabPill id="pill" /></Show>
+<Show when={tab() === "b"}><TabPill id="pill" /></Show>
+```
+
+| Option   | Default                          | Description                                                     |
+| -------- | -------------------------------- | --------------------------------------------------------------- |
+| `id`     | required                         | Shared identity; elements with the same id hand off to each other |
+| `spring` | `{ stiffness: 260, damping: 30 }` | Spring physics for the handoff flight                           |
+| `scale`  | `true`                           | Also morph the size delta as scale                               |
+
+Returns `{ x, y, scaleX, scaleY, flying }`: the corrective transform and `flying`, true while the handoff runs. SSR-safe and reduced-motion safe: the element simply appears, with no flight.
+
 ### `springPresets`
 
 Named spring configurations for common feels. Spread into `createSpring`, `createMagnetic`, or `createTilt` options.

package/dist/flip.d.ts

@@ -1,4 +1,6 @@
+import { type Accessor } from "solid-js";
 import { type AnimateOptions, type AnimationControls } from "./animate.js";
+import type { SpringOptions } from "./spring.js";
 export interface FlipOptions {
     /** Duration in milliseconds. Default 400. */
     duration?: number;
@@ -42,3 +44,74 @@ export interface FlipOptions {
  * ```
  */
 export declare function animateFlip(ref: () => Element | null | undefined, mutate: () => void, options?: FlipOptions): AnimationControls;
+export interface SharedLayoutOptions {
+    /**
+     * Shared identity. Elements with the same id hand off to each other
+     * across mounts: the newcomer flies in from the donor's last rect.
+     */
+    id: string;
+    /**
+     * Spring physics for the handoff flight. Default
+     * `{ stiffness: 260, damping: 30 }`.
+     */
+    spring?: SpringOptions;
+    /**
+     * Also morph the size delta as scale, so growing or shrinking elements
+     * morph instead of just sliding. Default true.
+     */
+    scale?: boolean;
+}
+export interface SharedLayoutResult {
+    /** Horizontal corrective offset in pixels. */
+    x: Accessor<number>;
+    /** Vertical corrective offset in pixels. */
+    y: Accessor<number>;
+    /** Horizontal corrective scale. */
+    scaleX: Accessor<number>;
+    /** Vertical corrective scale. */
+    scaleY: Accessor<number>;
+    /** True while the handoff flight is running. */
+    flying: Accessor<boolean>;
+}
+/**
+ * Shared-element transition across mounts, the `layoutId` magic.
+ *
+ * Give the same `id` to elements that represent the same thing in
+ * different places: a tab pill, a card that opens into a detail view,
+ * a thumbnail that becomes a hero image. When the old element unmounts
+ * its rect is remembered; when the new one mounts it starts at the
+ * donor's rect and springs home, sliding and morphing into place.
+ *
+ * This is cross-mount FLIP: where `animateFlip` inverts the delta
+ * around a mutation on one element, `createSharedLayout` inverts the
+ * delta between two elements that share an identity. Bind the returned
+ * values as a transform on the mounted element.
+ *
+ * SSR-safe and reduced-motion safe: the element simply appears, with
+ * no flight. One active carrier per id: the first mount consumes the
+ * parked donor rect.
+ *
+ * ```tsx
+ * import { createSharedLayout } from "solid-drift"
+ *
+ * function TabPill(props: { id: string }) {
+ *   let pill!: HTMLDivElement
+ *   const { x, y, scaleX, scaleY } = createSharedLayout(() => pill, {
+ *     id: props.id,
+ *   })
+ *   return (
+ *     <div
+ *       ref={pill}
+ *       style={{
+ *         transform: `translate(${x()}px, ${y()}px) scale(${scaleX()}, ${scaleY()})`,
+ *       }}
+ *     />
+ *   )
+ * }
+ *
+ * // Only one pill is mounted at a time; it glides between tabs.
+ * <Show when={tab() === "a"}><TabPill id="pill" /></Show>
+ * <Show when={tab() === "b"}><TabPill id="pill" /></Show>
+ * ```
+ */
+export declare function createSharedLayout(ref: () => Element | null | undefined, options: SharedLayoutOptions): SharedLayoutResult;

package/dist/flip.js

@@ -1,4 +1,6 @@
+import { createEffect, createSignal, onCleanup, } from "solid-js";
 import { animate, } from "./animate.js";
+import { now, schedule } from "./engine.js";
 import { prefersReducedMotion } from "./reduced-motion.js";
 /**
  * FLIP layout animation around a DOM mutation.
@@ -106,3 +108,158 @@ export function animateFlip(ref, mutate, options = {}) {
     }));
     return controls;
 }
+/**
+ * Donor registry for shared-element handoffs. When an element carrying a
+ * shared id unmounts, its last rect is parked here; the next element that
+ * mounts with the same id consumes it and flies in from that rect.
+ * One active carrier per id: consumption deletes the entry.
+ */
+const donors = new Map();
+function rectOf(el) {
+    const r = el.getBoundingClientRect();
+    return { left: r.left, top: r.top, width: r.width, height: r.height };
+}
+const zero = () => 0;
+const one = () => 1;
+const no = () => false;
+/**
+ * Shared-element transition across mounts, the `layoutId` magic.
+ *
+ * Give the same `id` to elements that represent the same thing in
+ * different places: a tab pill, a card that opens into a detail view,
+ * a thumbnail that becomes a hero image. When the old element unmounts
+ * its rect is remembered; when the new one mounts it starts at the
+ * donor's rect and springs home, sliding and morphing into place.
+ *
+ * This is cross-mount FLIP: where `animateFlip` inverts the delta
+ * around a mutation on one element, `createSharedLayout` inverts the
+ * delta between two elements that share an identity. Bind the returned
+ * values as a transform on the mounted element.
+ *
+ * SSR-safe and reduced-motion safe: the element simply appears, with
+ * no flight. One active carrier per id: the first mount consumes the
+ * parked donor rect.
+ *
+ * ```tsx
+ * import { createSharedLayout } from "solid-drift"
+ *
+ * function TabPill(props: { id: string }) {
+ *   let pill!: HTMLDivElement
+ *   const { x, y, scaleX, scaleY } = createSharedLayout(() => pill, {
+ *     id: props.id,
+ *   })
+ *   return (
+ *     <div
+ *       ref={pill}
+ *       style={{
+ *         transform: `translate(${x()}px, ${y()}px) scale(${scaleX()}, ${scaleY()})`,
+ *       }}
+ *     />
+ *   )
+ * }
+ *
+ * // Only one pill is mounted at a time; it glides between tabs.
+ * <Show when={tab() === "a"}><TabPill id="pill" /></Show>
+ * <Show when={tab() === "b"}><TabPill id="pill" /></Show>
+ * ```
+ */
+export function createSharedLayout(ref, options) {
+    const { id, spring = {}, scale = true } = options;
+    if (typeof window === "undefined") {
+        return { x: zero, y: zero, scaleX: one, scaleY: one, flying: no };
+    }
+    const [x, setX] = createSignal(0);
+    const [y, setY] = createSignal(0);
+    const [scaleX, setScaleX] = createSignal(1);
+    const [scaleY, setScaleY] = createSignal(1);
+    const [flying, setFlying] = createSignal(false);
+    let cancelFlight = null;
+    const stopFlight = () => {
+        cancelFlight?.();
+        cancelFlight = null;
+    };
+    /** Spring flight from the inverted delta back to identity. */
+    const flyFrom = (dx, dy, sx, sy) => {
+        const { stiffness = 260, damping = 30 } = spring;
+        let cx = dx;
+        let cy = dy;
+        let csx = sx;
+        let csy = sy;
+        let vx = 0;
+        let vy = 0;
+        let vsx = 0;
+        let vsy = 0;
+        let last = now();
+        setX(cx);
+        setY(cy);
+        setScaleX(csx);
+        setScaleY(csy);
+        setFlying(true);
+        stopFlight();
+        const task = (t) => {
+            const dt = Math.min(Math.max((t - last) / 1000, 0), 0.064);
+            last = t;
+            // Semi-implicit Euler per channel, same integrator as createSpring.
+            vx += (-stiffness * cx - damping * vx) * dt;
+            vy += (-stiffness * cy - damping * vy) * dt;
+            vsx += (-stiffness * (csx - 1) - damping * vsx) * dt;
+            vsy += (-stiffness * (csy - 1) - damping * vsy) * dt;
+            cx += vx * dt;
+            cy += vy * dt;
+            csx += vsx * dt;
+            csy += vsy * dt;
+            setX(cx);
+            setY(cy);
+            setScaleX(csx);
+            setScaleY(csy);
+            const settled = Math.hypot(cx, cy) < 0.5 &&
+                Math.abs(csx - 1) < 0.003 &&
+                Math.abs(csy - 1) < 0.003 &&
+                Math.hypot(vx, vy) < 20 &&
+                Math.hypot(vsx, vsy) < 0.05;
+            if (settled) {
+                setX(0);
+                setY(0);
+                setScaleX(1);
+                setScaleY(1);
+                setFlying(false);
+                cancelFlight = null;
+                return false;
+            }
+            return true;
+        };
+        cancelFlight = schedule(task);
+    };
+    // Late-bound refs (Solid assigns `ref` after mount) still hand off.
+    createEffect(() => {
+        const el = ref();
+        if (!el)
+            return;
+        const mountRect = rectOf(el);
+        const donor = donors.get(id);
+        donors.delete(id);
+        if (donor && !prefersReducedMotion()) {
+            const own = mountRect;
+            const dx = donor.left - own.left;
+            const dy = donor.top - own.top;
+            const sx = scale && own.width > 0 ? donor.width / own.width : 1;
+            const sy = scale && own.height > 0 ? donor.height / own.height : 1;
+            const moved = Math.abs(dx) >= 0.5 ||
+                Math.abs(dy) >= 0.5 ||
+                Math.abs(sx - 1) >= 0.002 ||
+                Math.abs(sy - 1) >= 0.002;
+            if (moved)
+                flyFrom(dx, dy, sx, sy);
+        }
+        onCleanup(() => {
+            // In <Show>/<Switch>/&& branches the cleanup runs while the node
+            // is still attached, so this is the live rect. If the node was
+            // already detached (all-zero rect), keep the mount snapshot.
+            const r = rectOf(el);
+            const valid = r.width > 0 || r.height > 0 || r.left !== 0 || r.top !== 0;
+            donors.set(id, valid ? r : mountRect);
+        });
+    });
+    onCleanup(() => stopFlight());
+    return { x, y, scaleX, scaleY, flying };
+}

package/dist/index.d.ts

@@ -19,7 +19,7 @@ export { createVelocity, type VelocityOptions } from "./velocity.js";
 export { createMagnetic, type MagneticOptions, type MagneticResult, createTilt, type TiltOptions, type TiltResult, } from "./pointer.js";
 export { createTrail, type TrailOptions } from "./trail.js";
 export { createTimeline, type TimelineStep, type TimelineStatus, type TimelineControls, } from "./timeline.js";
-export { animateFlip, type FlipOptions } from "./flip.js";
+export { animateFlip, type FlipOptions, createSharedLayout, type SharedLayoutOptions, type SharedLayoutResult, } from "./flip.js";
 export { createSquashStretch, type SquashStretchOptions, type SquashStretchResult, createFollowThrough, type FollowThroughOptions, createAnticipation, type AnticipationOptions, createWobble, type WobbleOptions, type WobbleResult, } from "./cartoon.js";
 export { createGravity, type GravityOptions, type GravityResult, createPendulum, type PendulumOptions, type PendulumResult, createFling, type FlingOptions, type FlingResult, } from "./physics.js";
 export { createFontSwap, type FontSwapOptions, type FontSwapResult, createTyping, type TypingOptions, type TypingResult, createTextPhysics, type TextPhysicsOptions, type TextPhysicsResult, createTextTunnel, type TextTunnelOptions, type TextTunnelResult, createTextCutout, type TextCutoutOptions, createTextGradient, type TextGradientOptions, createTextScramble, type TextScrambleOptions, type TextScrambleResult, createTextWave, type TextWaveOptions, } from "./typography.js";

package/dist/index.js

@@ -19,7 +19,7 @@ export { createVelocity } from "./velocity.js";
 export { createMagnetic, createTilt, } from "./pointer.js";
 export { createTrail } from "./trail.js";
 export { createTimeline, } from "./timeline.js";
-export { animateFlip } from "./flip.js";
+export { animateFlip, createSharedLayout, } from "./flip.js";
 export { createSquashStretch, createFollowThrough, createAnticipation, createWobble, } from "./cartoon.js";
 export { createGravity, createPendulum, createFling, } from "./physics.js";
 export { createFontSwap, createTyping, createTextPhysics, createTextTunnel, createTextCutout, createTextGradient, createTextScramble, createTextWave, } from "./typography.js";

package/package.json

@@ -43,5 +43,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.9.0"
+  "version": "0.10.0"
 }