solid-drift 0.7.1 → 0.8.0

package/dist/motion.js

@@ -16,53 +16,7 @@ import { parseColorStops, sampleColorStops, } from "./color.js";
 import { resolveEasing } from "./easing.js";
 import { now, schedule } from "./engine.js";
 import { prefersReducedMotion } from "./reduced-motion.js";
-function ownerDoc(el) {
-    const od = el
-        .ownerDocument;
-    if (od)
-        return od ?? undefined;
-    return typeof document !== "undefined" ? document : undefined;
-}
-/**
- * Split an element's text into per-unit inline-block spans so each
- * letter (or word) can be transformed independently. The original text
- * is preserved as an aria-label for screen readers.
- */
-function splitUnits(el, unit) {
-    const doc = ownerDoc(el);
-    if (!doc)
-        return [];
-    const text = el.textContent ?? "";
-    el.textContent = "";
-    el.setAttribute("aria-label", text);
-    const spans = [];
-    const push = (content) => {
-        const s = doc.createElement("span");
-        s.textContent = content;
-        s.setAttribute("aria-hidden", "true");
-        s.style.display = "inline-block";
-        s.style.willChange = "transform, opacity, filter";
-        el.appendChild(s);
-        spans.push(s);
-    };
-    if (unit === "words") {
-        for (const word of text.split(/(\s+)/)) {
-            if (word.length === 0)
-                continue;
-            if (/^\s+$/.test(word)) {
-                el.appendChild(doc.createTextNode(word));
-            }
-            else {
-                push(word);
-            }
-        }
-    }
-    else {
-        for (const ch of text)
-            push(ch === " " ? " " : ch);
-    }
-    return spans;
-}
+import { mulberry32, splitUnits } from "./text.js";
 function clamp01(v) {
     return v < 0 ? 0 : v > 1 ? 1 : v;
 }
