UX-261 Create usePrefersReducedMotion hook

cypress/integration/usePrefersReducedMotion.spec.js

@@ -0,0 +1,22 @@
+/// <reference types="Cypress" />
+
+describe('usePrefersReducedMotion hook', () => {
+  beforeEach(() => {
+    cy.visit('/iframe.html?path=/story/utility-useprefersreducedmotion--example-usage');
+    // Setting viewport dimensions to avoid side effects
+    cy.viewport(500, 500);
+  });
+
+  it('should set no-preference or reduce', () => {
+    const REDUCE = '(prefers-reduced-motion: reduce)';
+    const NO_PREFERENCE = '(prefers-reduced-motion: no-preference)';
+
+    if (window.matchMedia(REDUCE).matches) {
+      cy.contains('reduce').should('exist');
+    }
+
+    if (window.matchMedia(NO_PREFERENCE).matches) {
+      cy.contains('no-preference').should('exist');
+    }
+  });
+});

packages/matchbox/src/hooks/index.js

@@ -6,3 +6,4 @@ export { default as useResizeObserver } from './useResizeObserver';
 export { default as useTabs } from './useTabs';
 export { default as useWindowEvent } from './useWindowEvent';
 export { default as useInView } from './useInView';
+export { default as usePrefersReducedMotion } from './usePrefersReducedMotion';

packages/matchbox/src/hooks/useInView.js

@@ -3,6 +3,17 @@ import useWindowEvent from './useWindowEvent';
 import { getRectFor } from '../helpers/geometry';
 import { getWindow } from '../helpers/window';
 
+/**
+ * Reusable hook that returns true when element is scrolled into view
+ *
+ * @param {Boolean} once // defaults to true. If set to false the inView param will change when the element is scrolled into and out of view
+ *
+ * @example
+ * const [ref, inView] = useInView({ once: false });
+ * return <div>{inView ? 'In View' : 'Not In View'}</div>
+ *
+ */
+
 function useInView({ offset = 0, once = true } = {}) {
   const [node, setNode] = React.useState(null);
   const [inView, setInView] = React.useState(false);

packages/matchbox/src/hooks/usePrefersReducedMotion.js

@@ -0,0 +1,41 @@
+import React from 'react';
+import { getWindow } from '../helpers/window';
+
+/**
+ * SSR friendly hook that returns prefers-reduced-state status to disable animations
+ *
+ * @returns
+ * 'no-preference' OR 'reduce'
+ *
+ * @example
+ * const prefersReducedMotion = usePrefersReducedMotion();
+ * return <div>{prefersReducedMotion}</div>
+ */
+
+const QUERY = '(prefers-reduced-motion: reduce)';
+
+function usePrefersReducedMotion() {
+  const environment = getWindow();
+
+  const [prefersReducedMotion, setPrefersReducedMotion] = React.useState(
+    environment.matchMedia(QUERY).matches,
+  );
+
+  React.useEffect(() => {
+    const mql = environment.matchMedia(QUERY);
+
+    const listener = event => {
+      setPrefersReducedMotion(event.matches);
+    };
+
+    mql.addListener(listener);
+
+    return () => {
+      mql.removeListener(listener);
+    };
+  });
+
+  return prefersReducedMotion ? 'reduce' : 'no-preference';
+}
+
+export default usePrefersReducedMotion;

stories/utility/usePrefersReducedMotion.stories.js

@@ -0,0 +1,16 @@
+import React from 'react';
+import { Box, usePrefersReducedMotion } from '@sparkpost/matchbox';
+
+export default {
+  title: 'Utility|usePrefersReducedMotion',
+};
+
+export const ExampleUsage = () => {
+  const prefersReducedMotion = usePrefersReducedMotion();
+
+  return (
+    <>
+      <Box>(prefers-reduced-motion: {prefersReducedMotion})</Box>
+    </>
+  );
+};