feature: add useAnimationLoop hook

src/hooks/useAnimationLoop/useAnimationLoop.stories.mdx

@@ -0,0 +1,61 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="hooks/useAnimationLoop" />
+
+# useAnimationLoop
+
+`useAnimationLoop` hook is a wrapper around requestAnimationFrame function. This hook will execute
+the passed callback function every frame.
+
+## Reference
+
+```ts
+function useAnimationLoop(callback: (delta: number) => void, enabled = false): void;
+```
+
+### Parameters
+
+- `callback` - function accepts `delta` parameter which represents time passed since last
+  invocation;
+- `enabled` - boolean which is used to play and pause the requestAnimationFrame
+
+### Returns
+
+- `void`
+
+## Usage
+
+```tsx
+function DemoComponent(): ReactElement {
+  const [currentTimestamp, setCurrentTimestamp] = useState(Date.now);
+  const [isRunning, toggleIsRunning] = useToggle(true);
+  useAnimationLoop(() => {
+    setCurrentTimestamp(Date.now);
+  }, isRunning);
+
+  return (
+    <div>
+      <div className="alert alert-primary">
+        <h4 className="alert-heading">Instructions!</h4>
+        <p className="mb-0">Click on the button to toggle the animation loop</p>
+      </div>
+      <div className="card border-dark" data-ref="test-area">
+        <div className="card-header">Test Area</div>
+        <div className="card-body">
+          <p>{currentTimestamp}</p>
+
+          <button
+            type="button"
+            // eslint-disable-next-line react/jsx-handler-names, react/jsx-no-bind
+            onClick={(): void => {
+              toggleIsRunning();
+            }}
+          >
+            Toggle animation loop
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+```

src/hooks/useAnimationLoop/useAnimationLoop.stories.tsx

@@ -0,0 +1,48 @@
+/* eslint-disable react/jsx-no-literals */
+import type { StoryObj } from '@storybook/react';
+import { useState, type ReactElement } from 'react';
+import { useToggle } from '../useToggle/useToggle.js';
+import { useAnimationLoop } from './useAnimationLoop.js';
+
+export default {
+  title: 'hooks/useAnimationLoop',
+};
+
+function DemoComponent(): ReactElement {
+  const [currentTimestamp, setCurrentTimestamp] = useState(Date.now);
+  const [isRunning, toggleIsRunning] = useToggle(true);
+  useAnimationLoop(() => {
+    setCurrentTimestamp(Date.now);
+  }, isRunning);
+
+  return (
+    <div>
+      <div className="alert alert-primary">
+        <h4 className="alert-heading">Instructions!</h4>
+        <p className="mb-0">Click on the button to toggle the animation loop</p>
+      </div>
+      <div className="card border-dark" data-ref="test-area">
+        <div className="card-header">Test Area</div>
+        <div className="card-body">
+          <p>{currentTimestamp}</p>
+
+          <button
+            type="button"
+            // eslint-disable-next-line react/jsx-handler-names, react/jsx-no-bind
+            onClick={(): void => {
+              toggleIsRunning();
+            }}
+          >
+            Toggle animation loop
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export const Demo: StoryObj = {
+  render() {
+    return <DemoComponent />;
+  },
+};

src/hooks/useAnimationLoop/useAnimationLoop.test.tsx

@@ -0,0 +1,108 @@
+import { jest } from '@jest/globals';
+import { renderHook, waitFor } from '@testing-library/react';
+import { useAnimationLoop } from './useAnimationLoop.js';
+
+describe('useAnimationLoop', () => {
+  it('should not crash', async () => {
+    renderHook(useAnimationLoop, {
+      initialProps: undefined,
+    });
+  });
+
+  it('should not execute the callback function when enabled is not passed', async () => {
+    const spy = jest.fn();
+    renderHook(
+      ({ callback }) => {
+        useAnimationLoop(callback);
+      },
+      {
+        initialProps: {
+          callback: () => {
+            spy();
+          },
+        },
+      },
+    );
+
+    waitFor(() => {
+      expect(spy).toBeCalledTimes(0);
+    });
+  });
+
+  it('should execute the callback function when useAnimationLoop is enabled', async () => {
+    const spy = jest.fn();
+    renderHook(
+      ({ callback, enabled }) => {
+        useAnimationLoop(callback, enabled);
+      },
+      {
+        initialProps: {
+          callback: () => {
+            spy();
+          },
+          enabled: true,
+        },
+      },
+    );
+
+    expect(spy).toBeCalledTimes(0);
+    waitFor(() => {
+      expect(spy).toBeCalled();
+    });
+  });
+
+  it('should execute another callback function when it is passed to useAnimationLoop and not execute previously passed callback function', async () => {
+    const spyFirstRender = jest.fn();
+    const spySecondRender = jest.fn();
+    const { rerender } = renderHook(
+      ({ callback, enabled }) => {
+        useAnimationLoop(callback, enabled);
+      },
+      {
+        initialProps: {
+          callback: () => {
+            spyFirstRender();
+          },
+          enabled: true,
+        },
+      },
+    );
+
+    waitFor(() => {
+      expect(spyFirstRender).toBeCalled();
+      expect(spySecondRender).toBeCalledTimes(0);
+    });
+
+    rerender({ callback: spySecondRender, enabled: true });
+    waitFor(() => {
+      expect(spySecondRender).toBeCalled();
+      expect(spyFirstRender).toBeCalledTimes(0);
+    });
+  });
+
+  it('should execute the callback function when useAnimationLoop is enabled on the first render and should not execute the callback function when useAnimationLoop is disabled on the second render', async () => {
+    const spy = jest.fn();
+    const { rerender } = renderHook(
+      ({ callback, enabled }) => {
+        useAnimationLoop(callback, enabled);
+      },
+      {
+        initialProps: {
+          callback: () => {
+            spy();
+          },
+          enabled: true,
+        },
+      },
+    );
+
+    waitFor(() => {
+      expect(spy).toBeCalled();
+    });
+
+    rerender({ callback: spy, enabled: false });
+    waitFor(() => {
+      expect(spy).toBeCalledTimes(0);
+    });
+  });
+});

src/hooks/useAnimationLoop/useAnimationLoop.ts

@@ -0,0 +1,41 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { useRefValue } from '../useRefValue/useRefValue.js';
+
+/**
+ * useAnimationLoop hook is a wrapper around requestAnimationFrame method.
+ * This hook will execute a callback function every next frame.
+ *
+ * @param callback - callback function with @param delta which represents time passed since last invocation
+ * @param enabled - boolean which is used to play and pause the requestAnimationFrame
+ */
+export function useAnimationLoop(callback: (delta: number) => void, enabled = false): void {
+  const animationFrameRef = useRef(0);
+  const lastTimeRef = useRef(0);
+  const callbackRef = useRefValue(callback);
+
+  const tick = useCallback((time: number): void => {
+    const delta = time - lastTimeRef.current;
+    lastTimeRef.current = time;
+
+    callbackRef.current?.(delta);
+
+    animationFrameRef.current = requestAnimationFrame(tick);
+  }, []);
+
+  const play = useCallback(() => {
+    lastTimeRef.current = performance.now();
+    requestAnimationFrame(tick);
+  }, [tick]);
+
+  const pause = useCallback(() => {
+    cancelAnimationFrame(animationFrameRef.current);
+  }, []);
+
+  useEffect(() => {
+    if (enabled) {
+      play();
+    }
+
+    return pause;
+  }, [enabled, pause, play]);
+}