[ADD] useResponsive hook

Author: nDriaDev

apps/react-tools-demo/scripts/generateMarkdown.js

@@ -226,7 +226,7 @@ function buildHooksUtilsMarkdownObject(file) {
 		return obj;
 	}
 	const lines = getJsDoc(fileSplitted);
-	lines.forEach(line => {
+	lines.forEach((line, index) => {
 		const depuratedLine = (line.split(" * ")[1]);
 		if(depuratedLine.startsWith("@param")) {
 			const typeNameDescriptionParam = depuratedLine.split("@param ")[1];
@@ -250,6 +250,13 @@ function buildHooksUtilsMarkdownObject(file) {
 			titleDescription.shift();
 			obj.description = titleDescription.join(":").trim();
 			obj.description = obj.description.charAt(0).toUpperCase() + obj.description.substring(1);
+			let lastDescriptionIndex = index+1;
+			while([" * @param", " * @returns", "//", " */", "*/"].filter(key => lines[lastDescriptionIndex].startsWith(key)).length === 0) {
+				lastDescriptionIndex++;
+			}
+			if(lastDescriptionIndex !== (index+1)) {
+				obj.description += lines.splice(index+1, lastDescriptionIndex-1).map(el => el.split(" * ")[1]).join("\n");
+			}
 		}
 	});
 	let codeLines = fileSplitted.slice(fileSplitted.findIndex(line => line === lines.at(-1))+2);

apps/react-tools-demo/src/components/hooks/useResponsive/UseResponsive.tsx

@@ -0,0 +1,12 @@
+import { useResponsive } from "../../../../../../packages/react-tools/src"
+
+/**
+The component initialize _useResponsive_ hook without param and displays screen size value.
+
+Try to change window size to see how value changes.
+ */
+export const UseResponsive = () => {
+	const responsive = useResponsive();
+
+	return <p>{JSON.stringify(responsive, null, 2)}</p>
+}

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

@@ -47,7 +47,8 @@ export const COMPONENTS = [
 			"useEventDispatcher",
 			"usePerformAction",
 			"useDocumentVisibility",
-			"useHover"
+			"useHover",
+			"useResponsive"
 		],
 		//API DOM
 		[

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

@@ -0,0 +1,40 @@
+# useResponsive
+Hook for getting responsive window size. It receives an optional param __config__ to manually setting breakpoint keys. __config__ can have a keys subset and value can be a number or an object with _value_ and _condition_ properties. If _value_ is a number, the condition will be ">". By default Breakpoints are:
+- xs: { value: 576, condition: "<" }
+- sm: { value: 576, condition: ">=" }
+- md: { value: 768, condition: ">=" }
+- lg: { value: 992, condition: ">=" }
+- xl: { value: 1200, condition: ">=" }
+
+## Usage
+
+```tsx
+export const UseResponsive = () => {
+	const responsive = useResponsive();
+
+	return <p>{JSON.stringify(responsive, null, 2)}</p>
+}
+```
+
+> The component initialize _useResponsive_ hook without param and displays screen size value.
+> 
+> Try to change window size to see how value changes.
+
+
+## API
+
+```tsx
+useResponsive<T extends useResponsiveKeys>(config?: useResponsiveBreakpoints<T>): { [s in (keyof typeof defaultConfig)]: boolean } | { [s in useResponsiveKeys<T>]: boolean } 
+```
+
+> ### Params
+>
+> - __config?__: _useResponsiveBreakpoints_  
+custom breakpoint object.
+>
+
+> ### Returns
+>
+> __breakpoint key__: returns the __size key__ of the __config__, parameter if passed otherwise  __default config__, corresponding to the size of the window.
+> - _keyof useResponsiveBreakpoints_  
+>

packages/react-tools/README.md

@@ -45,7 +45,7 @@
 	- [x] usePerformAction
 	- [x] useDocumentVisibility
 	- [x] useHover
-	- [ ] useResponsive
+	- [x] useResponsive
 	- [ ] useClickOutside
 	- [ ] useNetwork
 	- [ ] useOnline

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

@@ -43,4 +43,5 @@ export { useColorScheme } from './useColorScheme';
 export { useTitle } from './useTitle'
 export { useLazyRef } from './useLazyRef';
 export { useId } from './useId';
-export { useHover } from './useHover';
+export { useHover } from './useHover';
+export { useResponsive } from './useResponsive';

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

@@ -0,0 +1,94 @@
+import { useCallback, useMemo, useRef } from "react";
+import { useSyncExternalStore } from ".";
+import { useResponsiveBreakpoints, useResponsiveKeys } from "../models/useResponsive.model";
+
+const listeners = new Set<() => void>();
+
+const handler = () => listeners.forEach(l => l());
+
+const defaultConfig: useResponsiveBreakpoints<"xs" | "sm" | "md" | "lg" | "xl"> = {
+	xs: {
+		value: 576,
+		condition: "<"
+	},
+	sm: {
+		value: 576,
+		condition: ">="
+	},
+	md: {
+		value: 768,
+		condition: ">="
+	},
+	lg: {
+		value: 992,
+		condition: ">="
+	},
+	xl: {
+		value: 1200,
+		condition: ">="
+	}
+};
+
+function calcResponsive<T extends useResponsiveKeys>(config?: useResponsiveBreakpoints<T>): { [s in keyof typeof defaultConfig]: boolean } | { [s in useResponsiveKeys<T>]: boolean } {
+	const width = window.innerWidth;
+	const conf = {};
+	const target = config ?? defaultConfig;
+	const keys = Object.keys(target) as ((keyof typeof conf)[]);
+	for (const key of keys) {
+		if (Reflect.get(target, key)) {
+			const point = Reflect.get(target, key);
+			const { value, condition } = typeof point === "number" ? { value: point, condition: ">" } : point;
+			Reflect.set(conf, key, eval(`${width}${condition}${value}`) as boolean);
+		}
+	}
+	return conf as typeof config extends undefined ? { [k in keyof typeof defaultConfig]: boolean } : { [k in useResponsiveKeys<T>]: boolean };
+}
+
+/**
+ * **`useResponsive`**: Hook for getting responsive window size. It receives an optional param __config__ to manually setting breakpoint keys. __config__ can have a keys subset and value can be a number or an object with _value_ and _condition_ properties. If _value_ is a number, the condition will be ">". By default Breakpoints are:
+ *
+ * - xs: { value: 576, condition: "<" }
+ * - sm: { value: 576, condition: ">=" }
+ * - md: { value: 768, condition: ">=" }
+ * - lg: { value: 992, condition: ">=" }
+ * - xl: { value: 1200, condition: ">=" }
+ * @param {useResponsiveBreakpoints} [config] - custom breakpoint object.
+ * @returns {keyof useResponsiveBreakpoints} breakpoint key - returns the __size key__ of the __config__, parameter if passed otherwise  __default config__, corresponding to the size of the window.
+ */
+function useResponsive(config?: undefined): { [s in (keyof typeof defaultConfig)]: boolean };
+function useResponsive<T extends useResponsiveKeys>(config?: useResponsiveBreakpoints<T>): { [s in useResponsiveKeys<T>]: boolean };
+function useResponsive<T extends useResponsiveKeys>(config?: useResponsiveBreakpoints<T>): { [s in (keyof typeof defaultConfig)]: boolean } | { [s in useResponsiveKeys<T>]: boolean } {
+	const configCache = useRef(() => {
+		if (config === undefined) {
+			return calcResponsive(defaultConfig);
+		} else {
+			return calcResponsive<T>(config);
+		}
+	});
+	return useSyncExternalStore(
+		useCallback(notif => {
+			listeners.size === 0 && window.addEventListener('resize', handler);
+			listeners.add(notif);
+			return () => {
+				listeners.delete(notif);
+				listeners.size === 0 && window.removeEventListener("resize", handler);
+			}
+		}, []),
+		useMemo(() => {
+			let cache = configCache.current();
+			return () => {
+				const result = configCache.current();
+				const keys = Object.keys(result);
+				for (const key of keys) {
+					if (Reflect.get(cache, key) !== Reflect.get(result, key)) {
+						cache = result;
+						break;
+					}
+				}
+				return cache;
+			}
+		}, []),
+	);
+}
+
+export { useResponsive };

packages/react-tools/src/index.ts

@@ -3,7 +3,10 @@ export type {
 	CompareFn,
 	UseScriptProps,
 	UseScriptStatus,
-	UseScript
+	UseScript,
+	TextSelection,
+	useResponsiveKeys,
+	useResponsiveBreakpoints
 } from './models'
 
 export {
@@ -52,7 +55,8 @@ export {
 	useTitle,
 	useLazyRef,
 	useId,
-	useHover
+	useHover,
+	useResponsive
 } from './hooks'
 
 export {

packages/react-tools/src/models/common.model.ts

@@ -7,3 +7,6 @@ export type DependencyListTyped<T = unknown> = ReadonlyArray<T>;
 export interface CompareFn<T = unknown> {
 	(oldDeps: DependencyListTyped<T>, newDeps: DependencyListTyped<T>): boolean
 }
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type PartialRecord<K extends keyof any, T> = Partial<Record<K, T>>

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

@@ -1,3 +1,4 @@
 export type { DependencyListTyped, CompareFn } from "./common.model";
 export type { UseScriptProps, UseScript, UseScriptStatus } from './useScript.model';
-export type { TextSelection } from './useTextSelection.model';
+export type { TextSelection } from './useTextSelection.model';
+export type { useResponsiveKeys, useResponsiveBreakpoints } from './useResponsive.model';