Update README and examples

Author: trurl-master

README.md

@@ -227,6 +227,83 @@ it('prints the size of the div', () => {
 
 Triggers all resize observer callbacks for all observers that observe the passed elements
 
+## Mock Web Animations API
+
+_Warning: **experimental**, bug reports, tests and feedback are greatly appreciated_
+
+Mocks WAAPI functionality using `requestAnimationFrame`. With one important limitation — there are no style interpolations. Each frame applies the closest keyframe from list of passed keyframes or a generated "initial keyframe" if only one keyframe is passed (initial keyframe removes/restores all the properties set by the one keyframe passed). As the implementation is based on the [official spec](https://www.w3.org/TR/web-animations-1/) it should support the majority of cases, but the test suite is far from complete, so _here be dragons_
+
+Example, using `React Testing Library`:
+
+```jsx
+import { mockAnimationsApi } from 'jsdom-testing-mocks';
+
+const TestComponent = () => {
+  const [isShown, setIsShown] = useState(false);
+
+  return (
+    <div>
+      {/* AnimatePresence is a component that adds its children in the dom
+          and fades it in using WAAPI, with 2 keyframes: [{ opacity: 0 }, { opacity: 1 }],
+          also adding a div with the word "Done!" after the animation has finished
+          You can find implementation in examples
+       */}
+      <AnimatePresence>{isShown && <div>Hehey!</div>}</AnimatePresence>
+      <button
+        onClick={() => {
+          setIsShown(true);
+        }}
+      >
+        Show
+      </button>
+    </div>
+  );
+};
+
+mockAnimationsApi();
+
+it('adds an element into the dom and fades it in', async () => {
+  render(<TestComponent />);
+
+  expect(screen.queryByText('Hehey!')).not.toBeInTheDocument();
+
+  await userEvent.click(screen.getByText('Show'));
+
+  // assume there's only one animation present in the document at this point
+  // in practice it's better to get the running animation from the element itself
+  const element = screen.getByText('Hehey!');
+  const animation = document.getAnimations()[0];
+
+  // our AnimatePresence implementation has 2 keyframes: opacity: 0 and opacity: 1
+  // which allows us to test the visibility of the element, the first keyframe
+  // is applied right after the animation is ready
+  await animation.ready;
+
+  expect(element).not.toBeVisible();
+
+  // this test will pass right after 50% of the animation is complete
+  // because this mock doesn't interpolate keyframes values,
+  // but chooses the closest one at each frame
+  await waitFor(() => {
+    expect(element).toBeVisible();
+  });
+
+  // AnimatePresence will also add a div with the text 'Done!' after animation is complete
+  await waitFor(() => {
+    expect(screen.getByText('Done!')).toBeInTheDocument();
+  });
+});
+```
+
+### Using with fake timers
+
+It's perfectly usable with fake timers, except for the [issue with promises](https://github.com/facebook/jest/issues/2157). Also note that you would need to manually advance timers by the duration of the animation taking frame duration (which currently is set to 16ms in `jest`/`sinon.js`) into account. So if you, say, have an animation with a duration of `300ms`, you will need to advance your timers by the value that is at least the closest multiple of the frame duration, which in this case is `304ms` (`19` frames \* `16ms`). Otherwise the last frame may not fire and the animation won't finish.
+
+### Current issues
+
+- No support for `steps` easings
+- Needs more tests
+
 <!-- prettier-ignore-start -->
 
 [version-badge]: https://img.shields.io/npm/v/jsdom-testing-mocks.svg?style=flat-square

examples/src/App.tsx

@@ -8,7 +8,8 @@ import PrintMySize from './components/resize-observer/print-my-size/PrintMySize'
 import CustomUseMedia from './components/viewport/custom-use-media/CustomUseMedia';
 import DeprecatedCustomUseMedia from './components/viewport/deprecated-use-media/DeprecatedUseMedia';
 import { Layout } from './components/animations/Layout';
-import AnimationsInView from './components/animations/examples/InView';
+import AnimationsInView from './components/animations/examples/inview/InView';
+import AnimationsAnimatePresence from './components/animations/examples/animate-presence/AnimatePresence';
 import AnimationsIndex from './components/animations';
 
 function Index() {
@@ -33,6 +34,10 @@ function App() {
         />
         <Route path="/animations" element={<Layout />}>
           <Route path="in-view" element={<AnimationsInView />} />
+          <Route
+            path="animate-presence"
+            element={<AnimationsAnimatePresence />}
+          />
           <Route index element={<AnimationsIndex />} />
         </Route>
         <Route path="/" element={<Index />} />

examples/src/components/animations/Nav.tsx

@@ -7,6 +7,9 @@ const Nav = () => {
         <li>
           <a href="/animations/in-view">Motion One InView</a>
         </li>
+        <li>
+          <a href="/animations/animate-presence">AnimatePresence</a>
+        </li>
       </ul>
     </nav>
   );

examples/src/components/animations/examples/animate-presence/AnimatePresence.test.tsx

@@ -0,0 +1,42 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import { mockAnimationsApi } from '../../../../../../dist';
+
+import Readme1 from './AnimatePresence';
+
+mockAnimationsApi();
+
+describe('Animations/Readme1', () => {
+  it('adds an element into the dom and fades it in', async () => {
+    render(<Readme1 />);
+
+    expect(screen.queryByText('Hehey!')).not.toBeInTheDocument();
+
+    await userEvent.click(screen.getByText('Show'));
+
+    // assume there's only one animation present in the document at this point
+    // in practice it's better to get the running animation from the element itself
+    const element = screen.getByText('Hehey!');
+    const animation = document.getAnimations()[0];
+
+    // our AnimatePresence implementation has 2 keyframes: opacity: 0 and opacity: 1
+    // which allows us to test the visibility of the element, the first keyframe
+    // is applied right after the animation is ready
+    await animation.ready;
+
+    expect(element).not.toBeVisible();
+
+    // this test will pass right after 50% of the animation is complete
+    // because this mock doesn't interpolate keyframes values,
+    // but chooses the closest one
+    await waitFor(() => {
+      expect(element).toBeVisible();
+    });
+
+    // AnimatePresence will also add a div with the text 'Done!' after animation is complete
+    await waitFor(() => {
+      expect(screen.getByText('Done!')).toBeInTheDocument();
+    });
+  });
+});

examples/src/components/animations/examples/animate-presence/AnimatePresence.tsx

@@ -0,0 +1,67 @@
+import {
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+
+enum Presence {
+  HIDDEN,
+  IN_DOM,
+  VISIBLE,
+}
+
+const AnimatePresence = ({ children }: { children: ReactNode | undefined }) => {
+  const [presence, setPresence] = useState(Presence.HIDDEN);
+  const ref = useRef<HTMLDivElement | null>(null);
+
+  useLayoutEffect(() => {
+    if (!ref.current) {
+      return;
+    }
+
+    if (presence === Presence.IN_DOM) {
+      const animation = ref.current.animate(
+        [{ opacity: 0 }, { opacity: 1 }],
+        500
+      );
+
+      animation.addEventListener('finish', () => {
+        setPresence(Presence.VISIBLE);
+      });
+    }
+  }, [presence]);
+
+  useEffect(() => {
+    if (presence === Presence.HIDDEN && children) {
+      setPresence(Presence.IN_DOM);
+    }
+  }, [presence, children]);
+
+  return presence !== Presence.HIDDEN ? (
+    <div ref={ref}>
+      {children}
+      {presence === Presence.VISIBLE && <div>Done!</div>}
+    </div>
+  ) : null;
+};
+
+const AnimationsReadme1 = () => {
+  const [isShown, setIsShown] = useState(false);
+
+  return (
+    <div>
+      <AnimatePresence>{isShown && <div>Hehey!</div>}</AnimatePresence>
+      <button
+        onClick={() => {
+          setIsShown(true);
+        }}
+      >
+        Show
+      </button>
+    </div>
+  );
+};
+
+export default AnimationsReadme1;

examples/src/components/animations/examples/InView.tsx renamed to examples/src/components/animations/examples/inview/InView.tsx

@@ -3,7 +3,7 @@ import { render, act, screen, waitFor } from '@testing-library/react';
 import {
   mockIntersectionObserver,
   mockAnimationsApi,
-} from '../../../../../dist';
+} from '../../../../../../dist';
 
 import InView from './InView';
 

examples/src/components/animations/examples/inView.test.tsx renamed to examples/src/components/animations/examples/inview/inView.test.tsx

@@ -1,6 +1,6 @@
 {
   "name": "jsdom-testing-mocks",
-  "version": "1.5.0-beta.7",
+  "version": "1.5.0-beta.8",
   "author": "Ivan Galiatin",
   "license": "MIT",
   "description": "A set of tools for emulating browser behavior in jsdom environment",
@@ -16,6 +16,7 @@
     "Resize Observer API",
     "Intersection Observer API",
     "Web Animations API",
+    "WAAPI",
     "matchMedia",
     "viewport",
     "react"