solid-drift 0.2.0 → 0.8.0

package/dist/velocity.d.ts

@@ -0,0 +1,44 @@
+import { type Accessor } from "solid-js";
+export interface VelocityOptions {
+    /**
+     * Exponential smoothing of the raw velocity, 0 to 1. Higher values
+     * react slower and ride smoother. Default 0.8.
+     */
+    smoothing?: number;
+    /** Multiplier applied to the raw units per second. Default 1. */
+    scale?: number;
+    /**
+     * Seconds of stillness after which the velocity settles to exactly 0.
+     * Default 0.12.
+     */
+    settleAfter?: number;
+}
+/**
+ * A signal tracking how fast another signal is changing, in scaled units
+ * per second, smoothed with an exponential moving average.
+ *
+ * The classic use is scroll velocity: it spikes while the user flings the
+ * page and eases back to 0 when scrolling stops, which makes it perfect
+ * for velocity-driven skew, stretch, or motion blur that intensifies with
+ * speed. With no source it measures page scroll in pixels per second.
+ *
+ * The measurement loop runs on the shared clock only while the value is
+ * live: it kicks off when the source changes and parks itself once the
+ * velocity settles back to 0.
+ *
+ * SSR-safe: returns a constant `0` accessor on the server. Under reduced
+ * motion it also returns constant `0`, since velocity-reactive effects
+ * are motion by another name.
+ *
+ * ```tsx
+ * // Skew a list while the user scrolls fast, relax when they stop.
+ * const velocity = createVelocity() // px per second of page scroll
+ * const skew = () => Math.max(-8, Math.min(8, velocity() / 120))
+ * <ul style={{ transform: `skewY(${skew()}deg)` }}>…</ul>
+ *
+ * // Velocity of any signal, in its own units per second.
+ * const [n, setN] = createSignal(0)
+ * const speed = createVelocity(n, { smoothing: 0.7 })
+ * ```
+ */
+export declare function createVelocity(source?: Accessor<number>, options?: VelocityOptions): Accessor<number>;

package/dist/velocity.js

@@ -0,0 +1,88 @@
+import { createEffect, createSignal, onCleanup, untrack, } from "solid-js";
+import { now, schedule } from "./engine.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+/**
+ * A signal tracking how fast another signal is changing, in scaled units
+ * per second, smoothed with an exponential moving average.
+ *
+ * The classic use is scroll velocity: it spikes while the user flings the
+ * page and eases back to 0 when scrolling stops, which makes it perfect
+ * for velocity-driven skew, stretch, or motion blur that intensifies with
+ * speed. With no source it measures page scroll in pixels per second.
+ *
+ * The measurement loop runs on the shared clock only while the value is
+ * live: it kicks off when the source changes and parks itself once the
+ * velocity settles back to 0.
+ *
+ * SSR-safe: returns a constant `0` accessor on the server. Under reduced
+ * motion it also returns constant `0`, since velocity-reactive effects
+ * are motion by another name.
+ *
+ * ```tsx
+ * // Skew a list while the user scrolls fast, relax when they stop.
+ * const velocity = createVelocity() // px per second of page scroll
+ * const skew = () => Math.max(-8, Math.min(8, velocity() / 120))
+ * <ul style={{ transform: `skewY(${skew()}deg)` }}>…</ul>
+ *
+ * // Velocity of any signal, in its own units per second.
+ * const [n, setN] = createSignal(0)
+ * const speed = createVelocity(n, { smoothing: 0.7 })
+ * ```
+ */
+export function createVelocity(source, options = {}) {
+    if (typeof window === "undefined" || prefersReducedMotion()) {
+        return () => 0;
+    }
+    const { smoothing = 0.8, scale = 1, settleAfter = 0.12 } = options;
+    const read = source ?? (() => window.scrollY);
+    const [velocity, setVelocity] = createSignal(0);
+    let current = 0;
+    let lastValue = untrack(read);
+    let lastT = now();
+    let lastChangeT = lastT;
+    let cancel = null;
+    const loop = (t) => {
+        const value = untrack(read);
+        const dt = Math.max((t - lastT) / 1000, 0.0001);
+        if (value !== lastValue) {
+            const instant = ((value - lastValue) / dt) * scale;
+            current = current * smoothing + instant * (1 - smoothing);
+            lastValue = value;
+            lastChangeT = t;
+        }
+        else if (t - lastChangeT > settleAfter * 1000) {
+            current = 0;
+        }
+        else {
+            // Coast down smoothly between samples instead of holding stale speed.
+            current *= Math.pow(0.02, dt);
+        }
+        lastT = t;
+        setVelocity(current);
+        const settled = Math.abs(current) < 0.001 && t - lastChangeT > settleAfter * 1000;
+        if (settled) {
+            setVelocity(0);
+            cancel = null;
+            return false;
+        }
+        return true;
+    };
+    const kick = () => {
+        if (cancel)
+            return;
+        lastT = now();
+        cancel = schedule(loop);
+    };
+    createEffect(() => {
+        read(); // track the source so any change kicks the loop
+        kick();
+    });
+    if (!source) {
+        // The default page-scroll source is not a reactive signal, so scroll
+        // events kick the loop explicitly.
+        window.addEventListener("scroll", kick, { passive: true });
+        onCleanup(() => window.removeEventListener("scroll", kick));
+    }
+    onCleanup(() => cancel?.());
+    return velocity;
+}

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 {};