solid-drift 0.2.0 → 0.8.0

package/dist/motion.d.ts

@@ -0,0 +1,404 @@
+/**
+ * Motion-graphics family: showreel and launch-film primitives.
+ *
+ * These are the building blocks of code-driven motion design: kinetic
+ * typography, scene orchestration, camera moves, time-based color
+ * shifts, match-cut transitions, and a beat clock for cutting on the
+ * music. Each primitive is small and composable; a showreel is a
+ * `createScenePlayer` driving a few of these together, not one mega-API.
+ *
+ * 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 ColorFormat, type ColorStop } from "./color.js";
+import { type Easing, type EasingName } from "./easing.js";
+type MaybeElement = () => Element | null | undefined;
+export interface KineticTypeFrom {
+    /** Vertical offset in px where each unit starts. Default 28. */
+    y?: number;
+    /** Blur in px where each unit starts. Default 10. */
+    blur?: number;
+    /** Scale where each unit starts. Default 0.85. */
+    scale?: number;
+    /** Opacity where each unit starts. Default 0. */
+    opacity?: number;
+    /** Rotation in degrees where each unit starts. Default 0. */
+    rotate?: number;
+    /**
+     * Per-unit jitter around the `from` values, 0 to 1. Default 0.
+     * At 0 every unit shares the exact `from` state; above 0 each unit
+     * gets a seeded random offset so the entrance feels hand-set
+     * instead of mechanical.
+     */
+    variance?: number;
+    /**
+     * Seed for the per-unit jitter. Same seed renders the same jitter
+     * on every run. Default 0.
+     */
+    seed?: number;
+}
+export interface KineticTypeOptions {
+    /** Split into "chars" or "words". Default "chars". */
+    unit?: "chars" | "words";
+    /** Milliseconds each unit takes to arrive. Default 550. */
+    duration?: number;
+    /** Milliseconds between unit starts. Default 45. */
+    stagger?: number;
+    /** Starting transform/opacity/blur for each unit. */
+    from?: KineticTypeFrom;
+    /** Easing for each unit's arrival. Default "easeOutExpo". */
+    easing?: Easing | EasingName;
+}
+export type KineticTypeStatus = "idle" | "running" | "done";
+export interface KineticTypeControls {
+    /** Play the reveal. Resolves when the last unit arrives. */
+    play: () => Promise<void>;
+    /** Stop mid-reveal. The play() promise resolves. */
+    stop: () => void;
+    /** Stop and play again from the first unit. */
+    replay: () => Promise<void>;
+    /** Reactive status: "idle" | "running" | "done". */
+    status: Accessor<KineticTypeStatus>;
+}
+/**
+ * Kinetic typography: each character (or word) flies in with position,
+ * blur, scale, and opacity, staggered for that showreel title feel.
+ *
+ * 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; 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.
+ *
+ * ```tsx
+ * let title!: HTMLHeadingElement
+ * const kinetic = createKineticType(() => title, {
+ *   unit: "chars",
+ *   stagger: 35,
+ *   from: { y: 40, blur: 12, scale: 0.8 },
+ *   easing: "easeOutExpo",
+ * })
+ * onMount(() => kinetic.play())
+ * <h1 ref={title}>Showreel</h1>
+ * ```
+ */
+export declare function createKineticType(ref: MaybeElement, options?: KineticTypeOptions): KineticTypeControls;
+/** One scene in a showreel: a duration plus enter/exit hooks. */
+export interface MotionScene {
+    /** How long the scene stays active, in milliseconds. */
+    duration: number;
+    /** Called when the scene becomes active. */
+    onEnter?: (index: number) => void;
+    /** Called when the scene ends. */
+    onExit?: (index: number) => void;
+}
+export type ScenePlayerStatus = "idle" | "running" | "paused" | "done";
+export interface ScenePlayerControls {
+    /** Current scene index, or -1 before the first play(). */
+    scene: Accessor<number>;
+    /** Reactive status: "idle" | "running" | "paused" | "done". */
+    status: Accessor<ScenePlayerStatus>;
+    /** Play from the current scene. Resolves after the last scene. */
+    play: () => Promise<void>;
+    /** Freeze the clock; play() resumes where it left off. */
+    pause: () => void;
+    /** Halt and reset to before the first scene. */
+    stop: () => void;
+    /** Stop and play again from the first scene. */
+    replay: () => Promise<void>;
+    /** Jump to the next scene now. */
+    next: () => void;
+    /** Jump to the previous scene now. */
+    prev: () => void;
+    /** Jump to a scene now. */
+    goTo: (index: number) => void;
+}
+/**
+ * Scene orchestrator for showreels and launch films: an ordered list of
+ * scenes, each with a duration and enter/exit hooks. Think of it as the
+ * paused-master-timeline pattern from motion-design tools, expressed as
+ * signals: `scene()` tells your view which scene is live, and the hooks
+ * trigger each scene's choreography (a `createKineticType`, a camera
+ * move, a color shift).
+ *
+ * SSR-safe: scenes never advance on the server. Under reduced motion
+ * `play()` jumps straight to the last scene (the clean final frame)
+ * instead of stepping through.
+ *
+ * ```ts
+ * const player = createScenePlayer([
+ *   { duration: 1200, onEnter: () => hookTitle.play() },
+ *   { duration: 2000, onEnter: () => cameraZoom.play() },
+ *   { duration: 1500, onEnter: () => showLogo() }, // final frame
+ * ])
+ * player.scene() // 0, 1, 2 as the reel plays
+ * await player.play()
+ * ```
+ */
+export declare function createScenePlayer(scenes: MotionScene[]): ScenePlayerControls;
+/** One camera keyframe: pan (x/y in px) and zoom (scale) at a progress. */
+export interface CameraKeyframe {
+    /** Progress position, 0 to 1. */
+    at: number;
+    /** Horizontal pan in px. Default 0. */
+    x?: number;
+    /** Vertical pan in px. Default 0. */
+    y?: number;
+    /** Zoom factor. Default 1. */
+    scale?: number;
+    /**
+     * Easing for the segment that ends at this keyframe, following the
+     * CSS keyframe convention. Default "linear".
+     */
+    easing?: Easing | EasingName;
+}
+export interface CameraOptions {
+    /** 0-to-1 progress signal driving the camera. */
+    progress: Accessor<number>;
+    /** Fallback easing for segments without their own. Default "linear". */
+    easing?: Easing | EasingName;
+}
+/**
+ * Camera moves for a motion-design stage: pan and zoom driven by a
+ * 0-to-1 progress signal, returned as a compositor-friendly transform
+ * string (`translate3d(...) scale(...)`).
+ *
+ * Drive `progress` with anything: a `createScenePlayer` scene's own
+ * clock, an `animate()` tween, or scroll. Keyframes sort themselves by
+ * `at`; progress outside the range clamps to the end poses.
+ *
+ * Pure computation, no listeners, no rAF: SSR-safe by construction.
+ * Under reduced motion it holds the final keyframe's pose.
+ *
+ * ```tsx
+ * const [p, setP] = createSignal(0)
+ * // Slow dolly-in across the scene.
+ * const cam = createCamera({
+ *   progress: p,
+ *   keyframes... // via options below
+ * })
+ * ```
+ */
+export declare function createCamera(keyframes: CameraKeyframe[], options: CameraOptions): Accessor<string>;
+export interface ColorShiftOptions {
+    /** Milliseconds to travel across all stops. Default 1200. */
+    duration?: number;
+    /** Delay before starting, in milliseconds. Default 0. */
+    delay?: number;
+    /** Fallback easing for stop segments without their own. Default "linear". */
+    easing?: Easing | EasingName;
+    /** Output format. Default "hex". */
+    format?: ColorFormat;
+}
+export type ColorShiftStatus = "idle" | "running" | "done";
+export interface ColorShiftControls {
+    /** The interpolated color as a string signal. */
+    color: Accessor<string>;
+    /** Play the shift. Resolves at the final stop. */
+    play: () => Promise<void>;
+    /** Stop mid-shift. The play() promise resolves. */
+    stop: () => void;
+    /** Stop and play again from the first stop. */
+    replay: () => Promise<void>;
+    /** Reactive status: "idle" | "running" | "done". */
+    status: Accessor<ColorShiftStatus>;
+}
+/**
+ * Time-based color interpolation across stops: the sibling of
+ * `createScrollColor` for motion graphics, where color shifts run on a
+ * clock instead of scroll. Colors interpolate in linear light, so
+ * midpoints stay vivid, and alpha channels interpolate too.
+ *
+ * Under reduced motion `play()` jumps straight to the final stop's
+ * color. SSR-safe: `color()` returns the final stop's color.
+ *
+ * ```ts
+ * const shift = createColorShift(
+ *   [
+ *     { at: 0, color: "#0a1220" },
+ *     { at: 0.5, color: "#2f8fdd" },
+ *     { at: 1, color: "#d9a441", easing: "easeInOutQuad" },
+ *   ],
+ *   { duration: 2000 },
+ * )
+ * shift.color() // "#0a1220" ... "#d9a441" as it plays
+ * await shift.play()
+ * ```
+ */
+export declare function createColorShift(stops: ColorStop[], options?: ColorShiftOptions): ColorShiftControls;
+/** How one scene hands off to the next. */
+export type TransitionType = "cut" | "fade" | "slide" | "wipe";
+/** Direction for "slide" and "wipe". */
+export type TransitionDirection = "left" | "right" | "up" | "down";
+export interface TransitionOptions {
+    /** Transition style. Default "fade". */
+    type?: TransitionType;
+    /** Direction for "slide" and "wipe". Default "left". */
+    direction?: TransitionDirection;
+    /** Duration in milliseconds. Default 500. */
+    duration?: number;
+    /** Easing. Default "easeInOutCubic". */
+    easing?: Easing | EasingName;
+}
+/** Compositor-friendly style for one side of a transition. */
+export interface TransitionLayerStyle {
+    opacity: string;
+    transform: string;
+    clipPath: string;
+}
+export type TransitionStatus = "idle" | "running" | "done";
+export interface TransitionControls {
+    /** 0-to-1 progress of the handoff. */
+    progress: Accessor<number>;
+    /** Style for the outgoing scene's layer. */
+    outgoing: Accessor<TransitionLayerStyle>;
+    /** Style for the incoming scene's layer. */
+    incoming: Accessor<TransitionLayerStyle>;
+    /** Play the handoff. Resolves when the incoming scene owns the frame. */
+    play: () => Promise<void>;
+    /** Stop mid-handoff. The play() promise resolves. */
+    stop: () => void;
+    /** Stop and play the handoff again. */
+    replay: () => Promise<void>;
+    /** Reactive status: "idle" | "running" | "done". */
+    status: Accessor<TransitionStatus>;
+}
+/**
+ * Match-cut style scene handoffs: `outgoing()` and `incoming()` return
+ * style objects for the two scene layers, driven by one 0-to-1 progress.
+ *
+ * - "cut": instant swap, no animation.
+ * - "fade": crossfade.
+ * - "slide": the outgoing scene exits one way while the incoming scene
+ *   enters from the opposite side.
+ * - "wipe": the incoming scene reveals over the outgoing one with a
+ *   clip-path wipe.
+ *
+ * Everything animates on opacity, transform, or clip-path, so handoffs
+ * stay on the compositor. Under reduced motion every type degrades to a
+ * cut: the swap happens instantly.
+ *
+ * ```tsx
+ * const cut = createTransition({ type: "wipe", direction: "left", duration: 600 })
+ * const go = async () => {
+ *   showSceneB()
+ *   await cut.play()
+ * }
+ * <div style={cut.outgoing()}>{sceneA}</div>
+ * <div style={cut.incoming()}>{sceneB}</div>
+ * ```
+ */
+export declare function createTransition(options?: TransitionOptions): TransitionControls;
+export interface BeatOptions {
+    /** Beats per minute. Default 120. */
+    bpm?: number;
+    /** Beats per bar. Default 4. */
+    beatsPerBar?: number;
+}
+export type BeatStatus = "idle" | "running";
+export interface BeatControls {
+    /** Whole beats elapsed since start(). */
+    beat: Accessor<number>;
+    /** Whole bars elapsed since start(). */
+    bar: Accessor<number>;
+    /** Fractional position within the current beat, 0 to 1. */
+    phase: Accessor<number>;
+    /** Beats per bar, from the options. Used as the default cut interval. */
+    beatsPerBar: number;
+    /**
+     * Register a callback fired on every beat with the beat index.
+     * Returns an unsubscribe function.
+     */
+    onBeat: (cb: (beat: number) => void) => () => void;
+    /** Start the clock. No-op if already running. */
+    start: () => void;
+    /** Stop the clock. */
+    stop: () => void;
+    /** Reactive status: "idle" | "running". */
+    status: Accessor<BeatStatus>;
+}
+/**
+ * A beat clock for cutting on the music: at 120 BPM it ticks twice a
+ * second, and `onBeat` fires your scene cuts, kinetic type replays, or
+ * color shifts in time. `phase()` gives the fractional position inside
+ * the current beat for syncing continuous motion to the rhythm.
+ *
+ * Beats are timing, not motion, so the clock keeps ticking under
+ * reduced motion (your callbacks decide what that means visually).
+ * SSR-safe: `start()` is a no-op without requestAnimationFrame.
+ *
+ * ```ts
+ * const beat = createBeat({ bpm: 128 })
+ * const off = beat.onBeat((b) => {
+ *   if (b % 8 === 0) player.next() // cut scenes every 2 bars
+ * })
+ * beat.start()
+ * ```
+ */
+export declare function createBeat(options?: BeatOptions): BeatControls;
+/** Named role of a showreel scene, for readability. */
+export type ShowreelSceneKind = "title" | "camera" | "color" | "cut" | "custom";
+/**
+ * One scene in a guided showreel: a `MotionScene` with an optional
+ * named kind describing what the scene does.
+ */
+export interface ShowreelScene extends MotionScene {
+    /**
+     * Named kind for readability: "title" for kinetic-type title cards,
+     * "camera" for camera-move scenes, "color" for color-shift scenes,
+     * "cut" for transition handoffs, "custom" for anything else.
+     * Informational only; it does not change playback.
+     */
+    kind?: ShowreelSceneKind;
+}
+/**
+ * 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 declare function createShowreel(scenes: ShowreelScene[]): ScenePlayerControls;
+export interface BeatCutOptions {
+    /**
+     * Cut every N beats. Default: the beat clock's `beatsPerBar`, so a
+     * cut lands on every downbeat.
+     */
+    every?: number;
+}
+/**
+ * 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 declare function createBeatCuts(beat: BeatControls, player: Pick<ScenePlayerControls, "next" | "status">, options?: BeatCutOptions): () => void;
+export {};