[IMPL] useBattery hook

Author: nDriaDev

apps/react-tools-demo/src/components/hooks/useBattery/UseBattery.tsx

@@ -0,0 +1,16 @@
+import { useBattery } from "../../../../../../packages/react-tools/src"
+
+/**
+The component displays device battery information.
+ */
+export const UseBattery = () => {
+	const status = useBattery();
+
+	return (<div style={{ textAlign: "center" }}>
+		{
+			Object.keys(status).map(el => (
+				<p key={el}>{el}: {status[el as keyof typeof status]}</p>
+			))
+		}
+	</div>)
+}

apps/react-tools-demo/src/components/hooks/useRaf/UseRaf.tsx

@@ -6,8 +6,8 @@ The component renders a textarea element and when it is resized, updates __state
  */
 export const UseRaf = () => {
 	const [state, setState] = useState({ width: 0, height: 0 });
-	const [start] = useRaf((timer: number, dim: DOMRectReadOnly) => {
-		setState({width:dim.width, height: dim.height})
+	const [start] = useRaf((timer: number, repeat:()=>void, dim: DOMRectReadOnly) => {
+		setState({ width: dim.width, height: dim.height });
 	});
 	const [refCb] = useResizeObserver<HTMLTextAreaElement>(
 		(entries: ResizeObserverEntry[]) => {

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

@@ -37,7 +37,6 @@ export const COMPONENTS = [
 			"useMemoDeepCompare",
 			"useCallbackCompare",
 			"useCallbackDeepCompare",
-			"useRaf",
 			"useLazyRef",
 			"useId"
 		],
@@ -71,14 +70,16 @@ export const COMPONENTS = [
 			"useActiveElement",
 			"useTimeout",
 			"useInterval",
+			"useRaf",
 			"useTextSelection",
 			"useClipboard",
 			"useMediaQuery",
 			"useColorScheme",
 			"useReducedMotion",
 			"useTitle",
 			"useIdle",
-			"useFullscreen"
+			"useFullscreen",
+			"useBattery"
 		]
 	],
 	//UTILS

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

@@ -0,0 +1,47 @@
+# useBattery
+Hook for accessing and monitoring device battery status. Refer to [Battery Status API](https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API)
+
+## Usage
+
+```tsx
+export const UseBattery = () => {
+	const status = useBattery();
+
+	return (<div style={{ textAlign: "center" }}>
+		{
+			Object.keys(status).map(el => (
+				<p key={el}>{el}: {JSON.stringify(status[el as keyof typeof status])}</p>
+			))
+		}
+	</div>)
+}
+```
+
+> The component displays device battery information.
+
+
+## API
+
+```tsx
+useBattery (opts?: { onChargingChange?: (evt: Event) => void, onChargingTimeChange?: (evt: Event) => void, onDischargingTimeChange?: (evt: Event) => void, onLevelChange?: (evt: Event) => void }): BatteryStatus 
+```
+
+> ### Params
+>
+> - __opts?__: _Object_  
+optional object parameter to listen battery events change.
+> - __opts.onChargingChange?__: _(evt: Event) => void_  
+callback that will be executed when chargingchange event is fired.
+> - __opts.onChargingTimeChange?__: _(evt: Event) => void_  
+callback that will be executed when chargingtimechange event is fired.
+> - __opts.onDischargingTimeChange?__: _(evt: Event) => void_  
+callback that will be executed when dischargingtimechange event is fired.
+> - __opts.onLevelChange?__: _(evt: Event) => void_  
+callback that will be executed when levelchange event is fired.
+>
+
+> ### Returns
+>
+> __result__: object:
+> - _BatteryStatus_  
+>

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

@@ -6,8 +6,8 @@ Hook to execute a callback function with _requestAnimationFrame_ to optimize per
 ```tsx
 export const UseRaf = () => {
 	const [state, setState] = useState({ width: 0, height: 0 });
-	const [start] = useRaf((timer: number, dim: DOMRectReadOnly) => {
-		setState({width:dim.width, height: dim.height})
+	const [start] = useRaf((timer: number, repeat:()=>void, dim: DOMRectReadOnly) => {
+		setState({ width: dim.width, height: dim.height });
 	});
 	const [refCb] = useResizeObserver<HTMLTextAreaElement>(
 		(entries: ResizeObserverEntry[]) => {
@@ -28,13 +28,13 @@ export const UseRaf = () => {
 ## API
 
 ```tsx
-useRaf <T extends unknown[]>(cb: (timer:number, ...args: T) => void): [(...args: T)=>void, ()=>void] 
+useRaf <T extends unknown[]>(cb: (timer: number, repeat: ()=>void, ...args: T) => void): [(...args: T)=>void, ()=>void] 
 ```
 
 > ### Params
 >
-> - __cb__: _(timer:number, ...args: T) => void_  
- callback to execute prior to the next repaint.
+> - __cb__: _(timer:number, ()=>void, ...args: T) => void_  
+ callback to execute prior to the next repaint. In addition to the classic timeStamp parameter, which indicates the end time of rendering of the previous frame, the second parameter is a function which, if invoked, re-executes the requestAnimationFrame with the callback itself, and finally various parameters can be added, passed with the invocation function returned by the hook.
 >
 
 > ### Returns

packages/react-tools/README.md

@@ -40,7 +40,6 @@
 	- [x] useMemoizedFunction
 	- [x] useMemoCompare
 	- [x] useMemoDeepCompare
-	- [x] useRaf
 	- [ ] useMergedRef
 	- [ ] useObjectRef
 	- [ ] useArrayRef
@@ -82,7 +81,7 @@
 	- [x] useDebounce
 	- [x] useThrottle
 	- [x] useActiveElement
-	- [ ] useRaf (with a reference to call itself again)
+	- [x] useRaf (with a reference to call itself again)
 	- [x] useTimeout
 	- [x] useInterval
 	- [x] useTextSelection
@@ -93,7 +92,7 @@
 	- [x] useTitle (change document.title but also document.head.title nodeElement)
 	- [x] useIdle
 	- [x] useFullscreen (check browser compatibility)
-	- [ ] useBattery
+	- [x] useBattery
 	- [ ] useGeolocation
 	- [ ] useShare
 	- [ ] useScreenShare
@@ -110,6 +109,7 @@
 	- [ ] useDeviceMotion (??? mobile)
 	- [ ] useVibrate (??? mobile)
 	- [ ] useObservable — tracks latest value of an Observable
+	- [ ] useLock - (https://developer.mozilla.org/en-US/docs/Web/API/LockManager/request)
 
 - __UTILS__
 	- [x] isShallowEqual

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

@@ -59,4 +59,5 @@ export { useVisible } from './useVisible';
 export { useReducedMotion } from './useReducedMotion';
 export { useScrollIntoView } from './useScrollIntoView';
 export { useMouse } from './useMouse';
-export { useLongPress } from './useLongPress';
+export { useLongPress } from './useLongPress';
+export { useBattery } from './useBattery';

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

@@ -0,0 +1,125 @@
+import { useCallback, useMemo, useRef } from "react";
+import { useSyncExternalStore } from "."
+import { BatteryStatus } from "../models";
+
+const listeners = new Set<() => void>();
+const eventsListeners = {
+	onCharging: new Set<(evt: Event) => void>(),
+	onChargingTime: new Set<(evt: Event) => void>(),
+	onDischargingTime: new Set<(evt: Event) => void>(),
+	onLevel: new Set<(evt: Event) => void>()
+};
+let batteryCached: undefined | BatteryStatus & { onchargingchange: null | ((evt: Event) => void), onlevelchange: null | ((evt: Event) => void), onchargingtimechange: null | ((evt: Event) => void), ondischargingtimechange: null | ((evt: Event) => void) };
+
+/**
+ * **`useBattery`**: Hook for accessing and monitoring device battery status. Refer to [Battery Status API](https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API)
+ * @param {Object} [opts] - optional object parameter to listen battery events change.
+ * @param {(evt: Event) => void} [opts.onChargingChange] - callback that will be executed when chargingchange event is fired.
+ * @param {(evt: Event) => void} [opts.onChargingTimeChange] - callback that will be executed when chargingtimechange event is fired.
+ * @param {(evt: Event) => void} [opts.onDischargingTimeChange] - callback that will be executed when dischargingtimechange event is fired.
+ * @param {(evt: Event) => void} [opts.onLevelChange] - callback that will be executed when levelchange event is fired.
+ * @returns {BatteryStatus} result - object:
+ * - __isSupported__: boolean that indicates if Battery Status API is available.
+ * - __level__: number that indicates battery level: is a number between 0 and 1.
+ * - __charging__: boolean that indicates if battery is charging.
+ * - __chargingTime__: number that indicates time in seconds remaining to full charge, or infinity.
+ * - __dischargingTime__: number that indicates time in seconds remaining to empty charge, rounded in 15 minutes by API.
+ */
+export const useBattery = (opts?: { onChargingChange?: (evt: Event) => void, onChargingTimeChange?: (evt: Event) => void, onDischargingTimeChange?: (evt: Event) => void, onLevelChange?: (evt: Event) => void }): BatteryStatus => {
+	const status = useRef<BatteryStatus>({
+		isSupported: "getBattery" in navigator,
+		charging: false,
+		chargingTime: 0,
+		dischargingTime: 0,
+		level: 0
+	});
+
+	return useSyncExternalStore(
+		useCallback(notif => {
+			listeners.add(notif);
+			listeners.size === 1 && "getBattery" in navigator && ((navigator.getBattery as () => Promise<BatteryStatus & { [k in "onchargingchange" | "onlevelchange" | "onchargingtimechange" | "ondischargingtimechange" ]: (evt:Event)=>void}>)())
+				.then((battery: Exclude<typeof batteryCached, undefined>) => {
+					batteryCached = battery;
+					status.current = {
+						isSupported: true,
+						level: battery.level,
+						charging: battery.charging,
+						chargingTime: battery.chargingTime,
+						dischargingTime: battery.dischargingTime
+					}
+					listeners.forEach(l => l());
+					opts?.onChargingChange && eventsListeners.onCharging.add(opts.onChargingChange);
+					opts?.onChargingTimeChange && eventsListeners.onChargingTime.add(opts.onChargingTimeChange);
+					opts?.onDischargingTimeChange && eventsListeners.onDischargingTime.add(opts.onDischargingTimeChange);
+					opts?.onLevelChange && eventsListeners.onLevel.add(opts.onLevelChange);
+					battery.onchargingchange = (evt) => {
+						status.current = {
+							isSupported: true,
+							level: battery.level,
+							charging: battery.charging,
+							chargingTime: battery.chargingTime,
+							dischargingTime: battery.dischargingTime
+						}
+						eventsListeners.onCharging.forEach(l => l(evt));
+						listeners.forEach(l => l());
+					};
+					battery.onchargingtimechange = (evt) => {
+						status.current = {
+							isSupported: true,
+							level: battery.level,
+							charging: battery.charging,
+							chargingTime: battery.chargingTime,
+							dischargingTime: battery.dischargingTime
+						}
+						eventsListeners.onChargingTime.forEach(l => l(evt));
+						listeners.forEach(l => l());
+					}
+					battery.ondischargingtimechange = (evt) => {
+						status.current = {
+							isSupported: true,
+							level: battery.level,
+							charging: battery.charging,
+							chargingTime: battery.chargingTime,
+							dischargingTime: battery.dischargingTime
+						}
+						eventsListeners.onDischargingTime.forEach(l => l(evt));
+						listeners.forEach(l => l());
+					}
+					battery.onlevelchange = (evt) => {
+						status.current = {
+							isSupported: true,
+							level: battery.level,
+							charging: battery.charging,
+							chargingTime: battery.chargingTime,
+							dischargingTime: battery.dischargingTime
+						}
+						eventsListeners.onLevel.forEach(l => l(evt));
+						listeners.forEach(l => l());
+					}
+				})
+			return () => {
+				opts?.onChargingChange && eventsListeners.onCharging.delete(opts.onChargingChange);
+				opts?.onChargingTimeChange && eventsListeners.onChargingTime.delete(opts.onChargingTimeChange);
+				opts?.onDischargingTimeChange && eventsListeners.onDischargingTime.delete(opts.onDischargingTimeChange);
+				opts?.onLevelChange && eventsListeners.onLevel.delete(opts.onLevelChange);
+				listeners.delete(notif);
+				if (listeners.size === 0) {
+					!!batteryCached && (batteryCached.onchargingchange = null);
+					!!batteryCached && (batteryCached.onchargingtimechange = null);
+					!!batteryCached && (batteryCached.ondischargingtimechange = null);
+					!!batteryCached && (batteryCached.onlevelchange = null);
+					batteryCached = undefined;
+				}
+			}
+		}, [opts?.onChargingChange, opts?.onChargingTimeChange, opts?.onDischargingTimeChange, opts?.onLevelChange]),
+		useMemo(() => {
+			let cachedStatus: BatteryStatus = { ...status.current };
+			return () => {
+				if (status.current.isSupported !== cachedStatus.isSupported || status.current.level !== cachedStatus.level || status.current.charging !== cachedStatus.charging || status.current.chargingTime !== cachedStatus.chargingTime || status.current.dischargingTime !== cachedStatus.dischargingTime) {
+					cachedStatus = status.current;
+				}
+				return cachedStatus;
+			}
+		}, [])
+	);
+}

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

@@ -1,4 +1,5 @@
 import { RefCallback, useCallback, useRef } from "react"
+import { useEffectOnce } from ".";
 
 /**
  * **`useIntersectionObserver`**: Hook to use Intersection Observer. Refer to [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)
@@ -11,20 +12,19 @@ export const useIntersectionObserver = <T extends Element>(cb: IntersectionObser
 	const working = useRef(true);
 	const nodeRef = useRef<T>();
 
+	useEffectOnce(() => () => {
+		nodeRef.current = undefined;
+		observer.current?.disconnect();
+		observer.current = undefined;
+	});
+
 	return [
 		useCallback((node: T) => {
-			nodeRef.current = node;
-			if (!working.current) {
+			if (!working.current || !node) {
 				return;
 			}
-			if (!node) {
-				if (observer.current) {
-					observer.current.disconnect();
-					observer.current = undefined;
-					nodeRef.current = undefined;
-					working.current = true;
-				}
-			} else {
+			if (node && (!nodeRef.current || nodeRef.current !== node)) {
+				nodeRef.current = node;
 				observer.current = new IntersectionObserver(cb, opts);
 				observer.current.observe(node);
 			}

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

@@ -2,15 +2,18 @@ import { useCallback, useRef } from "react"
 
 /**
  * **`useRaf`**: Hook to execute a callback function with _requestAnimationFrame_ to optimize performance. Refer to (requestAnimationFrame)[https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame].
- * @param {(timer:number, ...args: T) => void} cb -  callback to execute prior to the next repaint.
+ * @param {(timer:number, ()=>void, ...args: T) => void} cb -  callback to execute prior to the next repaint. In addition to the classic timeStamp parameter, which indicates the end time of rendering of the previous frame, the second parameter is a function which, if invoked, re-executes the requestAnimationFrame with the callback itself, and finally various parameters can be added, passed with the invocation function returned by the hook.
  * @returns {[(...args: T)=>void, ()=>void]} results - array with __start__ function to invoke _requestAnimationFrame_ and __cancel__ function to invoke _cancelAnimationFrame_.
  */
-export const useRaf = <T extends unknown[]>(cb: (timer:number, ...args: T) => void): [(...args: T)=>void, ()=>void] => {
+export const useRaf = <T extends unknown[]>(cb: (timer: number, repeat: ()=>void, ...args: T) => void): [(...args: T)=>void, ()=>void] => {
 	const idRequest = useRef<number>();
 
 	return [
 		useCallback((...args: T) => {
-			idRequest.current = requestAnimationFrame((timer) => cb(timer, ...args));
+			const repeat = () => {
+				idRequest.current = requestAnimationFrame((timer) => cb(timer, repeat, ...args));
+			}
+			idRequest.current = requestAnimationFrame((timer) => cb(timer, repeat, ...args));
 		}, [cb]),
 		useCallback(() => {
 			!!idRequest.current && cancelAnimationFrame(idRequest.current)