solidjs-motion 0.1.0

package/dist/src/primitives/gesture-state.d.ts

@@ -0,0 +1,108 @@
+import { MotionValue } from 'motion';
+import { Accessor } from 'solid-js';
+import { SetStoreFunction, Store } from 'solid-js/store';
+import { MotionConfigContextValue, MotionElement, MotionOptions, Target, VariantContextValue } from '../types';
+/** State names, ordered low → high priority. Matches motion-dom's variantPriorityOrder. */
+declare const STATE_NAMES: readonly ["animate", "whileInView", "whileHover", "whilePress", "whileFocus", "whileDrag", "exit"];
+export type GestureStateName = (typeof STATE_NAMES)[number];
+export type SetActive = (state: GestureStateName, isActive: boolean) => void;
+/** The reactive store of active gesture flags, lifted to the caller for sharing. */
+export type ActiveStore = Store<Record<GestureStateName, boolean>>;
+export type SetActiveStore = SetStoreFunction<Record<GestureStateName, boolean>>;
+export type ActiveStoreTuple = [ActiveStore, SetActiveStore];
+export type CreateGestureStateMachineDeps = {
+    el: MotionElement;
+    getOpts: () => MotionOptions;
+    parentVariantCtx: VariantContextValue;
+    motionConfig: MotionConfigContextValue;
+    systemReducedMotion: Accessor<boolean>;
+    /** Captured at construction. Used as the first stop in the removed-key fallback chain (Q7). */
+    initialTarget: Target | null;
+    /**
+     * Optional external active store (Q4 — useMotion lifts this up so its
+     * `myVariantCtx` can read the same flags it propagates to descendants).
+     * When omitted, the state machine creates its own internal store —
+     * backward-compatible for `createMotion` direct users.
+     */
+    externalActiveStore?: ActiveStoreTuple;
+    /**
+     * Phase 3 — when an enclosing `<Presence initial={false}>` is active, this
+     * is passed through to suppress the first-mount animate (mirrors the
+     * existing `initial: false` user-opt-out, but driven from above by
+     * Presence instead of by the user's own options).
+     */
+    suppressFirstMount?: boolean;
+    /**
+     * Phase 3 — readiness gate for the first-mount animate when this motion
+     * element is wrapped in a real `<Presence>`. The state machine reads this
+     * on each iteration; when it's `false` AND we haven't run yet, the diff
+     * effect short-circuits (no animate dispatch, no MV subscriptions sealed).
+     * Presence flips it to `true` from its `onEnter` / `onChange.added`
+     * callback, at which point the effect re-runs and treats THAT iteration
+     * as the first.
+     *
+     * Outside a Presence (no-op default context), createMotion leaves this
+     * `undefined` — the state machine treats absence as `ready=true` and the
+     * existing eager-first-iteration behavior is unchanged.
+     *
+     * Rationale: real `motion.animate()` is a Web Animations API call that
+     * runs even on a disconnected element, but its terminal `commitStyles`
+     * silently no-ops when the element is off-DOM. For a `mode: "wait"` swap
+     * the new child is created BEFORE the old child's exit completes, so
+     * dispatching the first animate eagerly would let it complete in the
+     * detached state and the element would paint at its `initial` target
+     * when it finally enters the DOM. Deferring until `onEnter` (when
+     * transition-group has synchronously inserted the element via
+     * `setReturned`) closes that gap.
+     */
+    enterReady?: Accessor<boolean>;
+    /**
+     * MV-in-style Stage 3 bridge. When provided, the diff effect calls this
+     * per animate-target key. A returned `MotionValue` routes the animation
+     * through that MV (`animate(mv, value, opts)`) — its change-subscription
+     * (in createMotion) composes `el.style` from the registry. `undefined`
+     * routes the key down the existing `animate(el, target, opts)` WAA path.
+     *
+     * createMotion only activates this when at least one external MV is
+     * registered (i.e., the user supplied `style: { scale: mv }`-shaped
+     * options). Inactive in the common case → 293 baseline tests stay on
+     * the original code path, their animateSpy assertions unaffected.
+     */
+    getValueForAnimate?: (key: string, fallback: unknown) => MotionValue<unknown> | undefined;
+};
+export type GestureStateMachine = {
+    /** Imperatively toggle a gesture state. Triggers re-resolution + animate(). */
+    setActive: SetActive;
+    /**
+     * Resolves when the next animate dispatched while `exit` is the highest-
+     * priority active driver state completes. If no exit animation is in
+     * flight AND no exit target is defined, resolves immediately.
+     *
+     * Used by `createMotion`'s presence registration: the registered
+     * `runExit` callable does `setActive("exit", true)` then awaits this.
+     * When the exit animation settles, `<Presence>` (or the hook) gets a
+     * resolved Promise and proceeds with DOM removal.
+     *
+     * Multiple concurrent waiters are supported — they all resolve from the
+     * same animation's completion.
+     */
+    onceExitComplete: () => Promise<void>;
+};
+/**
+ * Construct the per-element gesture state machine.
+ *
+ * Wired primitives:
+ * - `createStore` for the seven active flags — Solid tracks per-path, so
+ *   toggling `whileHover` doesn't dirty memos reading `whilePress`.
+ * - `createMemo` for `stateTargets` — cached, re-runs only when opts/parent
+ *   context change.
+ * - `createMemo` for `winners` — same caching, re-runs when `active` flags or
+ *   `stateTargets` change.
+ * - `createEffect` for the diff-and-animate loop — fires on `winners` change;
+ *   compares against `lastApplied` to compute changed/removed keys.
+ * - `onCleanup` inside the effect for per-iteration MV subscriptions — scoped
+ *   to each effect run (fires on re-run AND owner disposal). Same iteration-
+ *   scoped cleanup pattern Phase 1 established.
+ */
+export declare function createGestureStateMachine(deps: CreateGestureStateMachineDeps): GestureStateMachine;
+export {};

