[IMPL] useColorScheme hook

Author: nDriaDev

apps/react-tools-demo/src/App.css

@@ -575,4 +575,21 @@ button:not(:disabled) {
 	.docs-md {
 		width: 100%;
 	}
+}
+
+.container-themed {
+	border: 1px solid;
+	padding: 1em;
+	width: fit-content;
+	margin: 0 auto;
+}
+
+.container-themed[data-color="dark"] {
+	border-color: lightskyblue;
+	color: plum
+}
+
+.container-themed[data-color="light"] {
+	border-color: purple;
+	color: lightskyblue;
 }

apps/react-tools-demo/src/components/hooks/useColorScheme/UseColorScheme.tsx

@@ -0,0 +1,26 @@
+import { useCallback } from "react";
+import { useColorScheme } from "../../../../../../packages/react-tools/src"
+
+/**
+The component uses _useColorScheme_ with these properties:
+- _defaultValue_: __"mediaQuery"__, so it read color-scheme with media query.
+- _returnValue_: __true__, so it returns current value.
+- _getter_: a function that returns value from sessionStorage item with key "color-scheme".
+- _setter_: a function that save current value to sessionStorage item with key "color-scheme".
+The component renders a div with a class container that changes border and text colors by color-scheme selected and a button to manually change value.
+ */
+export const UseColorScheme = () => {
+	const [value, update] = useColorScheme({
+		defaultValue: "mediaQuery",
+		returnValue: true,
+		getter: useCallback(() => sessionStorage.getItem("color-scheme") as "dark" | "light" | null, []),
+		setter: useCallback((val: "dark" | "light") => sessionStorage.setItem("color-scheme", val), [])
+	});
+
+	return (
+		<div className="container-themed" data-color={value}>
+			<p>Current color-scheme is: {value}</p>
+			<button onClick={() => update(value === "dark" ? "light" : "dark")}>Change color</button>
+		</div>
+	);
+}

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

@@ -57,7 +57,8 @@ export const COMPONENTS = [
 			"useTextSelection",
 			"useDocumentVisibility",
 			"useClipboard",
-			"useMediaQuery"
+			"useMediaQuery",
+			"useColorScheme"
 		]
 	],
 	//UTILS

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

@@ -0,0 +1,58 @@
+# useColorScheme
+Hook to handle ColorScheme.
+
+## Usage
+
+```tsx
+export const UseColorScheme = () => {
+	const [value, update] = useColorScheme({
+		defaultValue: "mediaQuery",
+		returnValue: true,
+		getter: useCallback(() => sessionStorage.getItem("color-scheme") as "dark" | "light" | null, []),
+		setter: useCallback((val: "dark" | "light") => sessionStorage.setItem("color-scheme", val), [])
+	});
+
+	return (
+		<div className="container-themed" data-color={value}>
+			<button onClick={()=>update(value === "dark" ? "light" : "dark")}>Change color</button>
+		</div>
+	);
+}
+```
+
+> The component uses _useColorScheme_ with these properties:
+> - _defaultValue_: __"mediaQuery"__, so it read color-scheme with media query.
+> - _returnValue_: __true__, so it returns current value.
+> - _getter_: a function that returns value from sessionStorage item with key "color-scheme".
+> - _setter_: a function that save current value to sessionStorage item with key "color-scheme".
+> The component renders a div with a class container that changes border and text colors by color-scheme selected and a button to manually change value.
+
+
+## API
+
+```tsx
+useColorScheme({ defaultValue, getter, setter, returnValue }: { defaultValue: "dark" | "light" | "mediaQuery", getter?: () => "dark" | "light" | null | undefined, setter?: (schema: "light"|"dark") => void, returnValue: boolean }): ["light" | "dark", (schema: "light" | "dark") => void] | ((schema: "light" | "dark") => void) 
+```
+
+> ### Params
+>
+> - __param__: _Object_
+> - __param.defaultValue__: _"dark"|"light"|"mediaQuery"_  
+initial value if _getter_ function isn't present or isn't return a valid value. It can be _dark_ _light_ or _mediaQuery_ which means that must to be used media query prefers-color-scheme to detect initial value.
+> - __param.getter?__: _()=>"dark"|"light"|null|undefined_  
+an optional function used to initialize current value. For example, it can be useful for reading the value from an attribute of an html file or from localStorage.
+> - __param.setter?__: _("dark"|"light")=>void_  
+an optional function, which should work in conjunction with the _getter_ function, to run when the color scheme changes to save the value for future runs.
+> - __param.returnValue__: _boolean_  
+if true returns only a function to manually change the color scheme value.
+>
+
+> ### Returns
+>
+> __result__: if _returnValue_ is true, _result_ is the function to update color scheme value, otherwise is an array where first element is current value and second element is the function to update value.
+> - __Union of__:  
+>     - __Array__:  
+>         - _"dark"|"light"_  
+>         - _(schema:"dark"|"light") => void_  
+>     - _(schema:"dark"|"light") => void_  
+>

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

