solid-drift 0.29.0 → 0.31.0

package/README.md

@@ -1643,6 +1643,61 @@ const spy = createScrollSpy({ targets: ["intro", "api", "faq"], offset: 80 });
 - `createSkeleton(options?)` is a loading-placeholder controller with flicker protection: `{ loading, show, phase, setLoading }`. `show()` flips true only after `delay` ms (default 200), so fast loads never flash a skeleton, and stays true for at least `minVisible` ms once shown. `phase()` sweeps 0..1 on the shared clock while shown for a JS-driven shimmer (bind it to a gradient stop); it freezes under reduced motion. On the server `show()` never flips.
 - `createScrollSpy(options)` tracks the deepest section at or above the offset line: `{ active, scrollTo, refresh }`. `targets` is an id list or accessor; `container` defaults to the window (pass an element for a scrollable panel); scroll handling is rAF-throttled on the shared clock; `scrollTo(id)` smooth-scrolls (auto under reduced motion); `onChange` fires only when the active id changes. SSR-safe.
 
+### Copy and countdown
+
+```tsx
+import { createCopy, createCountdown } from "solid-drift";
+
+const clipboard = createCopy();
+const sale = createCountdown(new Date("2026-12-01T00:00:00"), {
+  onDone: () => toast("The sale has ended"),
+});
+
+<button onClick={() => clipboard.copy(link())}>
+  {clipboard.copied() ? "Copied!" : "Copy link"}
+</button>
+<p>{sale.days()}d {sale.hours()}h {sale.minutes()}m {sale.seconds()}s</p>
+```
+
+- `createCopy(options?)` copies text to the clipboard: `{ copied, error, copy, reset }`. Uses the async Clipboard API with an `execCommand` fallback (`noFallback: true` disables it). `copied()` flips true for `resetDelay` ms (default 2000) for transient "Copied!" feedback. SSR-safe.
+- `createCountdown(target, options?)` counts down to a date, timestamp, or accessor: `{ remaining, days, hours, minutes, seconds, done, running, start, stop, reset }`. Wall-clock based (the moment is fixed even if the tab hides); recomputes on the shared clock throttled to `interval` ms (default 1000); stops itself at zero and fires `onDone` once. SSR-safe.
+
+### Marquee, variants, path drawing, press and hover
+
+```tsx
+import {
+  createMarquee,
+  createVariants,
+  createPathDraw,
+  createPress,
+  createHover,
+} from "solid-drift";
+
+const marquee = createMarquee({ speed: 80 });
+const card = createVariants(
+  {
+    idle: { scale: 1 },
+    hover: { scale: 1.04 },
+    press: { scale: 0.96 },
+  },
+  { initial: "idle", duration: 180 },
+);
+
+let strip!: HTMLDivElement;
+let btn!: HTMLButtonElement;
+let mark!: SVGPathElement;
+createEffect(() => marquee.setContentSize(strip.scrollWidth / 2));
+createHover(() => btn, { onChange: (h) => card.go(h ? "hover" : "idle") });
+createPress(() => btn, { onChange: (p) => card.go(p ? "press" : "idle") });
+const draw = createPathDraw(() => mark, { duration: 1600 });
+```
+
+- `createMarquee(options?)` infinite scroller: `{ offset, running, setContentSize, start, stop }`. The offset advances at `speed` px/s (`direction` left/right/up/down) on the shared clock and wraps at the content size; render the content twice and translate by `-offset()`. Measure one loop unit and pass it to `setContentSize`. Static under reduced motion; SSR-safe.
+- `createVariants(defs, options?)` named animation states: `{ current, values, go }`. `go(name)` tweens numeric props from the current values to the target variant (`duration` ms, easing) and snaps non-numeric props at the end; unknown names are ignored. Snaps instantly under reduced motion; SSR-safe.
+- `createPathDraw(ref, options?)` SVG stroke draw-on: `{ progress, running, start, stop, reset }`. Reads the length with `getTotalLength()` and drives `stroke-dashoffset` to 0, eased; `onDone` fires once; resume keeps a constant speed. Renders fully drawn under reduced motion; SSR-safe.
+- `createPress(ref, options?)` press gesture state: `{ pressed }`. Pointer down/up/cancel/leave plus Enter/Space keys for keyboard parity; `onChange` fires on change only. State only, no animation; pair with `createVariants`. SSR-safe.
+- `createHover(ref, options?)` hover gesture state: `{ hovering }`. Pointer enter/leave plus focus/blur for keyboard parity; `onChange` fires on change only. SSR-safe.
+
 ### Easings
 
 Named easings: `linear`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeInQuart`, `easeOutQuart`, `easeInOutQuart`, `easeOutExpo`, `easeOutBack`, plus the cartoon set: `easeInBack` (anticipation dip before movement), `easeInOutBack` (wind-up, overshoot, settle), `easeOutElastic` (decaying rubber-band oscillation), `easeOutBounce` (shrinking cartoon bounces). Also `cubicBezier(x1, y1, x2, y2)` for CSS-style curves. Pass a name or a custom `(t) => number` function anywhere an easing is accepted.

package/dist/copy.d.ts

@@ -0,0 +1,27 @@
+export interface CopyOptions {
+    /** Milliseconds before `copied` flips back to false. Default 2000. */
+    resetDelay?: number;
+    /** Skip the execCommand fallback and require the async Clipboard API. Default false. */
+    noFallback?: boolean;
+}
+export interface CopyControls {
+    /** True briefly after a successful copy (for "Copied!" feedback). */
+    copied: () => boolean;
+    error: () => Error | null;
+    copy: (text: string) => Promise<void>;
+    reset: () => void;
+}
+/**
+ * createCopy
+ *
+ * Copy-to-clipboard with a `copied` flag for transient feedback. Uses the
+ * async Clipboard API with an `execCommand` fallback for older browsers.
+ *
+ * ```tsx
+ * const clipboard = createCopy();
+ * <button onClick={() => clipboard.copy(link())}>
+ *   {clipboard.copied() ? "Copied!" : "Copy link"}
+ * </button>
+ * ```
+ */
+export declare function createCopy(options?: CopyOptions): CopyControls;

package/dist/copy.js

@@ -0,0 +1,80 @@
+import { createSignal, onCleanup } from "solid-js";
+function legacyCopy(text) {
+    const doc = globalThis.document;
+    if (!doc || typeof doc.execCommand !== "function") {
+        throw new Error("Clipboard API is not supported.");
+    }
+    const area = doc.createElement("textarea");
+    area.value = text;
+    area.setAttribute("readonly", "");
+    area.style.position = "fixed";
+    area.style.opacity = "0";
+    doc.body.appendChild(area);
+    area.select();
+    const ok = doc.execCommand("copy");
+    doc.body.removeChild(area);
+    if (!ok)
+        throw new Error("Copy command failed.");
+}
+/**
+ * createCopy
+ *
+ * Copy-to-clipboard with a `copied` flag for transient feedback. Uses the
+ * async Clipboard API with an `execCommand` fallback for older browsers.
+ *
+ * ```tsx
+ * const clipboard = createCopy();
+ * <button onClick={() => clipboard.copy(link())}>
+ *   {clipboard.copied() ? "Copied!" : "Copy link"}
+ * </button>
+ * ```
+ */
+export function createCopy(options = {}) {
+    const { resetDelay = 2000, noFallback = false } = options;
+    const [copied, setCopied] = createSignal(false);
+    const [error, setError] = createSignal(null);
+    let timer = null;
+    const markCopied = () => {
+        setCopied(true);
+        if (timer !== null)
+            clearTimeout(timer);
+        timer = null;
+        if (resetDelay > 0) {
+            timer = setTimeout(() => {
+                timer = null;
+                setCopied(false);
+            }, resetDelay);
+        }
+    };
+    const copy = async (text) => {
+        setError(null);
+        const nav = globalThis.navigator;
+        try {
+            const writeText = nav?.clipboard?.writeText;
+            if (typeof writeText === "function") {
+                await writeText.call(nav?.clipboard, text);
+                markCopied();
+                return;
+            }
+            if (!noFallback) {
+                legacyCopy(text);
+                markCopied();
+                return;
+            }
+            throw new Error("Clipboard API is not supported.");
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            setError(err);
+            throw err;
+        }
+    };
+    const reset = () => {
+        if (timer !== null)
+            clearTimeout(timer);
+        timer = null;
+        setCopied(false);
+    };
+    onCleanup(reset);
+    return { copied, error, copy, reset };
+}

package/dist/countdown.d.ts

@@ -0,0 +1,38 @@
+export interface CountdownOptions {
+    /** Milliseconds between recomputes. Default 1000. */
+    interval?: number;
+    /** Start immediately on creation. Default true. */
+    autoStart?: boolean;
+    onDone?: () => void;
+}
+export interface CountdownControls {
+    /** Milliseconds remaining, clamped at 0. */
+    remaining: () => number;
+    days: () => number;
+    hours: () => number;
+    minutes: () => number;
+    seconds: () => number;
+    done: () => boolean;
+    running: () => boolean;
+    start: () => void;
+    stop: () => void;
+    reset: () => void;
+}
+/**
+ * createCountdown
+ *
+ * Countdown to a target date or timestamp. Uses wall-clock time (a sale
+ * ends at a real moment even if the tab was hidden) and recomputes on
+ * the shared clock, throttled to `interval`. The task stops itself at
+ * zero and `onDone` fires exactly once. `stop()` halts display updates;
+ * the target is a fixed wall-clock moment, so `start()` resumes against
+ * the same target.
+ *
+ * ```tsx
+ * const sale = createCountdown(new Date("2026-12-01T00:00:00"), {
+ *   onDone: () => toast("The sale has ended"),
+ * });
+ * <p>{sale.days()}d {sale.hours()}h {sale.minutes()}m {sale.seconds()}s</p>
+ * ```
+ */
+export declare function createCountdown(target: Date | number | (() => Date | number), options?: CountdownOptions): CountdownControls;

package/dist/countdown.js

@@ -0,0 +1,90 @@
+import { createSignal, onCleanup } from "solid-js";
+import { schedule } from "./engine.js";
+/**
+ * createCountdown
+ *
+ * Countdown to a target date or timestamp. Uses wall-clock time (a sale
+ * ends at a real moment even if the tab was hidden) and recomputes on
+ * the shared clock, throttled to `interval`. The task stops itself at
+ * zero and `onDone` fires exactly once. `stop()` halts display updates;
+ * the target is a fixed wall-clock moment, so `start()` resumes against
+ * the same target.
+ *
+ * ```tsx
+ * const sale = createCountdown(new Date("2026-12-01T00:00:00"), {
+ *   onDone: () => toast("The sale has ended"),
+ * });
+ * <p>{sale.days()}d {sale.hours()}h {sale.minutes()}m {sale.seconds()}s</p>
+ * ```
+ */
+export function createCountdown(target, options = {}) {
+    const { interval = 1000, autoStart = true, onDone } = options;
+    const [remaining, setRemaining] = createSignal(0);
+    const [done, setDone] = createSignal(false);
+    const [running, setRunning] = createSignal(false);
+    let stopClock = null;
+    let doneFired = false;
+    const targetMs = () => {
+        const t = typeof target === "function" ? target() : target;
+        return t instanceof Date ? t.getTime() : t;
+    };
+    const compute = (nowMs) => {
+        const left = Math.max(0, targetMs() - nowMs);
+        setRemaining(left);
+        if (left <= 0 && !doneFired) {
+            doneFired = true;
+            setDone(true);
+            stopClock?.();
+            stopClock = null;
+            setRunning(false);
+            onDone?.();
+        }
+    };
+    const start = () => {
+        if (running())
+            return;
+        doneFired = false;
+        setDone(false);
+        compute(Date.now());
+        if (done())
+            return;
+        if (typeof globalThis.requestAnimationFrame === "undefined")
+            return;
+        setRunning(true);
+        let last = Date.now();
+        stopClock = schedule(() => {
+            const nowMs = Date.now();
+            if (nowMs - last >= interval) {
+                last = nowMs;
+                compute(nowMs);
+            }
+            return !done();
+        });
+    };
+    const stop = () => {
+        stopClock?.();
+        stopClock = null;
+        setRunning(false);
+    };
+    const reset = () => {
+        stop();
+        doneFired = false;
+        setDone(false);
+        compute(Date.now());
+    };
+    onCleanup(stop);
+    if (autoStart)
+        start();
+    return {
+        remaining,
+        days: () => Math.floor(remaining() / 86400000),
+        hours: () => Math.floor(remaining() / 3600000) % 24,
+        minutes: () => Math.floor(remaining() / 60000) % 60,
+        seconds: () => Math.floor(remaining() / 1000) % 60,
+        done,
+        running,
+        start,
+        stop,
+        reset,
+    };
+}

package/dist/index.d.ts

@@ -52,3 +52,15 @@ export { createSkeleton } from "./skeleton.js";
 export type { SkeletonOptions, SkeletonControls } from "./skeleton.js";
 export { createScrollSpy } from "./scrollspy.js";
 export type { ScrollSpyOptions, ScrollSpyControls } from "./scrollspy.js";
+export { createCopy } from "./copy.js";
+export type { CopyOptions, CopyControls } from "./copy.js";
+export { createCountdown } from "./countdown.js";
+export type { CountdownOptions, CountdownControls } from "./countdown.js";
+export { createMarquee } from "./marquee.js";
+export type { MarqueeDirection, MarqueeOptions, MarqueeControls, } from "./marquee.js";
+export { createVariants } from "./variants.js";
+export type { VariantDef, VariantsOptions, VariantsControls, } from "./variants.js";
+export { createPathDraw } from "./pathdraw.js";
+export type { PathDrawOptions, PathDrawControls } from "./pathdraw.js";
+export { createPress, createHover } from "./press.js";
+export type { PressOptions, PressControls, HoverOptions, HoverControls, } from "./press.js";

package/dist/index.js

@@ -42,3 +42,9 @@ export { createBattery, createNetwork, createWakeLock, createContactPick, create
 export { createOptimistic } from "./optimistic.js";
 export { createSkeleton } from "./skeleton.js";
 export { createScrollSpy } from "./scrollspy.js";
+export { createCopy } from "./copy.js";
+export { createCountdown } from "./countdown.js";
+export { createMarquee } from "./marquee.js";
+export { createVariants } from "./variants.js";
+export { createPathDraw } from "./pathdraw.js";
+export { createPress, createHover } from "./press.js";

package/dist/marquee.d.ts

@@ -0,0 +1,57 @@
+import { type Accessor } from "solid-js";
+/** Marquee scroll direction. Default "left". */
+export type MarqueeDirection = "left" | "right" | "up" | "down";
+export interface MarqueeOptions {
+    /** Pixels per second. Default 60. */
+    speed?: number;
+    /** Scroll direction. Default "left". */
+    direction?: MarqueeDirection;
+    /** Start scrolling immediately. Default true. */
+    autoStart?: boolean;
+}
+export interface MarqueeControls {
+    /**
+     * Current offset in px. Wraps at the content size, so rendering two
+     * copies of the content side by side and translating by `-offset()`
+     * (or `-offset()` on Y for vertical) loops seamlessly.
+     */
+    offset: Accessor<number>;
+    /** Whether the marquee clock task is running. */
+    running: Accessor<boolean>;
+    /**
+     * Width (horizontal directions) or height (vertical directions) of one
+     * loop unit in px. Measure the content and call this once it is known.
+     */
+    setContentSize: (px: number) => void;
+    start: () => void;
+    stop: () => void;
+}
+/**
+ * Infinite marquee scroller. The offset advances at `speed` px/s on the
+ * shared clock and wraps at the content size, so a doubled content strip
+ * loops seamlessly.
+ *
+ * Reduced-motion aware: marquees are pure motion, so under reduced motion
+ * the marquee stays static (offset 0, never runs). SSR-safe.
+ *
+ * ```tsx
+ * const marquee = createMarquee({ speed: 80 });
+ * let strip!: HTMLDivElement;
+ * createEffect(() => {
+ *   marquee.setContentSize(strip.scrollWidth / 2);
+ * });
+ * <div style={{ overflow: "hidden" }}>
+ *   <div
+ *     ref={strip}
+ *     style={{
+ *       display: "flex",
+ *       transform: `translateX(${-marquee.offset()}px)`,
+ *       "will-change": "transform",
+ *     }}
+ *   >
+ *     {items}{items}
+ *   </div>
+ * </div>
+ * ```
+ */
+export declare function createMarquee(options?: MarqueeOptions): MarqueeControls;

package/dist/marquee.js

@@ -0,0 +1,88 @@
+import { createSignal, onCleanup, untrack } from "solid-js";
+import { now, schedule } from "./engine.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+/**
+ * Infinite marquee scroller. The offset advances at `speed` px/s on the
+ * shared clock and wraps at the content size, so a doubled content strip
+ * loops seamlessly.
+ *
+ * Reduced-motion aware: marquees are pure motion, so under reduced motion
+ * the marquee stays static (offset 0, never runs). SSR-safe.
+ *
+ * ```tsx
+ * const marquee = createMarquee({ speed: 80 });
+ * let strip!: HTMLDivElement;
+ * createEffect(() => {
+ *   marquee.setContentSize(strip.scrollWidth / 2);
+ * });
+ * <div style={{ overflow: "hidden" }}>
+ *   <div
+ *     ref={strip}
+ *     style={{
+ *       display: "flex",
+ *       transform: `translateX(${-marquee.offset()}px)`,
+ *       "will-change": "transform",
+ *     }}
+ *   >
+ *     {items}{items}
+ *   </div>
+ * </div>
+ * ```
+ */
+export function createMarquee(options = {}) {
+    const { speed = 60, direction = "left", autoStart = true } = options;
+    if (typeof window === "undefined") {
+        const zero = () => 0;
+        const falsy = () => false;
+        const noop = () => { };
+        return {
+            offset: zero,
+            running: falsy,
+            setContentSize: noop,
+            start: noop,
+            stop: noop,
+        };
+    }
+    const sign = direction === "left" || direction === "up" ? 1 : -1;
+    const [offset, setOffset] = createSignal(0);
+    const [running, setRunning] = createSignal(false);
+    let size = 0;
+    let phase = 0;
+    let last = 0;
+    let stopClock = null;
+    const task = (t) => {
+        const dt = Math.min(Math.max((t - last) / 1000, 0), 0.25);
+        last = t;
+        phase += speed * dt;
+        if (size > 0) {
+            setOffset((((phase * sign) % size) + size) % size);
+        }
+        return true;
+    };
+    const start = () => {
+        if (untrack(running) || prefersReducedMotion())
+            return;
+        setRunning(true);
+        last = now();
+        stopClock = schedule(task);
+    };
+    const stop = () => {
+        stopClock?.();
+        stopClock = null;
+        setRunning(false);
+    };
+    onCleanup(stop);
+    if (autoStart)
+        start();
+    return {
+        offset,
+        running,
+        setContentSize: (px) => {
+            size = Math.max(px, 0);
+            phase = 0;
+            setOffset(0);
+        },
+        start,
+        stop,
+    };
+}

package/dist/pathdraw.d.ts

@@ -0,0 +1,49 @@
+import { type Accessor } from "solid-js";
+import { type Easing } from "./easing.js";
+export interface PathDrawOptions {
+    /** Draw duration in ms. Default 1200. */
+    duration?: number;
+    /** Easing for the draw progress. Default easeInOutCubic. */
+    easing?: Easing;
+    /** Start drawing immediately. Default true. */
+    autoStart?: boolean;
+    /** Fires once when the draw completes. */
+    onDone?: () => void;
+}
+export interface PathDrawControls {
+    /** Eased draw progress, 0 to 1. */
+    progress: Accessor<number>;
+    /** Whether the draw clock task is running. */
+    running: Accessor<boolean>;
+    start: () => void;
+    stop: () => void;
+    /** Back to undrawn (progress 0). */
+    reset: () => void;
+}
+/**
+ * SVG path drawing animation. Drives `stroke-dashoffset` from the full
+ * path length to 0 so the stroke draws itself on, eased on the shared
+ * clock. The length is read with `getTotalLength()`, so any path shape
+ * works with no manual measuring.
+ *
+ * Under reduced motion (and on the server) the path renders fully drawn.
+ * SSR-safe.
+ *
+ * ```tsx
+ * let path!: SVGPathElement;
+ * const draw = createPathDraw(() => path, {
+ *   duration: 1600,
+ *   onDone: () => console.log("drawn"),
+ * });
+ * <svg viewBox="0 0 100 100">
+ *   <path
+ *     ref={path}
+ *     d="M10 80 C 40 10, 60 10, 90 80"
+ *     fill="none"
+ *     stroke="currentColor"
+ *     stroke-width="3"
+ *   />
+ * </svg>
+ * ```
+ */
+export declare function createPathDraw(ref: () => SVGPathElement | null | undefined, options?: PathDrawOptions): PathDrawControls;

package/dist/pathdraw.js

@@ -0,0 +1,106 @@
+import { createSignal, onCleanup } from "solid-js";
+import { now, schedule } from "./engine.js";
+import { easeInOutCubic } from "./easing.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+/**
+ * SVG path drawing animation. Drives `stroke-dashoffset` from the full
+ * path length to 0 so the stroke draws itself on, eased on the shared
+ * clock. The length is read with `getTotalLength()`, so any path shape
+ * works with no manual measuring.
+ *
+ * Under reduced motion (and on the server) the path renders fully drawn.
+ * SSR-safe.
+ *
+ * ```tsx
+ * let path!: SVGPathElement;
+ * const draw = createPathDraw(() => path, {
+ *   duration: 1600,
+ *   onDone: () => console.log("drawn"),
+ * });
+ * <svg viewBox="0 0 100 100">
+ *   <path
+ *     ref={path}
+ *     d="M10 80 C 40 10, 60 10, 90 80"
+ *     fill="none"
+ *     stroke="currentColor"
+ *     stroke-width="3"
+ *   />
+ * </svg>
+ * ```
+ */
+export function createPathDraw(ref, options = {}) {
+    const { duration = 1200, easing = easeInOutCubic, autoStart = true, onDone, } = options;
+    const [progress, setProgress] = createSignal(0);
+    const [running, setRunning] = createSignal(false);
+    if (typeof window === "undefined") {
+        const noop = () => { };
+        return { progress, running, start: noop, stop: noop, reset: noop };
+    }
+    let stopClock = null;
+    let doneFired = false;
+    const paint = (p) => {
+        const el = ref();
+        if (!el || typeof el.getTotalLength !== "function")
+            return;
+        const len = el.getTotalLength();
+        el.style.strokeDasharray = `${len}`;
+        el.style.strokeDashoffset = `${len * (1 - p)}`;
+    };
+    const finish = () => {
+        setProgress(1);
+        paint(1);
+        setRunning(false);
+        stopClock = null;
+        if (!doneFired) {
+            doneFired = true;
+            onDone?.();
+        }
+    };
+    const start = () => {
+        if (running())
+            return;
+        if (duration <= 0 || prefersReducedMotion()) {
+            setProgress(1);
+            finish();
+            return;
+        }
+        doneFired = false;
+        setRunning(true);
+        const from = progress();
+        if (from >= 1) {
+            finish();
+            return;
+        }
+        // Remaining time is proportional, so resume keeps a constant speed.
+        const span = Math.max(duration * (1 - from), 1);
+        const t0 = now();
+        paint(from);
+        stopClock?.();
+        stopClock = schedule((t) => {
+            const p = Math.min(Math.max((t - t0) / span, 0), 1);
+            const eased = from + (1 - from) * easing(p);
+            setProgress(eased);
+            paint(eased);
+            if (p >= 1) {
+                finish();
+                return false;
+            }
+            return true;
+        });
+    };
+    const stop = () => {
+        stopClock?.();
+        stopClock = null;
+        setRunning(false);
+    };
+    const reset = () => {
+        stop();
+        doneFired = false;
+        setProgress(0);
+        paint(0);
+    };
+    onCleanup(stop);
+    if (autoStart)
+        start();
+    return { progress, running, start, stop, reset };
+}

package/dist/press.d.ts

@@ -0,0 +1,57 @@
+import { type Accessor } from "solid-js";
+type MaybeElement = () => Element | null | undefined;
+export interface PressOptions {
+    /** Fires whenever the pressed state changes. */
+    onChange?: (pressed: boolean) => void;
+}
+export interface PressControls {
+    /** True while the pointer (or keyboard) is pressing the element. */
+    pressed: Accessor<boolean>;
+}
+export interface HoverOptions {
+    /** Fires whenever the hovering state changes. */
+    onChange?: (hovering: boolean) => void;
+}
+export interface HoverControls {
+    /** True while the pointer is over the element (or it has focus). */
+    hovering: Accessor<boolean>;
+}
+/**
+ * Press gesture state. Tracks pointer down/up on the element (mouse,
+ * touch, and pen via pointer events) plus Enter/Space key presses for
+ * keyboard parity. There is no animation here: the host decides how to
+ * respond, typically by driving `createVariants`.
+ *
+ * SSR-safe: always unpressed on the server.
+ *
+ * ```tsx
+ * let btn!: HTMLButtonElement;
+ * const press = createPress(() => btn);
+ * <button
+ *   ref={btn}
+ *   style={{
+ *     transform: press.pressed() ? "scale(0.96)" : "scale(1)",
+ *     transition: "transform 120ms",
+ *   }}
+ * >
+ *   Hold me
+ * </button>
+ * ```
+ */
+export declare function createPress(ref: MaybeElement, options?: PressOptions): PressControls;
+/**
+ * Hover gesture state. Tracks pointer enter/leave plus focus/blur so
+ * keyboard users get the same state. Like `createPress` this is state
+ * only: pair it with `createVariants` (or plain styles) to animate.
+ *
+ * SSR-safe: never hovering on the server.
+ *
+ * ```tsx
+ * let card!: HTMLDivElement;
+ * const hover = createHover(() => card, {
+ *   onChange: (h) => variants.go(h ? "hover" : "idle"),
+ * });
+ * ```
+ */
+export declare function createHover(ref: MaybeElement, options?: HoverOptions): HoverControls;
+export {};

package/dist/press.js

@@ -0,0 +1,116 @@
+import { createEffect, createSignal, onCleanup } from "solid-js";
+const falsy = () => false;
+/**
+ * Press gesture state. Tracks pointer down/up on the element (mouse,
+ * touch, and pen via pointer events) plus Enter/Space key presses for
+ * keyboard parity. There is no animation here: the host decides how to
+ * respond, typically by driving `createVariants`.
+ *
+ * SSR-safe: always unpressed on the server.
+ *
+ * ```tsx
+ * let btn!: HTMLButtonElement;
+ * const press = createPress(() => btn);
+ * <button
+ *   ref={btn}
+ *   style={{
+ *     transform: press.pressed() ? "scale(0.96)" : "scale(1)",
+ *     transition: "transform 120ms",
+ *   }}
+ * >
+ *   Hold me
+ * </button>
+ * ```
+ */
+export function createPress(ref, options = {}) {
+    const { onChange } = options;
+    if (typeof window === "undefined")
+        return { pressed: falsy };
+    const [pressed, setPressed] = createSignal(false);
+    const set = (value) => {
+        setPressed((prev) => {
+            if (prev !== value)
+                onChange?.(value);
+            return value;
+        });
+    };
+    createEffect(() => {
+        const el = ref();
+        if (!el)
+            return;
+        const down = () => set(true);
+        const up = () => set(false);
+        const onKeyDown = (event) => {
+            if (event.key === "Enter" || event.key === " ") {
+                if (!event.repeat)
+                    set(true);
+                if (event.key === " ")
+                    event.preventDefault?.();
+            }
+        };
+        const onKeyUp = (event) => {
+            if (event.key === "Enter" || event.key === " ")
+                set(false);
+        };
+        el.addEventListener("pointerdown", down);
+        el.addEventListener("pointerup", up);
+        el.addEventListener("pointercancel", up);
+        el.addEventListener("pointerleave", up);
+        el.addEventListener("keydown", onKeyDown);
+        el.addEventListener("keyup", onKeyUp);
+        onCleanup(() => {
+            el.removeEventListener("pointerdown", down);
+            el.removeEventListener("pointerup", up);
+            el.removeEventListener("pointercancel", up);
+            el.removeEventListener("pointerleave", up);
+            el.removeEventListener("keydown", onKeyDown);
+            el.removeEventListener("keyup", onKeyUp);
+        });
+    });
+    return { pressed };
+}
+/**
+ * Hover gesture state. Tracks pointer enter/leave plus focus/blur so
+ * keyboard users get the same state. Like `createPress` this is state
+ * only: pair it with `createVariants` (or plain styles) to animate.
+ *
+ * SSR-safe: never hovering on the server.
+ *
+ * ```tsx
+ * let card!: HTMLDivElement;
+ * const hover = createHover(() => card, {
+ *   onChange: (h) => variants.go(h ? "hover" : "idle"),
+ * });
+ * ```
+ */
+export function createHover(ref, options = {}) {
+    const { onChange } = options;
+    if (typeof window === "undefined")
+        return { hovering: falsy };
+    const [hovering, setHovering] = createSignal(false);
+    const set = (value) => {
+        setHovering((prev) => {
+            if (prev !== value)
+                onChange?.(value);
+            return value;
+        });
+    };
+    createEffect(() => {
+        const el = ref();
+        if (!el)
+            return;
+        const enter = () => set(true);
+        const leave = () => set(false);
+        el.addEventListener("pointerenter", enter);
+        el.addEventListener("pointerleave", leave);
+        el.addEventListener("focus", enter);
+        el.addEventListener("blur", leave);
+        onCleanup(() => {
+            el.removeEventListener("pointerenter", enter);
+            el.removeEventListener("pointerleave", leave);
+            el.removeEventListener("focus", enter);
+            el.removeEventListener("blur", leave);
+        });
+    });
+    return { hovering };
+}

package/dist/variants.d.ts

@@ -0,0 +1,63 @@
+import { type Accessor } from "solid-js";
+import { type Easing } from "./easing.js";
+/**
+ * One named animation state: CSS-ish property values. Numeric values
+ * interpolate; anything else snaps to the target when the transition
+ * finishes.
+ */
+export interface VariantDef {
+    [prop: string]: number | string;
+}
+export interface VariantsOptions {
+    /** Variant applied immediately on creation. */
+    initial?: string;
+    /** Transition length in ms. Default 250. */
+    duration?: number;
+    /** Easing for numeric interpolation. Default easeOutCubic. */
+    easing?: Easing;
+}
+export interface VariantsControls {
+    /** Name of the last variant passed to `go`. */
+    current: Accessor<string | undefined>;
+    /**
+     * Current interpolated values. Bind these straight into styles:
+     * `style={{ transform: `scale(${v.values().scale})` }}`.
+     */
+    values: Accessor<Record<string, number | string>>;
+    /** Transition to the named variant. Unknown names are ignored. */
+    go: (name: string) => void;
+}
+/**
+ * Named animation states with tweened transitions, in the vocabulary of
+ * "variants". `go(name)` interpolates every numeric property from the
+ * current values to the target variant on the shared clock; non-numeric
+ * properties (colors, keywords) snap at the end of the transition.
+ *
+ * Pairs with `createHover` / `createPress`: map gesture states to variant
+ * names and the element animates between them.
+ *
+ * Under reduced motion (and on the server) transitions snap instantly.
+ * SSR-safe.
+ *
+ * ```tsx
+ * const card = createVariants(
+ *   {
+ *     idle: { scale: 1, shadow: 0 },
+ *     hover: { scale: 1.04, shadow: 12 },
+ *     press: { scale: 0.96, shadow: 4 },
+ *   },
+ *   { initial: "idle", duration: 180 },
+ * );
+ * createHover(() => el, {
+ *   onChange: (h) => card.go(h ? "hover" : "idle"),
+ * });
+ * <div
+ *   ref={el}
+ *   style={{
+ *     transform: `scale(${card.values().scale})`,
+ *     "box-shadow": `0 ${card.values().shadow}px 24px rgb(0 0 0 / 0.12)`,
+ *   }}
+ * />
+ * ```
+ */
+export declare function createVariants(variants: Record<string, VariantDef>, options?: VariantsOptions): VariantsControls;

package/dist/variants.js

@@ -0,0 +1,86 @@
+import { createSignal, onCleanup, untrack } from "solid-js";
+import { now, schedule } from "./engine.js";
+import { easeOutCubic } from "./easing.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+/**
+ * Named animation states with tweened transitions, in the vocabulary of
+ * "variants". `go(name)` interpolates every numeric property from the
+ * current values to the target variant on the shared clock; non-numeric
+ * properties (colors, keywords) snap at the end of the transition.
+ *
+ * Pairs with `createHover` / `createPress`: map gesture states to variant
+ * names and the element animates between them.
+ *
+ * Under reduced motion (and on the server) transitions snap instantly.
+ * SSR-safe.
+ *
+ * ```tsx
+ * const card = createVariants(
+ *   {
+ *     idle: { scale: 1, shadow: 0 },
+ *     hover: { scale: 1.04, shadow: 12 },
+ *     press: { scale: 0.96, shadow: 4 },
+ *   },
+ *   { initial: "idle", duration: 180 },
+ * );
+ * createHover(() => el, {
+ *   onChange: (h) => card.go(h ? "hover" : "idle"),
+ * });
+ * <div
+ *   ref={el}
+ *   style={{
+ *     transform: `scale(${card.values().scale})`,
+ *     "box-shadow": `0 ${card.values().shadow}px 24px rgb(0 0 0 / 0.12)`,
+ *   }}
+ * />
+ * ```
+ */
+export function createVariants(variants, options = {}) {
+    const { initial, duration = 250, easing = easeOutCubic } = options;
+    const first = initial ?? Object.keys(variants)[0];
+    const [current, setCurrent] = createSignal(first);
+    const [values, setValues] = createSignal({
+        ...(first ? variants[first] : {}),
+    });
+    if (typeof window === "undefined") {
+        return { current, values, go: () => { } };
+    }
+    let stopClock = null;
+    const go = (name) => {
+        const target = variants[name];
+        if (!target)
+            return;
+        setCurrent(name);
+        stopClock?.();
+        stopClock = null;
+        const from = untrack(values);
+        if (duration <= 0 || prefersReducedMotion()) {
+            setValues({ ...target });
+            return;
+        }
+        const start = now();
+        const numeric = Object.keys(target).filter((k) => typeof target[k] === "number" && typeof from[k] === "number");
+        stopClock = schedule((t) => {
+            const p = Math.min(Math.max((t - start) / duration, 0), 1);
+            const e = easing(p);
+            const next = { ...untrack(values) };
+            for (const k of numeric) {
+                const a = from[k];
+                const b = target[k];
+                next[k] = a + (b - a) * e;
+            }
+            if (p >= 1) {
+                // Snap non-numeric props (and exact numeric targets) at the end.
+                for (const k of Object.keys(target))
+                    next[k] = target[k];
+                setValues(next);
+                stopClock = null;
+                return false;
+            }
+            setValues(next);
+            return true;
+        });
+    };
+    onCleanup(() => stopClock?.());
+    return { current, values, go };
+}

package/package.json

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