package/dist/src/primitives/motion-value.d.ts

@@ -0,0 +1,111 @@
+import { MotionValue, transform as motionTransform, SpringOptions } from 'motion';
+import { Accessor } from 'solid-js';
+import { MotionValueAccessor } from '../types';
+type MotionValueEvent = "change" | "animationStart" | "animationComplete" | "animationCancel";
+/**
+ * Create a {@link MotionValueAccessor} bound to the current reactive scope.
+ *
+ * The returned value has two access patterns:
+ *
+ * - `mv()` — invoke as a Solid Accessor. Tracks in JSX, `createEffect`,
+ *   `createMemo`, etc.
+ * - `mv.get()` / `mv.set(v)` / `mv.jump(v)` / `mv.on(...)` — the full upstream
+ *   {@link MotionValue} surface. Matches motion/react idioms.
+ *
+ * The same value can be passed as a target in
+ * `useMotion({ animate: { x: mv } })` (motion engine sees `.getVelocity` via
+ * the Proxy and treats it as a motion value) or directly as the target of
+ * `animate(mv, 100)`.
+ *
+ * Auto-destroyed via `onCleanup` when the owner is disposed.
+ *
+ * @example
+ * const x = createMotionValue(0)
+ * x.set(100)
+ * animate(x, 200, { duration: 0.5 })
+ * <p>{x()}</p>           // reactive read in JSX
+ */
+export declare function createMotionValue<T>(initial: T): MotionValueAccessor<T>;
+/**
+ * Bridge a raw {@link MotionValue} (from motion's `motionValue()` factory or
+ * any other motion API that doesn't return our hybrid) to a Solid
+ * {@link Accessor}. Seeds with the current value and updates on every
+ * `change` event.
+ *
+ * **You usually don't need this.** Values returned by `createMotionValue`,
+ * `createTransform`, `createSpring`, `createTime`, `createVelocity`, and
+ * `createTemplate` are already callable — you can do `mv()` directly. Reach
+ * for `toSignal` only when you receive a raw MotionValue from an external API.
+ *
+ * @example
+ * import { motionValue } from "motion"
+ * const rawMv = motionValue(0)
+ * const xSignal = toSignal(rawMv)
+ */
+export declare function toSignal<T>(mv: MotionValue<T>): Accessor<T>;
+/**
+ * Subscribe to a {@link MotionValue} event with automatic cleanup. Convenience
+ * wrapper around `mv.on(event, cb)` for parity with motion/react's
+ * `useMotionValueEvent`. For per-change reactivity, prefer
+ * `createComputed(() => fn(mv()))` since hybrids are directly callable.
+ *
+ * @example
+ * const x = createMotionValue(0)
+ * createMotionValueEvent(x, "animationComplete", () => console.log("done"))
+ */
+export declare function createMotionValueEvent<T>(mv: MotionValue<T>, event: MotionValueEvent, callback: (latest: T) => void): void;
+type TransformOptions = NonNullable<Parameters<typeof motionTransform>[2]>;
+/**
+ * Create a {@link MotionValueAccessor} that maps an input through a range/
+ * output pair. Mirrors motion/react's `useTransform`. The input can be a
+ * MotionValue, our hybrid, or any Solid Accessor; the output composes with
+ * `animate()`, `useMotion`'s targets, and JSX reactivity.
+ *
+ * @example
+ * const { scrollY } = createScroll()
+ * const opacity = createTransform(scrollY, [0, 200], [1, 0])
+ * <div style={{ opacity: opacity() }}>...</div>
+ */
+export declare function createTransform<I extends number, O>(input: MotionValue<I> | Accessor<I>, inputRange: I[], outputRange: O[], options?: TransformOptions): MotionValueAccessor<O>;
+/**
+ * Spring-smoothed mirror of a numeric input. Returns a
+ * {@link MotionValueAccessor} that tracks the source with physics-based easing.
+ *
+ * @example
+ * const x = createMotionValue(0)
+ * const smoothX = createSpring(x, { stiffness: 100, damping: 20 })
+ */
+export declare function createSpring(source: MotionValue<number> | Accessor<number>, options?: SpringOptions): MotionValueAccessor<number>;
+/**
+ * {@link MotionValueAccessor} that advances every animation frame, holding
+ * the milliseconds elapsed since this primitive was called. Driver for
+ * time-based animations and {@link createTransform}-derived values.
+ *
+ * @example
+ * const t = createTime()
+ * const wobble = createTransform(t, [0, 1000, 2000], [0, 10, 0])
+ */
+export declare function createTime(): MotionValueAccessor<number>;
+/**
+ * {@link MotionValueAccessor} reporting the velocity of a source motion value.
+ * Updated whenever the source changes.
+ *
+ * @example
+ * const x = createMotionValue(0)
+ * const xVelocity = createVelocity(x)
+ */
+export declare function createVelocity(source: MotionValue<number>): MotionValueAccessor<number>;
+type TemplateInput = MotionValue<any> | Accessor<unknown> | string | number;
+/**
+ * Tagged template producing a {@link MotionValueAccessor}\<string\>.
+ * Interpolated {@link MotionValue}s, hybrids, and Solid Accessors recompute
+ * the output string on change; primitives and static strings are baked in.
+ *
+ * @example
+ * const x = createMotionValue(0)
+ * const y = createMotionValue(0)
+ * const transform = createTemplate`translate(${x}px, ${y}px) scale(1.1)`
+ * <div style={{ transform: transform() }} />
+ */
+export declare function createTemplate(strings: TemplateStringsArray, ...values: TemplateInput[]): MotionValueAccessor<string>;
+export {};

