Better manage animation restarts. (2.0.2)

README.md

@@ -89,12 +89,15 @@ An `object` containing animation settings.
 
 - **`frames:`** `number | number[]` - Animation's frame configuration.
   - Set to an array of numbers to configure timeline of `step`s. Each item represents the amount of `step`s taken across the source image.
-  - Set to a number to move one step at a time for the specified amount of frames
+  - Set to a number to move one step at a time for the specified amount of frames.
+  - Restarts animation when updated.
+- **`initial?:`** `number` - Frame index to start animation at.
 - **`step:`** `number` - Number of pixels until next frame, relative to source image (usually same as view width/height).
 - **`orientation:`** `"horizontal" | "vertical"` - Direction the view portion moves in for each `step`.
 - **`fps:`** `number` - Amount of frames to cycle through per second (frames per second).
 - **`loop?:`** `boolean` - Whether animation should repeat.
 - **`destroy?:`** `boolean` - Whether component should remove itself when animation ends.
+- **`key?:`** `any` - Restarts animation when value is updated.
 - **`onStart?:`** `() => void` - Function to run on the first frame.
 - **`onEnd?:`** `() => void` - Function to run at the end of the last frame.
 - **`onChange?:`** `(frame: number) => void` - Function to run every frame change.
@@ -134,6 +137,6 @@ import { useFramage } from "react-framage";
 function Demo({ animation }) {
   const [frame, isDestroyed] = useFramage(animation);
 
-  return !isDestroyed ? <p>Current frame: {frame}</p> : <p>Animation go bye bye 😢</p>;
+  return <p>{!isDestroyed ? `Current frame index: ${frame}` : "Animation go bye bye 😢"}</p>;
 }
 ```

example/src/App.tsx

@@ -5,6 +5,8 @@ import { useState } from "react";
 
 function App() {
   const [frames, setFrames] = useState(Array.from({ length: 10 }, (_, i) => i));
+  const [key, setKey] = useState(0);
+  const [updater, setUpdater] = useState(0);
   return (
     <div className="App">
       <Framage
@@ -13,6 +15,7 @@ function App() {
         style={{ imageRendering: "pixelated" }}
         view={{ width: 9, height: 9 }}
         animation={{
+          key,
           fps: 1,
           frames: frames,
           loop: true,
@@ -27,6 +30,12 @@ function App() {
       <button type="button" onClick={() => setFrames((f) => [...f.reverse()])}>
         Reverse
       </button>
+      <button type="button" onClick={() => setKey((f) => f + 1)}>
+        Update Key
+      </button>
+      <button type="button" onClick={() => setUpdater((f) => f + 1)}>
+        Rerender {updater}
+      </button>
     </div>
   );
 }

package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-framage",
   "repository": "https://github.com/uspel/react-framage",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Move between portions of an image to create flipbook-like animations!",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

src/index.tsx

@@ -29,17 +29,32 @@ declare global {
 }
 
 interface FramageAnimation {
+  /** Animation's frame configuration.
+   * - Set to an array of numbers to configure timeline of steps. Each item represents the amount of `step`s taken across the source image.
+   * - Set to a number to move one `step` at a time for the specified amount of frames.
+   * - Restarts animation when updated. */
   frames: number | number[];
-  fps: number;
+  /** Frame index to start animation at. */
+  initial?: number;
+  /** Number of pixels until next frame, relative to source image (usually same as view width/height). */
   step: number;
+  /** Direction the view portion moves in for each `step`. */
   orientation: "horizontal" | "vertical";
-  initial?: number;
+  /** Amount of frames to cycle through per second (frames per second). */
+  fps: number;
+  /** Whether animation should repeat. */
   loop?: boolean;
+  /** Whether component should remove itself when animation ends. */
   destroy?: boolean;
+  /** Restarts animation when value is updated. */
+  key?: any;
   // Handlers
-  onChange?(frame: number): void;
+  /** Function to run on the first frame. */
   onStart?(): void;
+  /** Function to run at the end of the last frame. */
   onEnd?(): void;
+  /** Function to run every frame change. */
+  onChange?(frame: number): void;
 }
 
 type Framage = JSX.IntrinsicElements["img"] & {
@@ -57,7 +72,7 @@ type Framage = JSX.IntrinsicElements["img"] & {
   /**
     Framage animation configuration.
     
-    @version 2.0.0
+    @version 2.0.2
     @see https://npmjs.com/package/react-framage#framageanimation
    */
   animation?: FramageAnimation;
@@ -68,7 +83,7 @@ type Framage = JSX.IntrinsicElements["img"] & {
 
   Returns an array containing the current frame index and a boolean representing whether the Framage is destroyed.
   
-  @version 2.0.0
+  @version 2.0.2
   @see https://npmjs.com/package/react-framage#useframage
  */
 export function useFramage(animation?: FramageAnimation): [number, boolean] {
@@ -114,15 +129,15 @@ export function useFramage(animation?: FramageAnimation): [number, boolean] {
       };
     }
     return undefined;
-  }, [animation]);
+  }, [animation?.frames, animation?.key]);
 
   return [frame, isDestroyed];
 }
 
 /** 
  Move between portions of an image to create flipbook-like animations!
 
- @version 2.0.0
+ @version 2.0.2
  @see https://npmjs.com/package/react-framage#usage
  */
 export function Framage({ view, animation, ...imgAttributes }: Framage) {