@@ -88,7 +42,8 @@ function applyKineticStyle(el, e, from) {
  *
  * One master clock drives every unit, so a headline with 40 characters
  * costs a single rAF task, not 40 timers. Units animate through the
- * same `from` state with per-unit easing.
+ * same `from` state with per-unit easing; set `from.variance` above 0
+ * for seeded per-unit jitter around those values.
  *
  * SSR-safe: no-op on the server. Under reduced motion every unit jumps
  * to its final state when `play()` runs, so the text is fully readable.
@@ -113,10 +68,13 @@ export function createKineticType(ref, options = {}) {
         scale: options.from?.scale ?? 0.85,
         opacity: options.from?.opacity ?? 0,
         rotate: options.from?.rotate ?? 0,
+        variance: options.from?.variance ?? 0,
+        seed: options.from?.seed ?? 0,
     };
     const easing = resolveEasing(easingOpt);
     const [status, setStatus] = createSignal("idle");
     let units = [];
+    let unitFrom = [];
     let controls = null;
     let runToken = 0;
     const play = () => {
@@ -124,6 +82,7 @@ export function createKineticType(ref, options = {}) {
         controls?.stop();
         controls = null;
         units = [];
+        unitFrom = [];
         if (typeof window !== "undefined") {
             const el = ref();
             if (el)
@@ -133,6 +92,29 @@ export function createKineticType(ref, options = {}) {
             setStatus("done");
             return Promise.resolve();
         }
+        // Seeded per-unit jitter around the `from` values. Deterministic
+        // for a given seed, so the same headline renders the same way on
+        // every run. Variance 0 keeps the exact legacy behavior.
+        const variance = clamp01(from.variance);
+        if (variance > 0) {
+            const rand = mulberry32(from.seed);
+            unitFrom = units.map(() => ({
+                y: from.y + variance * (rand() * 2 - 1) * 20,
+                blur: Math.max(0, from.blur + variance * (rand() * 2 - 1) * 8),
+                scale: from.scale + variance * (rand() * 2 - 1) * 0.15,
+                opacity: from.opacity,
+                rotate: from.rotate + variance * (rand() * 2 - 1) * 12,
+            }));
+        }
+        else {
+            unitFrom = units.map(() => ({
+                y: from.y,
+                blur: from.blur,
+                scale: from.scale,
+                opacity: from.opacity,
+                rotate: from.rotate,
+            }));
+        }
         setStatus("running");
         const total = duration + stagger * (units.length - 1);
         return new Promise((resolve) => {
@@ -146,7 +128,7 @@ export function createKineticType(ref, options = {}) {
                 onUpdate: (elapsed) => {
                     for (let i = 0; i < units.length; i++) {
                         const local = clamp01((elapsed - i * stagger) / duration);
-                        applyKineticStyle(units[i], easing(local), from);
+                        applyKineticStyle(units[i], easing(local), unitFrom[i]);
                     }
                 },
                 onComplete: () => {
@@ -716,6 +698,7 @@ export function createBeat(options = {}) {
         beat,
         bar,
         phase,
+        beatsPerBar: perBar,
         onBeat: (cb) => {
             listeners.add(cb);
             return () => {
@@ -727,3 +710,52 @@ export function createBeat(options = {}) {
         status,
     };
 }
+/**
+ * Guided showreel recipe: a thin typed wrapper over
+ * `createScenePlayer` for showreels and launch films. Scenes carry a
+ * named `kind` so the reel reads like a shot list, and each scene's
+ * `onEnter` wires one of the motion-graphics primitives
+ * (`createKineticType`, `createCamera`, `createColorShift`,
+ * `createTransition`, `createBeat`).
+ *
+ * Same controls, status values, and reduced-motion behavior as
+ * `createScenePlayer`: `play()` jumps to the final frame under reduced
+ * motion or on the server.
+ *
+ * ```ts
+ * const reel = createShowreel([
+ *   { kind: "title", duration: 1200, onEnter: () => titleCard.play() },
+ *   { kind: "camera", duration: 2000, onEnter: () => dolly.play() },
+ *   { kind: "color", duration: 1500, onEnter: () => finale.play() },
+ * ])
+ * beatCuts = createBeatCuts(beat, reel, { every: 8 })
+ * await reel.play()
+ * ```
+ */
+export function createShowreel(scenes) {
+    return createScenePlayer(scenes);
+}
+/**
+ * Beat-synced scene cuts: advance the player every N beats through
+ * the beat clock's `onBeat`. Returns a cleanup function that
+ * unsubscribes the cut listener.
+ *
+ * Cuts only fire while the player is running, so pausing the reel
+ * pauses the cuts too.
+ *
+ * ```ts
+ * const beat = createBeat({ bpm: 128, beatsPerBar: 4 })
+ * const stopCuts = createBeatCuts(beat, player) // cut every bar
+ * beat.start()
+ * await player.play()
+ * stopCuts()
+ * ```
+ */
+export function createBeatCuts(beat, player, options = {}) {
+    const every = Math.max(1, Math.floor(options.every ?? beat.beatsPerBar));
+    return beat.onBeat((b) => {
+        if (b % every === 0 && player.status() === "running") {
+            player.next();
+        }
+    });
+}

package/dist/text.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Internal text utilities shared by the motion-graphics primitives.
+ *
+ * Not part of the public API: family modules import from here, but
+ * nothing in this file is re-exported from the package index.
+ */
+/** Document owning the element, with an SSR-safe fallback. */
+export declare function ownerDoc(el: Element): Document | undefined;
+/**
+ * Split an element's text into per-unit inline-block spans so each
+ * letter (or word) can be transformed independently. The original text
+ * is preserved as an aria-label for screen readers. Any previous
+ * content is replaced.
+ */
+export declare function splitUnits(el: Element, unit: "chars" | "words"): HTMLElement[];
+/**
+ * Append per-unit inline-block spans for `text` to the element's
+ * existing content, without clearing it. Used by streaming text, where
+ * each flushed batch adds new units while earlier units keep playing.
+ */
+export declare function appendUnits(el: Element, text: string, unit: "chars" | "words"): HTMLElement[];
+/**
+ * Deterministic pseudo-random generator (mulberry32). Used for
+ * per-unit variance so seeded jitter renders identically on every
+ * run, which keeps tests stable and output reproducible.
+ */
+export declare function mulberry32(seed: number): () => number;

package/dist/text.js

@@ -0,0 +1,84 @@
+/**
+ * Internal text utilities shared by the motion-graphics primitives.
+ *
+ * Not part of the public API: family modules import from here, but
+ * nothing in this file is re-exported from the package index.
+ */
+/** Document owning the element, with an SSR-safe fallback. */
+export function ownerDoc(el) {
+    const od = el
+        .ownerDocument;
+    if (od)
+        return od ?? undefined;
+    return typeof document !== "undefined" ? document : undefined;
+}
+function pushUnit(doc, parent, content) {
+    const s = doc.createElement("span");
+    s.textContent = content;
+    s.setAttribute("aria-hidden", "true");
+    s.style.display = "inline-block";
+    s.style.willChange = "transform, opacity, filter";
+    parent.appendChild(s);
+    return s;
+}
+function appendTokens(doc, parent, text, unit) {
+    const spans = [];
+    if (unit === "words") {
+        for (const word of text.split(/(\s+)/)) {
+            if (word.length === 0)
+                continue;
+            if (/^\s+$/.test(word)) {
+                parent.appendChild(doc.createTextNode(word));
+            }
+            else {
+                spans.push(pushUnit(doc, parent, word));
+            }
+        }
+    }
+    else {
+        for (const ch of text)
+            spans.push(pushUnit(doc, parent, ch === " " ? " " : ch));
+    }
+    return spans;
+}
+/**
+ * Split an element's text into per-unit inline-block spans so each
+ * letter (or word) can be transformed independently. The original text
+ * is preserved as an aria-label for screen readers. Any previous
+ * content is replaced.
+ */
+export function splitUnits(el, unit) {
+    const doc = ownerDoc(el);
+    if (!doc)
+        return [];
+    const text = el.textContent ?? "";
+    el.textContent = "";
+    el.setAttribute("aria-label", text);
+    return appendTokens(doc, el, text, unit);
+}
+/**
+ * Append per-unit inline-block spans for `text` to the element's
+ * existing content, without clearing it. Used by streaming text, where
+ * each flushed batch adds new units while earlier units keep playing.
+ */
+export function appendUnits(el, text, unit) {
+    const doc = ownerDoc(el);
+    if (!doc)
+        return [];
+    return appendTokens(doc, el, text, unit);
+}
+/**
+ * Deterministic pseudo-random generator (mulberry32). Used for
+ * per-unit variance so seeded jitter renders identically on every
+ * run, which keeps tests stable and output reproducible.
+ */
+export function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a |= 0;
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}

package/dist/web3.d.ts

@@ -0,0 +1,213 @@
+/**
+ * web3 family: motion primitives for onchain product UI.
+ *
+ * Transaction lifecycle, price tickers, mint reveals, and wallet
+ * button micro-interactions, without depending on any wallet or chain
+ * library. State arrives through accessors in a wagmi/viem-style
+ * shape (the adapter pattern), so the primitives stay zero-dependency
+ * while your app keeps its own stack.
+ *
+ * All primitives are signal-native, SSR-safe, dependency-free, and
+ * define sensible static behavior under `prefers-reduced-motion`.
+ */
+import { type Accessor } from "solid-js";
+import { type Easing, type EasingName } from "./easing.js";
+type MaybeElement = () => Element | null | undefined;
+/** Stages of a transaction's life, from wallet prompt to finality. */
+export type TxState = "idle" | "signing" | "pending" | "confirming" | "success" | "failed";
+/** wagmi/viem-style transaction status fed through `source`. */
+export interface TxStatusInput {
+    /** Transaction status from the wallet/chain adapter. */
+    status?: "pending" | "success" | "error" | "idle";
+    /** Confirmations seen so far, once a hash exists. */
+    confirmations?: number;
+}
+export interface TxLifecycleOptions {
+    /**
+     * wagmi/viem-style state accessor. Omit for fully manual control
+     * through `set()`.
+     */
+    source?: Accessor<TxStatusInput>;
+    /** Confirmations that promote "pending" to "confirming". Default 1. */
+    requiredConfirmations?: number;
+    /** Spring stiffness for the progress ring. Default 170. */
+    stiffness?: number;
+    /** Spring damping for the progress ring. Default 26. */
+    damping?: number;
+    /** Called after entering a state, with the previous state. */
+    onEnter?: (state: TxState, prev: TxState) => void;
+}
+export interface TxLifecycleControls {
+    /** Current lifecycle state. */
+    state: Accessor<TxState>;
+    /**
+     * Set the state manually, for stages the chain never reports
+     * (for example "signing" when the wallet prompt opens).
+     */
+    set: (next: TxState) => void;
+    /** Return to "idle". */
+    reset: () => void;
+    /**
+     * 0 to 1 across the lifecycle, spring-smoothed for progress rings
+     * and bars: idle 0, signing 0.25, pending 0.5, confirming 0.75,
+     * success/failed 1.
+     */
+    progress: Accessor<number>;
+}
+/**
+ * Signal-native transaction lifecycle.
+ *
+ * Feed it wagmi/viem-style state through `source` and it derives the
+ * stage: a reported hash with too few confirmations is "pending",
+ * enough confirmations is "confirming", success/error map to
+ * "success"/"failed". Stages the chain never reports, like "signing"
+ * while the wallet prompt is open, are set manually.
+ *
+ * ```ts
+ * const tx = createTxLifecycle({
+ *   source: () => ({
+ *     status: receiptQuery.status, // "pending" | "success" | "error" | "idle"
+ *     confirmations: receiptQuery.confirmations,
+ *   }),
+ *   requiredConfirmations: 2,
+ * })
+ * const openWallet = () => {
+ *   tx.set("signing")
+ *   sendTransaction()
+ * }
+ * // <ProgressRing value={tx.progress()} state={tx.state()} />
+ * ```
+ *
+ * SSR-safe: "idle" with `progress()` 0. Under reduced motion state
+ * changes apply instantly and `progress()` jumps to its target.
+ */
+export declare function createTxLifecycle(options?: TxLifecycleOptions): TxLifecycleControls;
+export interface TickerOptions {
+    /** Decimals in the formatted output. Default 2. */
+    decimals?: number;
+    /** Roll duration per digit, in ms. Default 400. */
+    duration?: number;
+    /** Flash color when the value rises. Default "#16a34a". */
+    upColor?: string;
+    /** Flash color when the value falls. Default "#dc2626". */
+    downColor?: string;
+    /** How long the flash color holds, in ms. Default 600. */
+    flashMs?: number;
+    /** Locale for grouping separators. Default "en-US". */
+    locale?: string;
+}
+export interface TickerControls {
+    /** Formatted value, SSR-safe. */
+    display: Accessor<string>;
+    /** Direction of the last update: "up" | "down" | "flat". */
+    direction: Accessor<"up" | "down" | "flat">;
+}
+/**
+ * Animated price/balance ticker: per-digit roll, direction flash.
+ *
+ * Each digit is a 0-9 strip in an overflow-hidden column, driven by a
+ * single rAF task for the whole ticker. Rapid source updates batch to
+ * one render per frame, keeping only the latest value, so a hot price
+ * feed never queues animation debt. Non-digit characters (decimal
+ * point, grouping separators, minus sign) render statically.
+ *
+ * ```tsx
+ * let el!: HTMLSpanElement
+ * const [price, setPrice] = createSignal(48210.5)
+ * const ticker = createTicker(price, () => el, { decimals: 2 })
+ * <span ref={el} style={{ color: ticker.direction() === "up" ? "green" : "red" }}>
+ *   {ticker.display()}
+ * </span>
+ * ```
+ *
+ * SSR-safe: `display()` returns the formatted string with no DOM.
+ * Under reduced motion the text swaps instantly: no roll, no flash.
+ */
+export declare function createTicker(source: Accessor<number>, ref: MaybeElement, options?: TickerOptions): TickerControls;
+export type MintRevealStatus = "idle" | "anticipating" | "flipping" | "revealed";
+export interface MintRevealOptions {
+    /** Anticipation shake duration, in ms. Default 500. */
+    shakeDuration?: number;
+    /** rotateY flip duration, in ms. Default 700. */
+    flipDuration?: number;
+    /** Squash and stretch on landing. Default true. */
+    squash?: boolean;
+    /** Easing for the flip. Default "easeOutCubic". */
+    easing?: Easing | EasingName;
+    /** Called at the flip midpoint: swap the card faces here. */
+    onFlip?: () => void;
+}
+export interface MintRevealControls {
+    /** Play the full reveal choreography. Resolves when revealed. */
+    play: () => Promise<void>;
+    /** Return to "idle". */
+    reset: () => void;
+    /** Reactive status. */
+    status: Accessor<MintRevealStatus>;
+}
+/**
+ * Pack-open / card-reveal choreography, built on the cartoon family:
+ * an anticipation shake, a rotateY flip with a face swap at the
+ * midpoint, and squash and stretch driven by the flip's own velocity
+ * as the card lands. Everything stays on compositor-friendly
+ * properties (transform, and the CSS `scale` property for the deform).
+ *
+ * ```tsx
+ * let card!: HTMLDivElement
+ * const [face, setFace] = createSignal<"back" | "front">("back")
+ * const reveal = createMintReveal(() => card, {
+ *   onFlip: () => setFace("front"), // swap faces mid-flip
+ * })
+ * <button onClick={() => reveal.play()}>Reveal</button>
+ * <div ref={card} style={{ "backface-visibility": "hidden" }}>
+ *   {face() === "back" ? <CardBack /> : <NftFront />}
+ * </div>
+ * ```
+ *
+ * SSR-safe: no-op on the server, `status()` is "revealed" so the face
+ * renders statically. Under reduced motion the shake and flip are
+ * skipped and the final face shows at once.
+ */
+export declare function createMintReveal(ref: MaybeElement, options?: MintRevealOptions): MintRevealControls;
+export interface ConnectButtonOptions {
+    /** Magnetic pull strength, 0 to 1. Default 0.35. */
+    strength?: number;
+    /** Scale while pressed. Default 0.96. */
+    pressScale?: number;
+}
+export type ConnectButtonStatus = "idle" | "ticking" | "pulsing";
+export interface ConnectButtonControls {
+    /** Checkmark tick for copy-address feedback. */
+    copyTick: () => void;
+    /** Expanding ring pulse for chain switches. */
+    chainPulse: () => void;
+    /** Reactive status: "idle" | "ticking" | "pulsing". */
+    status: Accessor<ConnectButtonStatus>;
+}
+/**
+ * Wallet connect-button micro-interactions: magnetic hover pull,
+ * press scale, a checkmark tick for copy-address feedback, and an
+ * expanding ring pulse for chain switches.
+ *
+ * The button's transform is owned by the primitive (magnetic pull
+ * plus press scale); the tick and pulse animate overlay spans so
+ * they never fight the hover motion. The button is given
+ * `position: relative` the first time a tick or pulse runs, to stage
+ * the overlays.
+ *
+ * ```tsx
+ * let btn!: HTMLButtonElement
+ * const connect = createConnectButton(() => btn)
+ * const copy = async () => {
+ *   await navigator.clipboard.writeText(address())
+ *   connect.copyTick()
+ * }
+ * <button ref={btn} onClick={copy}>0x7a…f3c2</button>
+ * ```
+ *
+ * SSR-safe: no-op on the server. Under reduced motion the magnetic
+ * pull is off and the tick/pulse become instant state changes (the
+ * check shows statically, then hides).
+ */
+export declare function createConnectButton(ref: MaybeElement, options?: ConnectButtonOptions): ConnectButtonControls;
+export {};