package/dist/src/primitives/value-registry.d.ts

@@ -0,0 +1,34 @@
+import { MotionValue } from 'motion';
+export type ValueRegistry = {
+    /** Returns the MV registered for `key`, or `undefined` if none. */
+    get(key: string): MotionValue<unknown> | undefined;
+    /** Has any MV been registered for `key`? */
+    has(key: string): boolean;
+    /**
+     * Number of entries currently registered. Used by `createMotion` to decide
+     * whether the per-element writer can take a specialized single-key path
+     * (size === 1) or needs the general-purpose `applyStaticStyle` walk.
+     */
+    readonly size: number;
+    /**
+     * Register a user-provided MV. The registry will NOT dispose it on
+     * teardown. If a transient MV exists for the key, it is replaced (the
+     * external MV becomes the new source of truth).
+     */
+    setExternal(key: string, mv: MotionValue<unknown>): void;
+    /**
+     * Get the MV for `key`, creating a transient one initialized to
+     * `fallback` if absent. Transient MVs are disposed on `dispose()`.
+     */
+    getOrCreateTransient(key: string, fallback: unknown): MotionValue<unknown>;
+    /** Iterate every (key, MV) pair currently registered. */
+    entries(): IterableIterator<[string, MotionValue<unknown>]>;
+    /**
+     * Drop registry-owned (transient) MVs. External MVs are untouched.
+     * Subscription cleanups are owned by whoever called `mv.on(...)`; they
+     * tie to the surrounding Solid owner via `onCleanup` in Stage 2+ so we
+     * don't unsubscribe imperatively here.
+     */
+    dispose(): void;
+};
+export declare function createValueRegistry(): ValueRegistry;

package/dist/src/reduced-motion.d.ts

@@ -0,0 +1,29 @@
+import { Accessor } from 'solid-js';
+/**
+ * A reactive `Accessor<boolean>` tracking the user's
+ * `prefers-reduced-motion: reduce` media query.
+ *
+ * Returns `false` server-side (no `window.matchMedia`). On the client, it seeds
+ * with the current match state and updates as the system preference toggles.
+ * The matchMedia listener is removed automatically on owner disposal via
+ * `from`'s teardown callback.
+ *
+ * @example
+ * const reduced = createReducedMotion()
+ * createEffect(() => {
+ *   if (reduced()) console.log("user prefers reduced motion")
+ * })
+ */
+export declare function createReducedMotion(): Accessor<boolean>;
+/**
+ * Compute the effective reduced-motion state by combining a {@link MotionConfig}
+ * `reducedMotion` setting with the system preference.
+ *
+ * - `"always"` — forced reduced, regardless of system pref
+ * - `"never"` — never reduced, regardless of system pref
+ * - `"user"` — respect system pref
+ *
+ * @example
+ * const reduced = shouldReduceMotion("user", createReducedMotion()())
+ */
+export declare function shouldReduceMotion(configValue: "always" | "never" | "user", systemReduced: boolean): boolean;

