Config isEnabled and useIsomorphicEffect Update (#14)

* Update

* Revert

Author: PauloMFJ

.eslintrc.json

@@ -1,3 +1,3 @@
 {
-  "extends": "./node_modules/@buildinams/lint/react-typescript"
+  "extends": "./node_modules/@buildinams/lint/eslint/react-typescript"
 }

README.md

@@ -46,22 +46,37 @@ const MyComponent = () => {
 
 ## Using 'defaultValue'
 
-If you want to provide a default value for the initial render (and in server), you can pass a second argument to the hook.
+If you want to provide a default value for the initial render (and in server), you can pass it as `defaultValue` within the _optional_ config object.
 
 ```tsx
 import useMatchMedia from "@buildinams/use-match-media";
 
 const MyComponent = () => {
-  const isMobile = useMatchMedia("(max-width: 768px)", true);
+  const isMobile = useMatchMedia("(max-width: 768px)", { defaultValue: true });
   ...
 };
 ```
 
 Couple things to **note**:
 
-- The default value will only be used on the initial render. By the second render, the hook will use the actual value matched.
+- The default value will only be used on the initial render and SSR. By the second render, the hook will use the actual value matched.
 - If left `undefined`, the default value will be `false`.
 
+## Conditionally Listening to Events
+
+You can conditionally listen to events by passing a `isEnabled` prop in the config object. This accepts a `boolean` value, and will only listen to events if the value is `true` (default). For example:
+
+```tsx
+import useMatchMedia from "@buildinams/use-match-media";
+
+const MyComponent = () => {
+  const [isEnabled, setIsEnabled] = useState(false);
+
+  const isMobile = useMatchMedia("(max-width: 768px)", { isEnabled });
+  ...
+};
+```
+
 ## Requirements
 
 This library requires a minimum React version of `17.0.0`.

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "@buildinams/use-match-media",
   "description": "Stateful hook that uses the matchMedia API.",
-  "version": "0.0.6",
+  "version": "0.1.0",
   "license": "MIT",
   "author": "Build in Amsterdam <development@buildinamsterdam.com> (https://www.buildinamsterdam.com/)",
   "main": "dist/index.js",
@@ -41,22 +41,22 @@
     "react": ">=17.0.0 || 18"
   },
   "devDependencies": {
-    "@babel/preset-env": "^7.20.2",
-    "@babel/preset-typescript": "^7.18.6",
-    "@buildinams/lint": "^0.0.3",
-    "@testing-library/react": "^13.4.0",
-    "@types/jest": "^29.2.5",
-    "@types/node": "^18.11.18",
-    "@types/react": "^18.0.26",
-    "@types/react-dom": "^18.0.10",
+    "@babel/preset-env": "^7.22.7",
+    "@babel/preset-typescript": "^7.22.5",
+    "@buildinams/lint": "^0.2.1",
+    "@testing-library/react": "^14.0.0",
+    "@types/jest": "^29.5.3",
+    "@types/node": "^20.4.1",
+    "@types/react": "^18.2.14",
+    "@types/react-dom": "^18.2.6",
     "babel": "^6.23.0",
-    "jest": "^29.3.1",
-    "jest-environment-jsdom": "^29.3.1",
+    "jest": "^29.6.1",
+    "jest-environment-jsdom": "^29.6.1",
     "jest-matchmedia-mock": "^1.1.0",
     "npm-run-all": "^4.1.5",
     "react-dom": "^18.0.0",
-    "ts-jest": "^29.0.3",
+    "ts-jest": "^29.1.1",
     "ts-node": "^10.9.1",
-    "typescript": "^4.9.4"
+    "typescript": "^5.1.6"
   }
 }

package.json

@@ -1,6 +1,7 @@
-import { useEffect, useState } from "react";
+import { useState } from "react";
 
-import { EventHandler, Query } from "./types";
+import { Config, EventHandler, Query } from "./types";
+import { useIsomorphicEffect } from "./useIsomorphicEffect";
 
 const queries = new Map<string, Query>();
 
@@ -76,8 +77,9 @@ const removeListener = (query: string, listener: EventHandler) => {
  *
  * @param query - The query to match for.
  *
- * @param defaultValue - Fallback value that is returned in SSR and first match
- * of any unique query. Defaults to `false`.
+ * @param config - Optional configuration object.
+ * @param config.defaultValue - Fallback value that is returned in SSR and first match of any unique query. Defaults to `false`.
+ * @param config.isEnabled - Lets you specify whether to listen for events or not. Defaults to `true`.
  *
  * @example
  * useMatchMedia("(pointer: coarse)") -> Checks if the browser matches coarse;
@@ -89,20 +91,24 @@ const removeListener = (query: string, listener: EventHandler) => {
  * @returns matches - `true` / `false` if the device matches the query, or
  * `defaultValue` as fallback.
  */
-const useMatchMedia = (query: string, defaultValue = false) => {
-  const [matches, setMatches] = useState(getExistingMatch(query, defaultValue));
-
-  useEffect(() => {
-    const listener = (event: MediaQueryListEvent) => {
-      setMatches(event.matches);
-    };
-
-    const matches = addListener(query, listener);
-    setMatches(matches);
-
-    return () => {
-      removeListener(query, listener);
-    };
+const useMatchMedia = (query: string, config?: Config) => {
+  const [matches, setMatches] = useState(
+    getExistingMatch(query, config?.defaultValue)
+  );
+
+  useIsomorphicEffect(() => {
+    if (config?.isEnabled ?? true) {
+      const listener = (event: MediaQueryListEvent) => {
+        setMatches(event.matches);
+      };
+
+      const matches = addListener(query, listener);
+      setMatches(matches);
+
+      return () => {
+        removeListener(query, listener);
+      };
+    }
   }, [query]);
 
   return matches;

src/index.ts

@@ -5,3 +5,17 @@ export interface Query {
   existingListeners: EventHandler[];
   eventHandler: EventHandler;
 }
+
+export interface Config {
+  /**
+   * Fallback value that is returned in SSR and first match of any unique query.
+   * Defaults to `false`.
+   */
+  defaultValue?: boolean;
+
+  /**
+   * This can be used to conditionally enable / disable the event listener.
+   * Defaults to `true`.
+   */
+  isEnabled?: boolean;
+}

src/types.ts

@@ -0,0 +1,9 @@
+import { useEffect, useLayoutEffect } from "react";
+
+const IS_BROWSER = typeof window !== "undefined";
+
+/**
+ * Small hook to run `useLayoutEffect` on the browser and `useEffect` on the
+ * server. This is useful for SSR, where `useLayoutEffect` will throw an error.
+ */
+export const useIsomorphicEffect = IS_BROWSER ? useLayoutEffect : useEffect;

src/useIsomorphicEffect.ts

@@ -50,4 +50,12 @@ describe("The hook", () => {
 
     expect(matchMedia.getListeners(query).length).toEqual(0);
   });
+
+  it("doesn't add event listener if listen is set to 'false' on mount", () => {
+    const query = "(pointer: coarse)";
+
+    renderHook(() => useMatchMedia(query, { isEnabled: false }));
+
+    expect(matchMedia.getListeners(query).length).toEqual(0);
+  });
 });