react-gif-timeline 0.0.1

package/README.md

@@ -0,0 +1,180 @@
+# react-gif-timeline
+
+Control GIF animation timelines with React state. Define anchor frames mapped to states, and the library animates between them (forward or reverse), respecting the GIF's original frame timing.
+
+```
+State A → Frame 0 (paused)
+State A→B → Animate frame 0 → frame 20, pause
+State B→C → Animate frame 20 → frame 39, pause
+State C→A → Animate frame 39 → frame 0 (reverse), pause
+```
+
+Mid-transition interruptions are handled gracefully. If the state changes while animating, the new transition starts from the current frame.
+
+## Install
+
+```bash
+bun add react-gif-timeline
+```
+
+## Quick Start
+
+### Hook
+
+```tsx
+import { useGifTimeline } from "react-gif-timeline"
+
+function WeatherWidget() {
+  const [state, setState] = useState("sunny")
+
+  const { canvasRef, currentFrame, isTransitioning } = useGifTimeline({
+    src: "/weather.gif",
+    anchors: { sunny: 0, cloudy: 19, rainy: 39 },
+    activeState: state,
+  })
+
+  return (
+    <div>
+      <canvas ref={canvasRef} />
+      <p>Frame {currentFrame} {isTransitioning && "(transitioning...)"}</p>
+      <button onClick={() => setState("sunny")}>Sunny</button>
+      <button onClick={() => setState("cloudy")}>Cloudy</button>
+      <button onClick={() => setState("rainy")}>Rainy</button>
+    </div>
+  )
+}
+```
+
+### Component
+
+```tsx
+import { GifTimeline } from "react-gif-timeline"
+
+function WeatherWidget() {
+  const [state, setState] = useState("sunny")
+
+  return (
+    <GifTimeline
+      src="/weather.gif"
+      anchors={{ sunny: 0, cloudy: 19, rainy: 39 }}
+      activeState={state}
+      speed={1.5}
+      renderLoading={() => <div>Loading...</div>}
+      renderError={(err) => <div>Error: {err}</div>}
+    >
+      {({ currentFrame, totalFrames, transitionProgress }) => (
+        <p>Frame {currentFrame}/{totalFrames} ({Math.round(transitionProgress * 100)}%)</p>
+      )}
+    </GifTimeline>
+  )
+}
+```
+
+## Anchors
+
+Anchors map your application states to GIF frame indices (0-indexed). Two formats are supported:
+
+### Named anchors (recommended)
+
+```tsx
+const anchors = { idle: 0, loading: 15, done: 30 }
+
+useGifTimeline({
+  anchors,
+  activeState: "loading", // TypeScript autocompletes keys
+})
+```
+
+### Index-based anchors
+
+```tsx
+const anchors = [0, 15, 30]
+
+useGifTimeline({
+  anchors,
+  activeState: 1, // points to frame 15
+})
+```
+
+Named anchors provide full TypeScript inference. `activeState` is constrained to the keys you defined.
+
+## API
+
+### `useGifTimeline(options)`
+
+#### Options
+
+| Option | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `src` | `string \| Blob` | yes | - | GIF URL or Blob |
+| `anchors` | `number[] \| Record<string, number>` | yes | - | Frame indices mapped to states |
+| `activeState` | `number \| string` | yes | - | Active state (index for arrays, key for records) |
+| `speed` | `number` | no | `1` | Playback speed multiplier |
+| `onTransitionStart` | `(fromFrame, toFrame) => void` | no | - | Called when a transition begins |
+| `onTransitionEnd` | `(state) => void` | no | - | Called when a transition completes |
+
+#### Return
+
+| Field | Type | Description |
+|---|---|---|
+| `canvasRef` | `RefObject<HTMLCanvasElement>` | Attach to a `<canvas>` element |
+| `currentFrame` | `number` | Currently displayed frame index |
+| `totalFrames` | `number` | Total frames in the GIF |
+| `isLoaded` | `boolean` | GIF is loaded and parsed |
+| `error` | `string \| null` | Error message if loading failed |
+| `isTransitioning` | `boolean` | A transition is in progress |
+| `transitionProgress` | `number` | 0–1 progress of current transition |
+
+### `<GifTimeline>`
+
+Wraps `useGifTimeline` with built-in canvas rendering and loading/error states.
+
+Accepts all hook options as props, plus:
+
+| Prop | Type | Description |
+|---|---|---|
+| `className` | `string` | Applied to the canvas element |
+| `style` | `CSSProperties` | Applied to the canvas element |
+| `renderLoading` | `() => ReactNode` | Rendered while the GIF loads |
+| `renderError` | `(error: string) => ReactNode` | Rendered if loading fails |
+| `children` | `(result: GifTimelineResult) => ReactNode` | Render prop with hook return values |
+
+## How It Works
+
+1. **Parse**: the GIF is fetched and decoded using [gifuct-js](https://github.com/matt-way/gifuct-js)
+2. **Pre-compose**: each frame is composited into a full image (resolving GIF delta/patch encoding), enabling instant forward and reverse playback
+3. **Render**: frames are drawn to a canvas via `putImageData` with automatic DPR scaling for retina displays
+4. **Animate**: when `activeState` changes, a `requestAnimationFrame` loop plays through frames using the GIF's original per-frame delays, adjusted by the `speed` multiplier
+
+### Direction
+
+- Target frame > current frame → plays forward
+- Target frame < current frame → plays in reverse
+
+### Interruptions
+
+If `activeState` changes during a transition, the current animation is cancelled and a new one starts from whatever frame is currently displayed.
+
+## TypeScript
+
+The library is fully typed with generics that infer `activeState` from `anchors`:
+
+```tsx
+// anchors is Record<string, number> → activeState must be a key
+useGifTimeline({
+  anchors: { idle: 0, active: 20 },
+  activeState: "idle",    // ✅
+  activeState: "unknown", // ❌ Type error
+})
+
+// anchors is number[] → activeState must be number
+useGifTimeline({
+  anchors: [0, 20],
+  activeState: 0,       // ✅
+  activeState: "idle",  // ❌ Type error
+})
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CSSProperties, ReactNode, RefObject } from 'react';
+
+type Anchors = number[] | Record<string, number>;
+type ActiveState<A extends Anchors> = A extends number[] ? number : keyof A & string;
+interface GifTimelineOptions<A extends Anchors> {
+    src: string | Blob;
+    anchors: A;
+    activeState: ActiveState<A>;
+    speed?: number;
+    onTransitionStart?: (fromFrame: number, toFrame: number) => void;
+    onTransitionEnd?: (state: ActiveState<A>) => void;
+}
+interface GifTimelineResult {
+    canvasRef: RefObject<HTMLCanvasElement | null>;
+    currentFrame: number;
+    totalFrames: number;
+    isLoaded: boolean;
+    error: string | null;
+    isTransitioning: boolean;
+    transitionProgress: number;
+}
+interface GifTimelineProps<A extends Anchors> extends GifTimelineOptions<A> {
+    className?: string;
+    style?: CSSProperties;
+    renderLoading?: () => ReactNode;
+    renderError?: (error: string) => ReactNode;
+    children?: (result: GifTimelineResult) => ReactNode;
+}
+
+declare function GifTimeline<A extends Anchors>(props: GifTimelineProps<A>): react_jsx_runtime.JSX.Element;
+
+declare function useGifTimeline<A extends Anchors>(options: GifTimelineOptions<A>): GifTimelineResult;
+
+export { type ActiveState, type Anchors, GifTimeline, type GifTimelineOptions, type GifTimelineProps, type GifTimelineResult, useGifTimeline };

package/dist/index.js

@@ -0,0 +1,274 @@
+// src/useGifTimeline.ts
+import { useEffect, useRef, useState } from "react";
+
+// src/animator.ts
+function animate(fromFrame, toFrame, delays, speed, onFrame, onComplete) {
+  if (fromFrame === toFrame) {
+    onFrame(toFrame);
+    onComplete();
+    return { cancel: () => {
+    } };
+  }
+  const direction = toFrame > fromFrame ? 1 : -1;
+  let currentFrame = fromFrame;
+  let elapsed = 0;
+  let lastTime = 0;
+  let rafId = 0;
+  function tick(time) {
+    if (lastTime === 0) {
+      lastTime = time;
+    }
+    elapsed += time - lastTime;
+    lastTime = time;
+    while (currentFrame !== toFrame) {
+      const frameDelay = (delays[currentFrame] || 100) / speed;
+      if (elapsed < frameDelay) break;
+      elapsed -= frameDelay;
+      currentFrame += direction;
+      onFrame(currentFrame);
+      if (currentFrame === toFrame) {
+        onComplete();
+        return;
+      }
+    }
+    rafId = requestAnimationFrame(tick);
+  }
+  onFrame(currentFrame);
+  rafId = requestAnimationFrame(tick);
+  return {
+    cancel: () => cancelAnimationFrame(rafId)
+  };
+}
+
+// src/frameRenderer.ts
+function initCanvas(canvas, width, height) {
+  const dpr = window.devicePixelRatio || 1;
+  canvas.width = width * dpr;
+  canvas.height = height * dpr;
+  canvas.style.width = `${width}px`;
+  canvas.style.height = `${height}px`;
+  const ctx = canvas.getContext("2d");
+  ctx.scale(dpr, dpr);
+}
+function renderFrame(canvas, frame, width, height) {
+  const ctx = canvas.getContext("2d");
+  const temp = document.createElement("canvas");
+  temp.width = width;
+  temp.height = height;
+  const tempCtx = temp.getContext("2d");
+  tempCtx.putImageData(frame, 0, 0);
+  ctx.clearRect(0, 0, width, height);
+  ctx.drawImage(temp, 0, 0, width, height);
+}
+
+// src/gifParser.ts
+import { decompressFrames, parseGIF } from "gifuct-js";
+async function parseGifSource(src) {
+  const buffer = src instanceof Blob ? await src.arrayBuffer() : await fetch(src).then((r) => r.arrayBuffer());
+  const gif = parseGIF(buffer);
+  const rawFrames = decompressFrames(gif, true);
+  if (rawFrames.length === 0) {
+    throw new Error("react-gif-timeline: GIF contains no frames");
+  }
+  const { width, height } = rawFrames[0].dims;
+  const accumulator = document.createElement("canvas");
+  accumulator.width = width;
+  accumulator.height = height;
+  const accCtx = accumulator.getContext("2d");
+  const temp = document.createElement("canvas");
+  const tempCtx = temp.getContext("2d");
+  const frames = [];
+  const delays = [];
+  for (const frame of rawFrames) {
+    const { patch, dims, disposalType, delay } = frame;
+    if (patch) {
+      temp.width = dims.width;
+      temp.height = dims.height;
+      const patchData = new ImageData(patch, dims.width, dims.height);
+      tempCtx.putImageData(patchData, 0, 0);
+      accCtx.drawImage(temp, dims.left, dims.top);
+    }
+    frames.push(accCtx.getImageData(0, 0, width, height));
+    delays.push(delay);
+    if (disposalType === 2) {
+      accCtx.clearRect(dims.left, dims.top, dims.width, dims.height);
+    }
+    if (disposalType === 3) {
+      accCtx.clearRect(dims.left, dims.top, dims.width, dims.height);
+    }
+  }
+  return { frames, delays, width, height };
+}
+
+// src/useGifTimeline.ts
+function resolveAnchorFrame(anchors, activeState) {
+  if (Array.isArray(anchors)) {
+    return anchors[activeState];
+  }
+  return anchors[activeState];
+}
+function useGifTimeline(options) {
+  const { src, anchors, activeState, speed = 1, onTransitionStart, onTransitionEnd } = options;
+  const canvasRef = useRef(null);
+  const gifDataRef = useRef(null);
+  const currentFrameRef = useRef(0);
+  const animatorRef = useRef(null);
+  const [isLoaded, setIsLoaded] = useState(false);
+  const [error, setError] = useState(null);
+  const [currentFrame, setCurrentFrame] = useState(0);
+  const [isTransitioning, setIsTransitioning] = useState(false);
+  const [transitionProgress, setTransitionProgress] = useState(0);
+  const onTransitionStartRef = useRef(onTransitionStart);
+  onTransitionStartRef.current = onTransitionStart;
+  const onTransitionEndRef = useRef(onTransitionEnd);
+  onTransitionEndRef.current = onTransitionEnd;
+  const activeStateRef = useRef(activeState);
+  activeStateRef.current = activeState;
+  const anchorsRef = useRef(anchors);
+  anchorsRef.current = anchors;
+  useEffect(() => {
+    let cancelled = false;
+    setIsLoaded(false);
+    setError(null);
+    gifDataRef.current = null;
+    parseGifSource(src).then((data) => {
+      if (cancelled) return;
+      gifDataRef.current = data;
+      if (canvasRef.current) {
+        initCanvas(canvasRef.current, data.width, data.height);
+      }
+      const initialFrame = resolveAnchorFrame(anchorsRef.current, activeStateRef.current);
+      const clampedFrame = Math.min(Math.max(0, initialFrame), data.frames.length - 1);
+      currentFrameRef.current = clampedFrame;
+      setCurrentFrame(clampedFrame);
+      if (canvasRef.current) {
+        renderFrame(canvasRef.current, data.frames[clampedFrame], data.width, data.height);
+      }
+      setIsLoaded(true);
+    }).catch((err) => {
+      if (cancelled) return;
+      const message = err instanceof Error ? err.message : "Failed to load GIF";
+      setError(message);
+      console.error("react-gif-timeline:", message);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [src]);
+  const prevTargetRef = useRef(null);
+  useEffect(() => {
+    const data = gifDataRef.current;
+    if (!data || !isLoaded) return;
+    const targetFrame = resolveAnchorFrame(anchors, activeState);
+    if (targetFrame === void 0 || targetFrame < 0 || targetFrame >= data.frames.length) {
+      console.warn(
+        `react-gif-timeline: anchor frame ${targetFrame} is out of range (0-${data.frames.length - 1})`
+      );
+      return;
+    }
+    if (prevTargetRef.current === targetFrame) return;
+    prevTargetRef.current = targetFrame;
+    const fromFrame = currentFrameRef.current;
+    if (fromFrame === targetFrame) return;
+    if (animatorRef.current) {
+      animatorRef.current.cancel();
+    }
+    const totalSteps = Math.abs(targetFrame - fromFrame);
+    let stepsDone = 0;
+    setIsTransitioning(true);
+    setTransitionProgress(0);
+    onTransitionStartRef.current?.(fromFrame, targetFrame);
+    animatorRef.current = animate(
+      fromFrame,
+      targetFrame,
+      data.delays,
+      speed,
+      (frameIndex) => {
+        currentFrameRef.current = frameIndex;
+        if (canvasRef.current) {
+          renderFrame(canvasRef.current, data.frames[frameIndex], data.width, data.height);
+        }
+        if (frameIndex !== fromFrame) {
+          stepsDone++;
+          setTransitionProgress(totalSteps > 0 ? stepsDone / totalSteps : 1);
+        }
+      },
+      () => {
+        setCurrentFrame(targetFrame);
+        setIsTransitioning(false);
+        setTransitionProgress(1);
+        onTransitionEndRef.current?.(activeStateRef.current);
+      }
+    );
+    return () => {
+      if (animatorRef.current) {
+        animatorRef.current.cancel();
+        animatorRef.current = null;
+      }
+    };
+  }, [activeState, anchors, speed, isLoaded]);
+  useEffect(() => {
+    return () => {
+      if (animatorRef.current) {
+        animatorRef.current.cancel();
+      }
+    };
+  }, []);
+  return {
+    canvasRef,
+    currentFrame,
+    totalFrames: gifDataRef.current?.frames.length ?? 0,
+    isLoaded,
+    error,
+    isTransitioning,
+    transitionProgress
+  };
+}
+
+// src/GifTimeline.tsx
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+function GifTimeline(props) {
+  const {
+    src,
+    anchors,
+    activeState,
+    speed,
+    onTransitionStart,
+    onTransitionEnd,
+    className,
+    style,
+    renderLoading,
+    renderError,
+    children
+  } = props;
+  const result = useGifTimeline({
+    src,
+    anchors,
+    activeState,
+    speed,
+    onTransitionStart,
+    onTransitionEnd
+  });
+  if (result.error) {
+    return /* @__PURE__ */ jsx(Fragment, { children: renderError?.(result.error) });
+  }
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    !result.isLoaded && renderLoading?.(),
+    /* @__PURE__ */ jsx(
+      "canvas",
+      {
+        ref: result.canvasRef,
+        className,
+        style: {
+          ...style,
+          display: result.isLoaded ? void 0 : "none"
+        }
+      }
+    ),
+    result.isLoaded && children?.(result)
+  ] });
+}
+export {
+  GifTimeline,
+  useGifTimeline
+};

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "react-gif-timeline",
+  "version": "0.0.1",
+  "description": "Control GIF animation timelines with React state — map anchor frames to states and animate between them.",
+  "sideEffects": false,
+  "workspaces": ["demo"],
+  "license": "MIT",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "lint": "biome check .",
+    "prepublishOnly": "bun run build",
+    "release": "semantic-release"
+  },
+  "keywords": [
+    "react",
+    "gif",
+    "timeline",
+    "animation",
+    "state-machine",
+    "canvas",
+    "keyframe",
+    "anchor",
+    "gif-player",
+    "gif-controller"
+  ],
+  "author": {
+    "name": "Matt Silva",
+    "email": "tecoad@gmail.com",
+    "url": "https://github.com/tecoad"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tecoad/react-gif-timeline.git"
+  },
+  "homepage": "https://github.com/tecoad/react-gif-timeline#readme",
+  "bugs": {
+    "url": "https://github.com/tecoad/react-gif-timeline/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "gifuct-js": "^2.1.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.7",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.4",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "semantic-release": "^25.0.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  }
+}