[IMPL] useMediaQuery hook

Author: nDriaDev

apps/react-tools-demo/src/components/hooks/useMediaQuery/UseMediaQuery.tsx

@@ -0,0 +1,17 @@
+import { useMediaQuery } from "../../../../../../packages/react-tools/src"
+
+/**
+The component uses _useMediaQuery_ hook to detect color-scheme and displays result.
+ */
+export const UseMediaQuery = () => {
+	const mediaQuery = useMediaQuery('(prefers-color-scheme: dark)');
+
+	return <div style={{textAlign: "left"}}>
+		<p>
+			Color-scheme: {mediaQuery.matches ? "dark" : "light"}
+		</p>
+		<p>
+			Media matched: {mediaQuery.media}
+		</p>
+	</div>
+}

…components/hooks/useUpdate/UseUpdate.tsx …onents/hooks/useRerender/UseRerender.tsxapps/react-tools-demo/src/components/hooks/useUpdate/UseUpdate.tsx renamed to apps/react-tools-demo/src/components/hooks/useRerender/UseRerender.tsx apps/react-tools-demo/src/components/hooks/useUpdate/UseUpdate.tsx renamed to apps/react-tools-demo/src/components/hooks/useRerender/UseRerender.tsx

@@ -1,13 +1,13 @@
-import { useUpdate } from "../../../../../../packages/react-tools/src"
+import { useRerender } from "../../../../../../packages/react-tools/src"
 
 /**
 The component has:
 - a button that execute the update
 
 The component displays the current time. When button is clicked, it rerenders and current time is updated.
  */