@@ -24,7 +24,7 @@ export const UseMediaQuery = () => {
 ## API
 
 ```tsx
-useMediaQuery (mediaQuery: string, onChange?: (evt: MediaQueryListEvent) => void ) 
+useMediaQuery (mediaQuery: string, onChange?: (evt: MediaQueryListEvent) => void ): {matches: boolean, media: string} 
 ```
 
 > ### Params

packages/react-tools/README.md

@@ -67,7 +67,7 @@
 	- [x] useDocumentVisibility
 	- [x] useClipboard
 	- [x] useMediaQuery
-	- [ ] useColorScheme
+	- [x] useColorScheme
 	- [ ] useTitle (change document.title but also document.head.title nodeElement)
 	- [ ] useFetch
 	- [ ] useAsync

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

@@ -38,4 +38,5 @@ export { useInterval } from './useInterval';
 export { useTextSelection } from './useTextSelection';
 export { useDocumentVisibility } from './useDocumentVisibility';
 export { useClipboard } from './useClipboard';
-export { useMediaQuery } from './useMediaQuery';
+export { useMediaQuery } from './useMediaQuery';
+export { useColorScheme } from './useColorScheme';

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

@@ -0,0 +1,65 @@
+import { useCallback, useMemo, useRef } from "react";
+import { useSyncExternalStore } from "."
+
+/**
+ * **`useColorScheme`**: Hook to handle ColorScheme.
+ * @param {Object} param
+ * @param {"dark"|"light"|"mediaQuery"} param.defaultValue - initial value if _getter_ function isn't present or isn't return a valid value. It can be _dark_ _light_ or _mediaQuery_ which means that must to be used media query prefers-color-scheme to detect initial value.
+ * @param {()=>"dark"|"light"|null|undefined} [param.getter] - an optional function used to initialize current value. For example, it can be useful for reading the value from an attribute of an html file or from localStorage.
+ * @param {("dark"|"light")=>void} [param.setter] - an optional function, which should work in conjunction with the _getter_ function, to run when the color scheme changes to save the value for future runs.
+ * @param {boolean} param.returnValue - if true returns only a function to manually change the color scheme value.
+ * @returns {["dark"|"light", (schema:"dark"|"light") => void] | (schema:"dark"|"light") => void} result - if _returnValue_ is true, _result_ is the function to update color scheme value, otherwise is an array where first element is current value and second element is the function to update value.
+ */
+function useColorScheme({ defaultValue, getter, setter, returnValue }: { defaultValue: "dark" | "light" | "mediaQuery", getter?: () => "dark" | "light" | null | undefined, setter?: (schema: "light" | "dark") => void, returnValue: true }): ["light" | "dark", (schema: "light" | "dark") => void]
+function useColorScheme({ defaultValue, getter, setter, returnValue }: { defaultValue: "dark" | "light" | "mediaQuery", getter?: () => "dark" | "light" | null | undefined, setter?: (schema: "light" | "dark") => void, returnValue: false }): ((schema: "light" | "dark") => void)
+function useColorScheme({ defaultValue, getter, setter, returnValue }: { defaultValue: "dark" | "light" | "mediaQuery", getter?: () => "dark" | "light" | null | undefined, setter?: (schema: "light"|"dark") => void, returnValue: boolean }): ["light" | "dark", (schema: "light" | "dark") => void] | ((schema: "light" | "dark") => void) {
+	const currentValue = useRef<"dark" | "light">(useMemo(() => {
+		let val = getter ? getter() : null;
+		if (!val) {
+			val = defaultValue === "mediaQuery" ? window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light" : defaultValue;
+			setter && setter(val);
+		}
+		return val;
+	},[]));
+	const cacheValue = useRef(currentValue.current);
+	const notifRef = useRef<(() => void) | null>();
+
+	const updateValue = useCallback((schema: "dark" | "light") => {
+		currentValue.current = schema;
+		setter && setter(currentValue.current);
+		notifRef.current && notifRef.current();
+	}, [setter])
+
+	const value = useSyncExternalStore(
+		useCallback(notif => {
+			notifRef.current = notif;
+			const mq = window.matchMedia("(prefers-color-scheme: dark)")
+			const listener = (evt: MediaQueryListEvent) => {
+				updateValue(evt.matches ? "dark" : "light");
+			};
+
+			defaultValue === "mediaQuery" && mq.addEventListener("change", listener)
+			return () => {
+				defaultValue === "mediaQuery" && mq.removeEventListener("change", listener)
+				notifRef.current = null;
+			}
+		}, [defaultValue, updateValue]),
+		useCallback(() => {
+			if (currentValue.current !== cacheValue.current) {
+				cacheValue.current = currentValue.current;
+			}
+			return cacheValue.current
+		}, [])
+	);
+
+	if (returnValue) {
+		return [
+			value,
+			updateValue
+		]
+	}
+
+	return updateValue
+}
+
+export {useColorScheme}

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

@@ -1,4 +1,4 @@
-import { Dispatch, SetStateAction, useRef, useSyncExternalStore } from "react"
+import { Dispatch, SetStateAction, useMemo, useRef, useSyncExternalStore } from "react"
 import { useEvents, useMemoizedFunction } from ".";
 
 
@@ -19,7 +19,7 @@ function useLocalStorageState<T>({ key, initialState, opts }: { key: string, ini
 	const serializer = useRef(opts?.serializer || JSON.stringify);
 	const deserializer = useRef(opts?.deserializer || JSON.parse);
 	const mode = useRef(opts?.mode || "read/write");
-	const cachedState = useRef((() => {
+	const cachedState = useRef(useMemo(() => {
 		if (mode.current === "write") {
 			return null as T;
 		}
@@ -35,7 +35,7 @@ function useLocalStorageState<T>({ key, initialState, opts }: { key: string, ini
 		} else {
 			return null as T;
 		}
-	})());
+	}, []));
 
 	const subscribeRef = useRef((cb: ()=> void) => {
 		const listener = (evt: Event) => {

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

@@ -1,4 +1,4 @@
-import { useCallback, useRef } from "react"
+import { useCallback, useMemo, useRef } from "react"
 import { useSyncExternalStore } from "."
 
 /**
@@ -8,13 +8,13 @@ import { useSyncExternalStore } from "."
  * @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);
+	const cachedMediaQuery = useRef(useMemo(() => {
+		const { media, matches } = window.matchMedia(mediaQuery);
 		return {
 			matches,
 			media
 		}
-	})());
+	}, []));
 
 	return useSyncExternalStore(
 		useCallback(notif => {