solid-drift 0.9.0 → 0.11.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.
@@ -741,6 +776,25 @@ createTextWave(() => headline, {
 
 Options: `amplitude`, `wavelength` (characters per wave), `period`, `tilt` (default true), `progress`. Returns `{ stop }`. Under reduced motion the text sits still.
 
+### `createCountUp(source, options?)`
+
+A signal that counts toward a source number with an eased tween, rendering as a formatted string: dashboard stats, prices, scores. When the source changes mid-count the tween retargets from the current displayed value, with no snapping.
+
+```tsx
+import { createCountUp } from "solid-drift"
+
+const [revenue, setRevenue] = createSignal(0)
+const display = createCountUp(revenue, {
+  decimals: 2,
+  prefix: "$",
+  separator: ",",
+})
+<div>{display()}</div> // "$1,234.50" gliding up from "$0.00"
+setRevenue(1234.5)
+```
+
+Options: `decimals` (default 0), `duration` (ms, default 1000), `easing` (default `"easeOutExpo"`), `prefix` (default `""`), `suffix` (default `""`), `separator` (thousands separator, default `""`). Returns an accessor of the formatted string. SSR-safe: renders the formatted source value. Under reduced motion the text jumps straight to each new value.
+
 ### `createKineticType(ref, options?)`
 
 Kinetic typography: each character (or word) flies in with position, blur, scale, and opacity, staggered for that showreel title feel. One master clock drives every unit, so a 40-character headline costs a single rAF task.

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,10 +19,10 @@ 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";
+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, createCountUp, type CountUpOptions, } from "./typography.js";
 export { easings, cubicBezier, linear, easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeInQuart, easeOutQuart, easeInOutQuart, easeOutExpo, easeOutBack, easeInBack, easeInOutBack, easeOutElastic, easeOutBounce, resolveEasing, type Easing, type EasingName, } from "./easing.js";
 export { createKineticType, createScenePlayer, createShowreel, createCamera, createColorShift, createTransition, createBeat, createBeatCuts, } from "./motion.js";
 export type { KineticTypeFrom, KineticTypeOptions, KineticTypeStatus, KineticTypeControls, MotionScene, ScenePlayerStatus, ScenePlayerControls, ShowreelScene, ShowreelSceneKind, CameraKeyframe, CameraOptions, ColorShiftOptions, ColorShiftStatus, ColorShiftControls, TransitionType, TransitionDirection, TransitionOptions, TransitionLayerStyle, TransitionStatus, TransitionControls, BeatOptions, BeatStatus, BeatControls, BeatCutOptions, } from "./motion.js";

package/dist/index.js

@@ -19,10 +19,10 @@ 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";
+export { createFontSwap, createTyping, createTextPhysics, createTextTunnel, createTextCutout, createTextGradient, createTextScramble, createTextWave, createCountUp, } from "./typography.js";
 export { easings, cubicBezier, linear, easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeInQuart, easeOutQuart, easeInOutQuart, easeOutExpo, easeOutBack, easeInBack, easeInOutBack, easeOutElastic, easeOutBounce, resolveEasing, } from "./easing.js";
 export { createKineticType, createScenePlayer, createShowreel, createCamera, createColorShift, createTransition, createBeat, createBeatCuts, } from "./motion.js";
 export { createDrag, } from "./gesture.js";

package/dist/typography.d.ts

@@ -238,4 +238,43 @@ export interface TextWaveOptions {
 export declare function createTextWave(ref: MaybeElement, options?: TextWaveOptions): {
     stop: () => void;
 };
+export interface CountUpOptions {
+    /** Decimal places in the output. Default 0. */
+    decimals?: number;
+    /** Tween duration in milliseconds when the source changes. Default 1000. */
+    duration?: number;
+    /** Easing for the count. Default "easeOutExpo". */
+    easing?: Easing | EasingName;
+    /** String placed before the number, e.g. "$". Default "". */
+    prefix?: string;
+    /** String placed after the number, e.g. "%". Default "". */
+    suffix?: string;
+    /** Thousands separator, e.g. ",". Default "" (no grouping). */
+    separator?: string;
+}
+/**
+ * A signal that counts toward a source number with an eased tween,
+ * rendering as a formatted string: dashboard stats, prices, scores.
+ *
+ * When the source changes mid-count the tween retargets from the
+ * current displayed value, with no snapping. Formatting (decimals,
+ * prefix, suffix, thousands separator) applies to every frame.
+ *
+ * SSR-safe: renders the formatted source value. Under reduced motion
+ * the text jumps straight to each new value with no tween.
+ *
+ * ```tsx
+ * import { createCountUp } from "solid-drift"
+ *
+ * const [revenue, setRevenue] = createSignal(0)
+ * const display = createCountUp(revenue, {
+ *   decimals: 2,
+ *   prefix: "$",
+ *   separator: ",",
+ * })
+ * <div>{display()}</div> // "$1,234.50" gliding up from "$0.00"
+ * setRevenue(1234.5)
+ * ```
+ */
+export declare function createCountUp(source: Accessor<number>, options?: CountUpOptions): Accessor<string>;
 export {};

package/dist/typography.js

@@ -1,5 +1,6 @@
 import { createEffect, createSignal, onCleanup, untrack, } from "solid-js";
 import { animate } from "./animate.js";
+import { createTween } from "./tween.js";
 import { resolveEasing } from "./easing.js";
 import { now, schedule } from "./engine.js";
 import { prefersReducedMotion } from "./reduced-motion.js";
@@ -810,3 +811,47 @@ export function createTextWave(ref, options = {}) {
         },
     };
 }
+function groupInteger(int, separator) {
+    if (!separator)
+        return int;
+    const negative = int.startsWith("-");
+    const digits = negative ? int.slice(1) : int;
+    const grouped = digits.replace(/\B(?=(\d{3})+(?!\d))/g, separator);
+    return (negative ? "-" : "") + grouped;
+}
+/**
+ * A signal that counts toward a source number with an eased tween,
+ * rendering as a formatted string: dashboard stats, prices, scores.
+ *
+ * When the source changes mid-count the tween retargets from the
+ * current displayed value, with no snapping. Formatting (decimals,
+ * prefix, suffix, thousands separator) applies to every frame.
+ *
+ * SSR-safe: renders the formatted source value. Under reduced motion
+ * the text jumps straight to each new value with no tween.
+ *
+ * ```tsx
+ * import { createCountUp } from "solid-drift"
+ *
+ * const [revenue, setRevenue] = createSignal(0)
+ * const display = createCountUp(revenue, {
+ *   decimals: 2,
+ *   prefix: "$",
+ *   separator: ",",
+ * })
+ * <div>{display()}</div> // "$1,234.50" gliding up from "$0.00"
+ * setRevenue(1234.5)
+ * ```
+ */
+export function createCountUp(source, options = {}) {
+    const { decimals = 0, duration = 1000, easing = "easeOutExpo", prefix = "", suffix = "", separator = "", } = options;
+    const tweened = createTween(source, { duration, easing });
+    const format = (value) => {
+        const fixed = value.toFixed(decimals);
+        const dot = fixed.indexOf(".");
+        const head = dot === -1 ? fixed : fixed.slice(0, dot);
+        const tail = dot === -1 ? "" : fixed.slice(dot);
+        return prefix + groupInteger(head, separator) + tail + suffix;
+    };
+    return () => format(tweened());
+}

package/package.json

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