refactor: cache keyframes and animationOptions on mount & deprecate shouldUpdateAnimation option & refine types

Author: wellyshen

README.md

@@ -34,7 +34,7 @@ Using [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_
 - 🔩 Supports custom `refs` for [some reasons](#use-your-own-ref).
 - 📜 Supports [TypeScript](https://www.typescriptlang.org) type definition.
 - 🗄️ Server-side rendering compatibility.
-- 🦔 Tiny size ([~ 4.8KB gzipped](https://bundlephobia.com/result?p=@wellyshen/use-web-animations)).
+- 🦔 Tiny size ([~ 3.8KB gzipped](https://bundlephobia.com/result?p=@wellyshen/use-web-animations)). No external dependencies, aside for the `react`.
 
 ## Requirement
 
@@ -129,7 +129,22 @@ const App = () => {
 };
 ```
 
-> 💡 By default, the hook will be updated when options changed (i.e. keyframes, animationOptions etc.). However, you can disable the behavior by setting the `shouldUpdateAnimation` option to `false`.
+### Setting/Updating Animation
+
+The `keyframes` and `animationOptions` are cached when the hook is mounted. However, we can set/update the animation by the `animation` method.
+
+```js
+const { animation } = useWebAnimations();
+
+const changeAnim = () =>
+  animation({
+    keyframes: { transform: ["translateX(0)", "translateX(100px)"] },
+    animationOptions: 1000,
+    id: "123",
+    playbackRate: 1,
+    autoPlay: true,
+  });
+```
 
 ### Playback Control
 
@@ -528,24 +543,24 @@ It's returned with the following properties.
 | `ref`          | object   |         | Used to set the target element for animating.                                                                                                                                                               |
 | `playState`    | string   |         | Describes the playback state of an animation.                                                                                                                                                               |
 | `getAnimation` | function |         | Access the [animation instance](https://developer.mozilla.org/en-US/docs/Web/API/Animation) for [playback control](#playback-control), [animation's information](#getting-animations-information) and more. |
-| `animate`      | function |         | Creates animation at the `animationOptions` you want. Useful for [interactive animations and composite animations](#dynamic-interactions-with-animation).                                                   |
+| `animate`      | function |         | Imperatively [set/update the animation](#settingupdating-animation). Useful for [interactive animations and composite animations](#dynamic-interactions-with-animation).                                    |
 
 ### Parameter
 
 The `options` provides the following configurations and event callbacks for you.
 
-| Key                     | Type             | Default | Description                                                                                                                                                                                                                                       |
-| ----------------------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ref`                   | object           |         | For [some reasons](#use-your-own-ref), you can pass in your own ref instead of using the built-in.                                                                                                                                                |
-| `id`                    | string           | `""`    | Sets the ID of an animation, implemented based on the [Animation.id](https://developer.mozilla.org/en-US/docs/Web/API/Animation/id).                                                                                                              |
-| `playbackRate`          | number           | `1`     | Sets the playback rate of an animation, implemented based on the [Animation.playbackRate](https://developer.mozilla.org/en-US/docs/Web/API/Animation/playbackRate).                                                                               |
-| `autoPlay`              | boolean          | `true`  | Automatically starts the animation.                                                                                                                                                                                                               |
-| `keyframes`             | Array \| object  |         | An array of keyframe objects, or a keyframe object whose property are arrays of values to iterate over. See [basic usage](#basic-usage) for more details.                                                                                         |
-| `animationOptions`      | number \| object |         | An **integer** representing the animation's duration (in milliseconds), or an **object** containing one or more timing properties. See [basic usage](#basic-usage) for more details.                                                              |
-| `shouldUpdateAnimation` | boolean          | `true`  | By default, the hook will be updated when options changed (i.e. keyframes, animationOptions etc.). However, you can disable the behavior by setting this option to `false`.                                                                      |
-| `onReady`               | function         |         | It's invoked when an animation is ready to play. You can access the [playState](#basic-usage), [animate](#dynamic-interactions-with-animation) and [animation](#getting-animations-information) from the event object.                            |
-| `onUpdate`              | function         |         | It's invoked when an animation enters the `running` state or changes state. You can access the [playState](#basic-usage), [animate](#dynamic-interactions-with-animation) and [animation](#getting-animations-information) from the event object. |
-| `onFinish`              | function         |         | It's invoked when an animation enters the `finished` state. You can access the [playState](#basic-usage), [animate](#dynamic-interactions-with-animation) and [animation](#getting-animations-information) from the event object.                 |
+| Key                | Type             | Default | Description                                                                                                                                                                          |
+| ------------------ | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ref`              | object           |         | For [some reasons](#use-your-own-ref), you can pass in your own ref instead of using the built-in.                                                                                   |
+| `id`               | string           | `""`    | Sets the ID of an animation, implemented based on the [Animation.id](https://developer.mozilla.org/en-US/docs/Web/API/Animation/id).                                                 |
+| `playbackRate`     | number           | `1`     | Sets the playback rate of an animation, implemented based on the [Animation.playbackRate](https://developer.mozilla.org/en-US/docs/Web/API/Animation/playbackRate).                  |
+| `autoPlay`         | boolean          | `true`  | Automatically starts the animation.                                                                                                                                                  |
+| `keyframes`        | Array \| object  |         | An array of keyframe objects, or a keyframe object whose property are arrays of values to iterate over. See [basic usage](#basic-usage) for more details.                            |
+| `animationOptions` | number \| object |         | An **integer** representing the animation's duration (in milliseconds), or an **object** containing one or more timing properties. See [basic usage](#basic-usage) for more details. |
+
+| `onReady` | function | | It's invoked when an animation is ready to play. You can access the [playState](#basic-usage), [animate](#dynamic-interactions-with-animation) and [animation](#getting-animations-information) from the event object. |
+| `onUpdate` | function | | It's invoked when an animation enters the `running` state or changes state. You can access the [playState](#basic-usage), [animate](#dynamic-interactions-with-animation) and [animation](#getting-animations-information) from the event object. |
+| `onFinish` | function | | It's invoked when an animation enters the `finished` state. You can access the [playState](#basic-usage), [animate](#dynamic-interactions-with-animation) and [animation](#getting-animations-information) from the event object. |
 
 ## Use Polyfill
 

demo/Animations/index.tsx

@@ -1,26 +1,32 @@
-import { FC, ChangeEvent, useState } from "react";
+import { FC, ChangeEvent } from "react";
 
 import useWebAnimations from "../../src";
 import * as animations from "../../src/animations";
 import { container as sharedContainer, title, subtitle } from "../theme";
 import { container, link, target, select } from "./styles";
 
 const Animations: FC = () => {
-  const [val, setVal] = useState<string>("bounce");
-  // @ts-expect-error
-  const { keyframes, animationOptions } = animations[val];
-  const { ref, getAnimation } = useWebAnimations<HTMLDivElement>({
-    keyframes,
-    animationOptions: { ...animationOptions, fill: "auto" },
+  const { bounce } = animations;
+  const { ref, getAnimation, animate } = useWebAnimations<HTMLDivElement>({
+    keyframes: bounce.keyframes,
+    animationOptions: { ...bounce.animationOptions, fill: "auto" },
   });
 
   const play = () => {
     // @ts-expect-error
     getAnimation().play();
   };
 
-  const handleChangeSelect = (e: ChangeEvent<HTMLSelectElement>) => {
-    setVal(e.currentTarget.value);
+  const handleChangeSelect = ({
+    currentTarget,
+  }: ChangeEvent<HTMLSelectElement>) => {
+    // @ts-expect-error
+    const { keyframes, animationOptions } = animations[currentTarget.value];
+
+    animate({
+      keyframes,
+      animationOptions: { ...animationOptions, fill: "auto" },
+    });
   };
 
   return (

package.json

@@ -60,8 +60,7 @@
     "**/*": "prettier -w -u"
   },
   "dependencies": {
-    "@babel/runtime": "^7.14.0",
-    "use-deep-compare-effect": "^1.6.1"
+    "@babel/runtime": "^7.14.0"
   },
   "devDependencies": {
     "@babel/core": "^7.14.3",

src/__tests__/useWebAnimations.ts

@@ -22,19 +22,10 @@ describe("useWebAnimations", () => {
     ref = target,
     keyframes = mockKeyframes,
     animationOptions = mockTiming,
-    shouldUpdateAnimation = true,
     ...rest
   }: Partial<Options<HTMLDivElement>> = {}) =>
-    renderHook(
-      (config) => useWebAnimations({ ...config, shouldUpdateAnimation }),
-      {
-        initialProps: {
-          ref,
-          keyframes,
-          animationOptions,
-          ...rest,
-        },
-      }
+    renderHook(() =>
+      useWebAnimations({ ref, keyframes, animationOptions, ...rest })
     );
 
   const e = { playState: "pause" };
@@ -53,32 +44,6 @@ describe("useWebAnimations", () => {
     el.animate = jest.fn(() => animation);
   });
 
-  it("should update animation", () => {
-    const { rerender } = renderHelper();
-    expect(el.animate).toHaveBeenCalledWith(mockKeyframes, 3000);
-    const elm = document.createElement("div");
-    // @ts-expect-error
-    elm.animate = jest.fn(() => animation);
-    const keyframes = { transform: ["translateX(100px)"] };
-    const animationOptions = 5000;
-    rerender({ ref: { current: elm }, keyframes, animationOptions });
-    expect(elm.animate).toHaveBeenCalledWith(keyframes, animationOptions);
-  });
-
-  it("should not update animation", () => {
-    const { rerender } = renderHelper({ shouldUpdateAnimation: false });
-    expect(el.animate).toHaveBeenCalledWith(mockKeyframes, 3000);
-    const elm = document.createElement("div");
-    // @ts-expect-error
-    elm.animate = jest.fn(() => animation);
-    rerender({
-      ref: { current: elm },
-      keyframes: { transform: ["translateX(100px)"] },
-      animationOptions: 5000,
-    });
-    expect(elm.animate).not.toHaveBeenCalled();
-  });
-
   it("should cancel animation", async () => {
     const { unmount } = renderHelper();
     unmount();
@@ -192,10 +157,10 @@ describe("useWebAnimations", () => {
   it("should return workable ref", () => {
     // @ts-expect-error
     const { result } = renderHelper({ ref: null });
-    expect(result.current.ref).toStrictEqual({ current: null });
+    expect(result.current.ref).toEqual({ current: null });
 
     result.current.ref = target;
-    expect(result.current.ref).toStrictEqual(target);
+    expect(result.current.ref).toEqual(target);
   });
 
   it("should return playState correctly", () => {
@@ -212,7 +177,7 @@ describe("useWebAnimations", () => {
 
   it("should return workable getAnimation method", () => {
     const { result } = renderHelper();
-    expect(result.current.getAnimation()).toStrictEqual(animation);
+    expect(result.current.getAnimation()).toEqual(animation);
   });
 
   it("should return workable animate method", () => {

src/use-web-animations.d.ts

@@ -5,18 +5,19 @@ declare module "@wellyshen/use-web-animations" {
 
   export type PlayState = string | null;
 
-  type AnimConf = Partial<{
+  type BaseOptions = Partial<{
     id: string;
     playbackRate: number;
     autoPlay: boolean;
     animationOptions:
       | number
       | (KeyframeAnimationOptions & { pseudoElement?: string });
-    shouldUpdateAnimation: boolean;
   }>;
 
+  export type AnimateOptions = BaseOptions & { keyframes: Keyframes };
+
   export interface Animate {
-    (args: AnimConf & { keyframes: Keyframes }): void;
+    (options: AnimateOptions): void;
   }
 
   export interface Event {
@@ -29,18 +30,22 @@ declare module "@wellyshen/use-web-animations" {
     (event: Event): void;
   }
 
-  export interface Options<T> extends AnimConf {
+  export interface Options<T> extends BaseOptions {
     ref?: RefObject<T>;
-    keyframes: Keyframes;
+    keyframes?: Keyframes;
     onReady?: Callback;
     onUpdate?: Callback;
     onFinish?: Callback;
   }
 
+  export interface GetAnimation {
+    (): Animation | undefined;
+  }
+
   export interface Return<T> {
     ref: RefObject<T>;
     playState: PlayState;
-    getAnimation: () => Animation | undefined;
+    getAnimation: GetAnimation;
     animate: Animate;
   }
 

src/useWebAnimations.ts

@@ -1,5 +1,4 @@
 import { RefObject, useState, useRef, useCallback, useEffect } from "react";
-import useDeepCompareEffect from "use-deep-compare-effect";
 
 import useLatest from "./useLatest";
 
@@ -10,17 +9,16 @@ export const eventErr = (type: string): string =>
 
 type Keyframes = Keyframe[] | PropertyIndexedKeyframes;
 type PlayState = string | null;
-type AnimConf = Partial<{
+type BaseOptions = Partial<{
   id: string;
   playbackRate: number;
   autoPlay: boolean;
   animationOptions:
     | number
     | (KeyframeAnimationOptions & { pseudoElement?: string });
-  shouldUpdateAnimation: boolean;
 }>;
 interface Animate {
-  (args: AnimConf & { keyframes: Keyframes }): void;
+  (options: BaseOptions & { keyframes: Keyframes }): void;
 }
 interface Callback {
   (event: {
@@ -29,9 +27,9 @@ interface Callback {
     animation: Animation;
   }): void;
 }
-export interface Options<T> extends AnimConf {
+export interface Options<T> extends BaseOptions {
   ref?: RefObject<T>;
-  keyframes: Keyframes;
+  keyframes?: Keyframes;
   onReady?: Callback;
   onUpdate?: Callback;
   onFinish?: Callback;
@@ -50,16 +48,17 @@ const useWebAnimations = <T extends HTMLElement>({
   autoPlay,
   keyframes,
   animationOptions,
-  shouldUpdateAnimation = true,
   onReady,
   onUpdate,
   onFinish,
-}: Options<T>): Return<T> => {
+}: Options<T> = {}): Return<T> => {
   const [playState, setPlayState] = useState<PlayState>(null);
   const hasUnmountedRef = useRef(false);
   const animRef = useRef<Animation>();
   const prevPendingRef = useRef<boolean>();
   const prevPlayStateRef = useRef<string>();
+  const keyframesRef = useRef(keyframes);
+  const animationOptionsRef = useRef(animationOptions);
   const onReadyRef = useLatest(onReady);
   const onUpdateRef = useLatest(onUpdate);
   const onFinishRef = useLatest(onFinish);
@@ -123,14 +122,16 @@ const useWebAnimations = <T extends HTMLElement>({
     [onFinishRef, onReadyRef, ref]
   );
 
-  useDeepCompareEffect(
-    () => {
-      animate({ id, playbackRate, autoPlay, keyframes, animationOptions });
-    },
-    shouldUpdateAnimation
-      ? [id, playbackRate, autoPlay, keyframes, animationOptions, animate]
-      : [{}]
-  );
+  useEffect(() => {
+    if (keyframesRef.current)
+      animate({
+        id,
+        playbackRate,
+        autoPlay,
+        keyframes: keyframesRef.current,
+        animationOptions: animationOptionsRef.current,
+      });
+  }, [animate, autoPlay, id, playbackRate]);
 
   useEffect(() => {
     let rafId: number;

yarn.lock

@@ -1608,7 +1608,7 @@
   dependencies:
     "@types/react" "*"
 
-"@types/react@*", "@types/react@>=16.9.0", "@types/react@^17.0.0", "@types/react@^17.0.8":
+"@types/react@*", "@types/react@>=16.9.0", "@types/react@^17.0.8":
   version "17.0.8"
   resolved "https://registry.yarnpkg.com/@types/react/-/react-17.0.8.tgz#fe76e3ba0fbb5602704110fd1e3035cf394778e3"
   integrity sha512-3sx4c0PbXujrYAKwXxNONXUtRp9C+hE2di0IuxFyf5BELD+B+AXL8G7QrmSKhVwKZDbv0igiAjQAMhXj8Yg3aw==
@@ -3309,11 +3309,6 @@ delayed-stream@~1.0.0:
   resolved "https://registry.yarnpkg.com/delayed-stream/-/delayed-stream-1.0.0.tgz#df3ae199acadfb7d440aaae0b29e2272b24ec619"
   integrity sha1-3zrhmayt+31ECqrgsp4icrJOxhk=
 
-dequal@^2.0.2:
-  version "2.0.2"
-  resolved "https://registry.yarnpkg.com/dequal/-/dequal-2.0.2.tgz#85ca22025e3a87e65ef75a7a437b35284a7e319d"
-  integrity sha512-q9K8BlJVxK7hQYqa6XISGmBZbtQQWVXSrRrWreHC94rMt1QL/Impruc+7p2CYSYuVIUr+YCt6hjrs1kkdJRTug==
-
 des.js@^1.0.0:
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/des.js/-/des.js-1.0.1.tgz#5382142e1bdc53f85d86d53e5f4aa7deb91e0843"
@@ -8978,15 +8973,6 @@ url@^0.11.0:
     punycode "1.3.2"
     querystring "0.2.0"
 
-use-deep-compare-effect@^1.6.1:
-  version "1.6.1"
-  resolved "https://registry.yarnpkg.com/use-deep-compare-effect/-/use-deep-compare-effect-1.6.1.tgz#061a0ac5400aa0461e33dddfaa2a98bca873182a"
-  integrity sha512-VB3b+7tFI81dHm8buGyrpxi8yBhzYZdyMX9iBJra7SMFMZ4ci4FJ1vFc1nvChiB1iLv4GfjqaYfvbNEpTT1rFQ==
-  dependencies:
-    "@babel/runtime" "^7.12.5"
-    "@types/react" "^17.0.0"
-    dequal "^2.0.2"
-
 use@^3.1.0:
   version "3.1.1"
   resolved "https://registry.yarnpkg.com/use/-/use-3.1.1.tgz#d50c8cac79a19fbc20f2911f56eb973f4e10070f"