-const UseUpdate = () => {
-	const update = useUpdate();
+const UseRerender = () => {
+	const update = useRerender();
 
 	return (<>
 		<button type="button" onClick={update}>Update</button>
@@ -17,6 +17,6 @@ const UseUpdate = () => {
 	</>);
 }
 
-UseUpdate.displayName = "UseUpdate";
+UseRerender.displayName = "UseRerender";
 
-export { UseUpdate };
+export { UseRerender };

apps/react-tools-demo/src/constants/components.ts

@@ -27,7 +27,7 @@ export const COMPONENTS = [
 			"useLayoutEffectCompare",
 			"useLayoutEffectDeepCompare",
 			"useLayoutEffectOnce",
-			"useUpdate",
+			"useRerender",
 			"useIsMounted"
 		],
 		//PERFORMANCE
@@ -56,7 +56,8 @@ export const COMPONENTS = [
 			"useInterval",
 			"useTextSelection",
 			"useDocumentVisibility",
-			"useClipboard"
+			"useClipboard",
+			"useMediaQuery"
 		]
 	],
 	//UTILS

apps/react-tools-demo/src/markdown/useMediaQuery.md

@@ -0,0 +1,44 @@
+# useMediaQuery
+Hook to handle CSS mediaQuery. It returns an object with __matches__ and __media__ properties and receives an optional _onChange_ function to handle _MediaQueryListEvent change_ event.
+
+## Usage
+
+```tsx
+export const UseMediaQuery = () => {
+	const mediaQuery = useMediaQuery('(prefers-color-scheme: dark)');
+
+	return <div style={{textAlign: "left"}}>
+		<p>
+			Color-scheme: {mediaQuery.matches ? "dark" : "light"}
+		</p>
+		<p>
+			Media matched: {mediaQuery.media}
+		</p>
+	</div>
+}
+```
+
+> The component uses _useMediaQuery_ hook to detect color-scheme and displays result.
+
+
+## API
+
+```tsx
+useMediaQuery (mediaQuery: string, onChange?: (evt: MediaQueryListEvent) => void ) 
+```
+
+> ### Params
+>
+> - __mediaQuery__: _string_  
+media query to test.
+> - __onChange?__: _(evt: MediaQueryListEvent) => void_  
+MediaQueryListEvent change handler.
+>
+
+> ### Returns
+>
+> __result__: object with __matches__, boolean value that returns true if the document currently matches the media query, __media__, string that represents media query.
+> - __Object__:  
+>     - __matches__ : _boolean_  
+>     - __media__ : _string_  
+>

…act-tools-demo/src/markdown/useUpdate.md …t-tools-demo/src/markdown/useRerender.mdapps/react-tools-demo/src/markdown/useUpdate.md renamed to apps/react-tools-demo/src/markdown/useRerender.md apps/react-tools-demo/src/markdown/useUpdate.md renamed to apps/react-tools-demo/src/markdown/useRerender.md

@@ -1,11 +1,11 @@
-# useUpdate
+# useRerender
 Hook that force a render.
 
 ## Usage
 
 ```tsx
-const UseUpdate = () => {
-	const update = useUpdate();
+const UseRerender = () => {
+	const update = useRerender();
 
 	return (<>
 		<button type="button" onClick={update}>Update</button>
@@ -15,9 +15,9 @@ const UseUpdate = () => {
 	</>);
 }
 
-UseUpdate.displayName = "UseUpdate";
+UseRerender.displayName = "UseRerender";
 
-export { UseUpdate };
+export { UseRerender };
 ```
 
 > The component has:
@@ -29,7 +29,7 @@ export { UseUpdate };
 ## API
 
 ```tsx
-useUpdate (): React.DispatchWithoutAction 
+useRerender (): React.DispatchWithoutAction 
 ```
 
 > ### Params

packages/react-tools/README.md

@@ -24,7 +24,7 @@
 	- [x] useLayoutEffectCompare
 	- [x] useLayoutEffectDeepCompare
 	- [x] useLayoutEffectOnce
-	- [x] useUpdate
+	- [x] useRerender
 	- [x] useIsMounted
 	- [ ] useDeferredValue (polyfill - an idea can be use setTimeout inside useEffect)
 
@@ -45,7 +45,6 @@
 	- [ ] useKeysEvents
 	- [ ] useSize
 	- [ ] useHover
-	- [ ] useMediaQuery
 	- [ ] useResponsive
 	- [ ] useClickOutside
 	- [ ] useScrollIntoView
@@ -67,6 +66,7 @@
 	- [x] useTextSelection
 	- [x] useDocumentVisibility
 	- [x] useClipboard
+	- [x] useMediaQuery
 	- [ ] useColorScheme
 	- [ ] useTitle (change document.title but also document.head.title nodeElement)
 	- [ ] useFetch

packages/react-tools/src/hooks/index.ts

@@ -25,7 +25,7 @@ export { usePublishSubscribe } from './usePublishSubscribe';
 export { useEvents } from './useEvents';
 export { useEventDispatcher } from './useEventDispatcher';
 export { useEventListener } from './useEventListener';
-export { useUpdate } from './useUpdate';
+export { useRerender } from './useRerender';
 export { usePerformAction } from './usePerformAction';
 export { useScript } from './useScript';
 export { useSyncExternalStore } from './useSyncExternalStore';
@@ -37,4 +37,5 @@ export { useTimeout } from './useTimeout';
 export { useInterval } from './useInterval';
 export { useTextSelection } from './useTextSelection';
 export { useDocumentVisibility } from './useDocumentVisibility';
-export { useClipboard } from './useClipboard';
+export { useClipboard } from './useClipboard';
+export { useMediaQuery } from './useMediaQuery';

packages/react-tools/src/hooks/useEffectOnce.ts

@@ -1,12 +1,12 @@
 import { EffectCallback, useEffect, useRef } from "react";
-import { useUpdate } from "."
+import { useRerender } from "."
 
 /**
  * **`useEffectOnce`**: Hook to executes _effect_ and _clean up_ after component mount __only once__. It prevents _React 18 StrictMode_ behavior if present, otherwise it works like a normal _useEffect_ with empty dependencies array. __*N.B.*__ Not use in a component with normal _useEffect_, if it executes a _React.DispatchAction_, because this action is executes twice if there is _React.StrictMode_.
  * @param {EffectCallback} effect
  */
 export const useEffectOnce = (effect: EffectCallback) => {
-	const update = useUpdate();
+	const update = useRerender();
 	const effectFn = useRef(effect);
 	const cleanUpFn = useRef<ReturnType<EffectCallback>>();
 	const effectCalled = useRef(false);

packages/react-tools/src/hooks/useLayoutEffectOnce.ts

@@ -1,12 +1,12 @@
 import { EffectCallback, useLayoutEffect, useRef } from "react";
-import { useUpdate } from "."
+import { useRerender } from "."
 
 /**
  * **`useLayoutEffectOnce`**: Hook to executes _effect_ and _clean up_ after component mount __only once__. It prevents _React 18 StrictMode_ behavior if present, otherwise it works like a normal _useLayoutEffect_ with empty dependencies array. __*N.B.*__ Not use in a component with normal _useLayoutEffect_, if it executes a _React.DispatchAction_, because this action is executes twice if there is _React.StrictMode_.
  * @param {EffectCallback} effect
  */
 export const useLayoutEffectOnce = (effect: EffectCallback) => {
-	const update = useUpdate();
+	const update = useRerender();
 	const effectFn = useRef(effect);
 	const cleanUpFn = useRef<ReturnType<EffectCallback>>();
 	const effectCalled = useRef(false);

packages/react-tools/src/hooks/useMediaQuery.ts

@@ -0,0 +1,42 @@
+import { useCallback, useRef } from "react"
+import { useSyncExternalStore } from "."
+
+/**
+ * **`useMediaQuery`**: Hook to handle CSS mediaQuery. It returns an object with __matches__ and __media__ properties and receives an optional _onChange_ function to handle _MediaQueryListEvent change_ event.
+ * @param {string} mediaQuery - media query to test.
+ * @param {(evt: MediaQueryListEvent) => void} [onChange] - MediaQueryListEvent change handler.
+ * @returns {{matches: boolean, media: string}} result - object with __matches__, boolean value that returns true if the document currently matches the media query, __media__, string that represents media query.
+ */
+export const useMediaQuery = (mediaQuery: string, onChange?: (evt: MediaQueryListEvent) => void ): {matches: boolean, media: string} => {
+	const cachedMediaQuery = useRef((() => {
+		const {media, matches} = window.matchMedia(mediaQuery);
+		return {
+			matches,
+			media
+		}
+	})());
+
+	return useSyncExternalStore(
+		useCallback(notif => {
+			const mq = window.matchMedia(mediaQuery);
+			const listener = (evt: MediaQueryListEvent) => {
+				!!onChange && onChange(evt);
+				notif();
+			}
+			mq.addEventListener("change", listener);
+			return () => {
+				mq.removeEventListener("change", listener);
+			}
+		}, [mediaQuery, onChange]),
+		useCallback(() => {
+			const {media, matches} = window.matchMedia(mediaQuery);
+			if (matches !== cachedMediaQuery.current.matches) {
+				cachedMediaQuery.current = {
+					matches,
+					media
+				};
+			}
+			return cachedMediaQuery.current;
+		}, [mediaQuery])
+	)
+}