feat: implement new hook - useScreenOrientation

Checks if screen is in `portrait` or `landscape` orientation
and automatically re-renders on orientation change.

#

README.md

@@ -158,6 +158,9 @@ Coming from `react-use`? Check out our
     — Tracks the state of CSS media query.
   - [**`useResizeObserver`**](https://react-hookz.github.io/web/?path=/docs/sensor-useresizeobserver--example)
     — Invokes a callback whenever ResizeObserver detects a change to target's size.
+  - [**`useScreenOrientation`**](https://react-hookz.github.io/web/?path=/docs/sensor-usescreenorientation--example)
+    — Checks if screen is in `portrait` or `landscape` orientation and automatically re-renders on
+    orientation change.
 
 - #### Dom
 

src/index.ts

@@ -88,6 +88,11 @@ export {
   IUseKeyboardEventOptions,
 } from './useKeyboardEvent/useKeyboardEvent';
 
+export {
+  ScreenOrientation,
+  useScreenOrientation,
+} from './useScreenOrientation/useScreenOrientation';
+
 // Dom
 export { useClickOutside } from './useClickOutside/useClickOutside';
 export { useDocumentTitle, IUseDocumentTitleOptions } from './useDocumentTitle/useDocumentTitle';

src/usePreviousDistinct/usePreviousDistinct.ts

@@ -2,6 +2,7 @@ import { useRef, useState } from 'react';
 import { useUpdateEffect } from '..';
 import { isStrictEqual } from '../util/const';
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type Predicate = (prev: any, next: any) => boolean;
 
 /**

src/useScreenOrientation/__docs__/example.stories.tsx

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import { useScreenOrientation } from '../..';
+
+export const Example: React.FC = () => {
+  const orientation = useScreenOrientation();
+
+  return (
+    <div>
+      <div>
+        Orientation: <code>{orientation}</code>
+      </div>
+      <div>
+        Render time: <code>{new Date().toLocaleString()}</code>
+      </div>
+    </div>
+  );
+};

src/useScreenOrientation/__docs__/story.mdx

@@ -0,0 +1,41 @@
+import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
+import { Example } from './example.stories';
+import { ImportPath } from '../../storybookUtil/ImportPath';
+
+<Meta title="Sensor/useScreenOrientation" component={Example} />
+
+# useScreenOrientation
+
+Checks if screen is in `portrait` or `landscape` orientation and automatically re-renders on
+orientation change.
+
+As [Screen Orientation API](https://developer.mozilla.org/en-US/docs/Web/API/Screen_Orientation_API#browser_compatibility)
+is still experimental and not supported by Safari, this hook uses CSS3 `orientation` media-query to
+check screen orientation.
+
+- Automatically re-renders on screen orientation change.
+- Works in sync with CSS, as it uses media-query.
+- All hooks uses single media query - therefore it is extremely performant.
+- SSR-friendly.
+
+#### Example
+
+<Canvas>
+  <Story story={Example} inline />
+</Canvas>
+
+## Reference
+
+```ts
+type ScreenOrientation = 'portrait' | 'landscape';
+
+function useScreenOrientation(): ScreenOrientation;
+```
+
+#### Importing
+
+<ImportPath />
+
+#### Return
+
+A string representing screen orientation

src/useScreenOrientation/__tests__/dom.ts

@@ -0,0 +1,71 @@
+import { act, renderHook } from '@testing-library/react-hooks/dom';
+import { useScreenOrientation } from '../..';
+
+describe('useScreenOrientation', () => {
+  // have to copy implementation as jsdom lacks of it
+  type IMutableMediaQueryList = {
+    matches: boolean;
+    media: string;
+    onchange: null;
+    addListener: jest.Mock; // Deprecated
+    removeListener: jest.Mock; // Deprecated
+    addEventListener: jest.Mock;
+    removeEventListener: jest.Mock;
+    dispatchEvent: jest.Mock;
+  };
+
+  const matchMediaMock = jest.fn();
+  let initialMatchMedia: typeof window.matchMedia;
+
+  beforeAll(() => {
+    initialMatchMedia = window.matchMedia;
+    Object.defineProperty(window, 'matchMedia', {
+      writable: true,
+      value: matchMediaMock,
+    });
+  });
+
+  afterAll(() => {
+    window.matchMedia = initialMatchMedia;
+  });
+
+  beforeEach(() => {
+    matchMediaMock.mockImplementation((query) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addListener: jest.fn(), // Deprecated
+      removeListener: jest.fn(), // Deprecated
+      addEventListener: jest.fn(),
+      removeEventListener: jest.fn(),
+      dispatchEvent: jest.fn(),
+    }));
+  });
+
+  afterEach(() => {
+    matchMediaMock.mockClear();
+  });
+
+  it('should be defined', () => {
+    expect(useScreenOrientation).toBeDefined();
+  });
+
+  it('should render', () => {
+    const { result } = renderHook(() => useScreenOrientation());
+    expect(result.error).toBeUndefined();
+  });
+
+  it('should return `portrait` in case media query matches and `landscape` otherwise', () => {
+    const { result } = renderHook(() => useScreenOrientation());
+    expect(result.current).toBe('landscape');
+
+    const mql = matchMediaMock.mock.results[0].value as IMutableMediaQueryList;
+    mql.matches = true;
+
+    act(() => {
+      mql.addEventListener.mock.calls[0][1]();
+    });
+
+    expect(result.current).toBe('portrait');
+  });
+});

src/useScreenOrientation/__tests__/ssr.ts

@@ -0,0 +1,13 @@
+import { renderHook } from '@testing-library/react-hooks/server';
+import { useScreenOrientation } from '../..';
+
+describe('useScreenOrientation', () => {
+  it('should be defined', () => {
+    expect(useScreenOrientation).toBeDefined();
+  });
+
+  it('should render', () => {
+    const { result } = renderHook(() => useScreenOrientation());
+    expect(result.error).toBeUndefined();
+  });
+});

src/useScreenOrientation/useScreenOrientation.ts

@@ -0,0 +1,13 @@
+import { useMediaQuery } from '..';
+
+export type ScreenOrientation = 'portrait' | 'landscape';
+
+/**
+ * Checks if screen is in `portrait` or `landscape` orientation.
+ *
+ * As `Screen Orientation API` is still experimental and not supported by Safari, this
+ * hook uses CSS3 `orientation` media-query to check screen orientation.
+ */
+export function useScreenOrientation(): ScreenOrientation {
+  return useMediaQuery('(orientation: portrait)') ? 'portrait' : 'landscape';
+}

src/util/const.ts

@@ -11,6 +11,7 @@ export const isBrowser =
  * You should only be reaching for this function when you're attempting to prevent multiple
  * redefinitions of the same function. In-place strict equality checks are more performant.
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const isStrictEqual: Predicate = (prev: any, next: any): boolean => prev === next;
 
 export const truthyAndArrayPredicate: IConditionsPredicate = (conditions): boolean =>