package/dist/src/style.d.ts

@@ -0,0 +1,79 @@
+import { JSX } from 'solid-js';
+import { Target } from './types';
+/**
+ * Set of CSS shortcut keys motion treats as transform components. Re-used by
+ * `createMotion`'s Stage 3 animate bridge to decide whether an animate-target
+ * key should be routed through the value registry (composed via the writer's
+ * `el.style.transform =`) or sent down the existing WAA path.
+ */
+export declare const TRANSFORM_KEYS: Set<string>;
+type Leaf = string | number;
+/**
+ * Reduce a target-value (which may be raw, a MotionValue, an Accessor, or a
+ * keyframe array) to a concrete leaf value the writer can apply to the DOM
+ * or use to initialize a transient MotionValue. The cascade follows motion's
+ * own semantics:
+ *
+ * - `null` / `undefined` → `undefined` (caller drops the key)
+ * - keyframe array → first frame (consistent with motion-vanilla's
+ *   initial-style snapshot)
+ * - `MotionValue` → its current `.get()`
+ * - `Accessor` (a bare zero-arg function) → its invocation result
+ * - primitive (string / number) → returned as-is
+ *
+ * Exported for the MV-in-style Stage 4 work: createMotion uses it to
+ * snapshot initial-target entries when registering them into the value
+ * registry as transient MVs.
+ */
+export declare function snapshotValue(value: unknown): Leaf | undefined;
+/**
+ * Per-key transform formatter functions. Pre-built once at module load and
+ * shared across all elements. Used by `createMotion`'s specialized writer
+ * to avoid evaluating the transform-key switch on every single-key write —
+ * at Sierpinski-scale fan-out (thousands of writes per frame) the switch's
+ * 15 case-comparisons add up to non-trivial CPU.
+ *
+ * Pre-pick the formatter with `pickTransformFormatter(key)` ONCE at writer-
+ * compile time, then the per-call cost in the hot path is just `formatter(v)`.
+ */
+type TransformFormatter = (value: Leaf) => string;
+/**
+ * Look up the formatter for a transform-shortcut key. Returns `undefined`
+ * for non-transform keys; callers should check `TRANSFORM_KEYS.has(key)`
+ * before assuming a formatter exists.
+ */
+export declare function pickTransformFormatter(key: string): TransformFormatter | undefined;
+/**
+ * Format a motion transform-shortcut key + value as the corresponding CSS
+ * transform function string (e.g. `transformFunctionFor("scale", 1.05)`
+ * → `"scale(1.05)"`). One-shot variant — for hot paths, use
+ * `pickTransformFormatter(key)` once at compile time and reuse.
+ */
+export declare function transformFunctionFor(key: string, value: Leaf): string;
+/**
+ * Format a non-transform CSS property's value (e.g. `formatProperty("width", 100)`
+ * → `"100px"`, `formatProperty("opacity", 0.5)` → `0.5`). Applies motion's
+ * default-unit table (PX for dimensional CSS, dimensionless otherwise);
+ * leaves CSS variables alone. Exported for `createMotion`'s writer fast path.
+ */
+export declare function formatProperty(key: string, value: Leaf): string | number;
+/**
+ * Convert a {@link Target} to a Solid {@link JSX.CSSProperties} object.
+ *
+ * - Composes transform shorthand (`x`, `y`, `scale`, `rotate`, etc.) into a
+ *   single `transform: "..."` string in motion's canonical order.
+ * - Applies the default-unit table (px for dimensional CSS, deg for rotate/
+ *   skew, dimensionless for scale/opacity/etc.).
+ * - For keyframe arrays, uses the first frame; a leading `null`/`undefined`
+ *   keyframe omits the property entirely.
+ * - MotionValues and Solid Accessors are snapshotted at call time. Callers
+ *   wrap in `untrack` if they don't want the read to subscribe.
+ * - Skips the `transition` key (animation config, not style).
+ * - CSS variables (`--foo`) emit raw values, no unit guess.
+ *
+ * @example
+ * targetToStyle({ x: 100, scale: 0.9, opacity: 0.5 })
+ * // { transform: "translateX(100px) scale(0.9)", opacity: 0.5 }
+ */
+export declare function targetToStyle(target: Target): JSX.CSSProperties;
+export {};