solid-drift 0.7.1 → 0.9.0

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