main 🧊 add browser api block

siberiacancode · Mar 2, 2025 · 8d8333c · 8d8333c
1 parent 74ae3a3
commit 8d8333c
Show file tree

Hide file tree

Showing 79 changed files with 231 additions and 63 deletions.
diff --git a/packages/core/src/bundle/hooks/useBattery/useBattery.js b/packages/core/src/bundle/hooks/useBattery/useBattery.js
@@ -4,6 +4,8 @@ import { useEffect, useState } from 'react';
  * @description - Hook for getting information about battery status
  * @category Browser
  *
+ * @browserapi navigator.getBattery https://developer.mozilla.org/en-US/docs/Web/API/Navigator/getBattery
+ *
  * @returns {UseBatteryStateReturn} Object containing battery information & Battery API support
  *
  * @example

diff --git a/packages/core/src/bundle/hooks/useBluetooth/useBluetooth.js b/packages/core/src/bundle/hooks/useBluetooth/useBluetooth.js
@@ -4,6 +4,8 @@ import { useEffect, useState } from 'react';
  * @description - Hook for getting information about bluetooth
  * @category Browser
  *
+ * @browserapi navigator.bluetooth https://developer.mozilla.org/en-US/docs/Web/API/Navigator/bluetooth
+ *
  * @param {boolean} [options.acceptAllDevices=false] The options to request all Bluetooth devices
  * @param {Array<BluetoothLEScanFilter>} [options.filters] Array of filters to apply when scanning Bluetooth devices
  * @param {Array<BluetoothServiceUUID>} [options.optionalServices] Array of optional services that the application can use

diff --git a/packages/core/src/bundle/hooks/useBoolean/useBoolean.js b/packages/core/src/bundle/hooks/useBoolean/useBoolean.js
@@ -1,7 +1,7 @@
 import { useState } from 'react';
 /**
  * @name useBoolean
- * @description - Hook provides a boolean state and a function to toggle the boolean value
+ * @description - Hook provides opportunity to manage boolean state
  * @category Utilities
  *
  * @param {boolean} [initialValue=false] The initial boolean value

diff --git a/packages/core/src/bundle/hooks/useBrowserLanguage/useBrowserLanguage.js b/packages/core/src/bundle/hooks/useBrowserLanguage/useBrowserLanguage.js
@@ -10,6 +10,8 @@ const subscribe = (callback) => {
  * @description - Hook that returns the current browser language
  * @category Browser
  *
+ * @browserapi navigator.language https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language
+ *
  * @returns {string} The current browser language
  *
  * @example

diff --git a/packages/core/src/bundle/hooks/useClipboard/useClipboard.js b/packages/core/src/bundle/hooks/useClipboard/useClipboard.js
@@ -16,6 +16,8 @@ export const legacyCopyToClipboard = (value) => {
  * @description - Hook that manages a copy to clipboard
  * @category Browser
  *
+ * @browserapi navigator.clipboard https://developer.mozilla.org/en-US/docs/Web/API/Navigator/clipboard
+ *
  * @param {boolean} [params.enabled=false] Whether the copy to clipboard is enabled
  * @returns {UseCopyToClipboardReturn} An object containing the boolean state value and utility functions to manipulate the state
  *

diff --git a/packages/core/src/bundle/hooks/useCounter/useCounter.js b/packages/core/src/bundle/hooks/useCounter/useCounter.js
@@ -1,7 +1,7 @@
 import { useState } from 'react';
 /**
  * @name useCounter
- * @description - Hook that manages a counter with increment, decrement, reset, and set functionalities
+ * @description - Hook that manages a counter
  * @category Utilities
  *
  * @overload

diff --git a/packages/core/src/bundle/hooks/useCssVar/useCssVar.js b/packages/core/src/bundle/hooks/useCssVar/useCssVar.js
@@ -3,7 +3,7 @@ import { getElement } from '@/utils/helpers';
 import { useRefState } from '../useRefState/useRefState';
 /**
  * @name useCssVar
- * @description - Hook that returns the value of a CSS variable
+ * @description - Hook that returns the value of a css variable
  * @category Utilities
  *
  * @overload

diff --git a/packages/core/src/bundle/hooks/useDebounceCallback/useDebounceCallback.js b/packages/core/src/bundle/hooks/useDebounceCallback/useDebounceCallback.js
@@ -3,7 +3,7 @@ import { debounce } from '@/utils/helpers';
 import { useEvent } from '../useEvent/useEvent';
 /**
  * @name useDebounceCallback
- * @description - Hook that creates a debounced callback and returns a stable reference of it
+ * @description - Hook that creates a debounced callback
  * @category Utilities
  *
  * @template Params The type of the params

diff --git a/packages/core/src/bundle/hooks/useDebounceValue/useDebounceValue.js b/packages/core/src/bundle/hooks/useDebounceValue/useDebounceValue.js
@@ -2,7 +2,7 @@ import { useEffect, useRef, useState } from 'react';
 import { useDebounceCallback } from '../useDebounceCallback/useDebounceCallback';
 /**
  * @name useDebounceValue
- * @description - Hook that creates a debounced value and returns a stable reference of it
+ * @description - Hook that creates a debounced value
  * @category Utilities
  *
  * @template Value The type of the value

diff --git a/packages/core/src/bundle/hooks/useDeviceMotion/useDeviceMotion.js b/packages/core/src/bundle/hooks/useDeviceMotion/useDeviceMotion.js
@@ -5,6 +5,8 @@ import { throttle } from '@/utils/helpers';
  * @description - Hook that work with device motion
  * @category Utilities
  *
+ * @browserapi DeviceMotionEvent https://developer.mozilla.org/en-US/docs/Web/API/Window/DeviceMotionEvent
+ *
  * @param {number} [delay=1000] The delay in milliseconds
  * @param {(event: DeviceMotionEvent) => void} [callback] The callback function to be invoked
  * @param {boolean} [enabled=true] Whether to enable the hook

diff --git a/packages/core/src/bundle/hooks/useDeviceOrientation/useDeviceOrientation.js b/packages/core/src/bundle/hooks/useDeviceOrientation/useDeviceOrientation.js
@@ -4,6 +4,8 @@ import { useEffect, useState } from 'react';
  * @description - Hook that provides the current device orientation
  * @category Sensors
  *
+ * @browserapi DeviceOrientationEvent https://developer.mozilla.org/en-US/docs/Web/API/Window/DeviceOrientationEvent
+ *
  * @returns {UseDeviceOrientationReturn} The current device orientation
  *
  * @example

diff --git a/packages/core/src/bundle/hooks/useDevicePixelRatio/useDevicePixelRatio.js b/packages/core/src/bundle/hooks/useDevicePixelRatio/useDevicePixelRatio.js
@@ -1,9 +1,11 @@
 import { useEffect, useState } from 'react';
 /**
  * @name useDevicePixelRatio
- * @description - Hook that returns the ratio of the resolution in physical pixels to the resolution in CSS pixels for the current display device
+ * @description - Hook that returns the device's pixel ratio
  * @category Utilities
  *
+ * @browserapi window.devicePixelRatio https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio
+ *
  * @returns {UseDevicePixelRatioReturn} The ratio and supported flag
  *
  * @example

diff --git a/packages/core/src/bundle/hooks/useDidUpdate/useDidUpdate.js b/packages/core/src/bundle/hooks/useDidUpdate/useDidUpdate.js
@@ -2,7 +2,7 @@ import { useRef } from 'react';
 import { useIsomorphicLayoutEffect } from '../useIsomorphicLayoutEffect/useIsomorphicLayoutEffect';
 /**
  * @name useDidUpdate
- * @description – Hook that behaves like useEffect, but skips the effect on the initial render
+ * @description – Hook that triggers the effect callback on updates
  * @category Lifecycle
  *
  * @param {EffectCallback} effect The effect callback

diff --git a/packages/core/src/bundle/hooks/useDisplayMedia/useDisplayMedia.js b/packages/core/src/bundle/hooks/useDisplayMedia/useDisplayMedia.js
@@ -3,9 +3,11 @@ import { getElement, isTarget } from '@/utils/helpers';
 import { useRefState } from '../useRefState/useRefState';
 /**
  * @name useDisplayMedia
- * @description - Hook that provides screen sharing functionality using the Display Media API
+ * @description - Hook that provides screen sharing functionality
  * @category Browser
  *
+ * @browserapi mediaDevices.getDisplayMedia https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getDisplayMedia
+ *
  * @overload
  * @template Target The target video element
  * @param {Target} target The target video element to display the media stream

diff --git a/packages/core/src/bundle/hooks/useEyeDropper/useEyeDropper.js b/packages/core/src/bundle/hooks/useEyeDropper/useEyeDropper.js
@@ -4,6 +4,8 @@ import { useState } from 'react';
  * @description - Hook that gives you access to the eye dropper
  * @category Browser
  *
+ * @browserapi EyeDropper https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper
+ *
  * @param {string} [initialValue=undefined] The initial value for the eye dropper
  * @returns {UseEyeDropperReturn} An object containing the supported status, the value and the open method
  *

diff --git a/packages/core/src/bundle/hooks/useFps/useFps.js b/packages/core/src/bundle/hooks/useFps/useFps.js
@@ -4,6 +4,8 @@ import { useEffect, useState } from 'react';
  * @description - Hook that measures frames per second
  * @category Sensors
  *
+ * @browserapi requestAnimationFrame https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame
+ *
  * @returns {number} A number which determines frames per second
  *
  * @example

diff --git a/packages/core/src/bundle/hooks/useGamepad/useGamepad.js b/packages/core/src/bundle/hooks/useGamepad/useGamepad.js
@@ -5,6 +5,8 @@ import { useRaf } from '../useRaf/useRaf';
  * @description - Hook for getting information about gamepad
  * @category Browser
  *
+ * @browserapi navigator.getGamepads https://developer.mozilla.org/en-US/docs/Web/API/Navigator/getGamepads
+ *
  * @returns {UseGamepadStateReturn} An object containing the gamepad information
  *
  * @example
@@ -62,4 +64,39 @@ export const useGamepad = () => {
         gamepads: Object.values(gamepads)
     };
 };
-export { mapGamepadToXbox360Controller } from './helpers';
+export const mapGamepadToXbox360Controller = (gamepad) => ({
+    buttons: {
+        a: gamepad.buttons[0],
+        b: gamepad.buttons[1],
+        x: gamepad.buttons[2],
+        y: gamepad.buttons[3]
+    },
+    bumper: {
+        left: gamepad.buttons[4],
+        right: gamepad.buttons[5]
+    },
+    triggers: {
+        left: gamepad.buttons[6],
+        right: gamepad.buttons[7]
+    },
+    stick: {
+        left: {
+            horizontal: gamepad.axes[0],
+            vertical: gamepad.axes[1],
+            button: gamepad.buttons[10]
+        },
+        right: {
+            horizontal: gamepad.axes[2],
+            vertical: gamepad.axes[3],
+            button: gamepad.buttons[11]
+        }
+    },
+    dpad: {
+        up: gamepad.buttons[12],
+        down: gamepad.buttons[13],
+        left: gamepad.buttons[14],
+        right: gamepad.buttons[15]
+    },
+    back: gamepad.buttons[8],
+    start: gamepad.buttons[9]
+});
diff --git a/packages/core/src/bundle/hooks/useGeolocation/useGeolocation.js b/packages/core/src/bundle/hooks/useGeolocation/useGeolocation.js
@@ -4,6 +4,8 @@ import { useEffect, useState } from 'react';
  * @description - Hook that returns the current geolocation
  * @category Browser
  *
+ * @browserapi navigator.geolocation https://developer.mozilla.org/en-US/docs/Web/API/Navigator/geolocation
+ *
  * @param {boolean} [params.enableHighAccuracy] Enable high accuracy
  * @param {number} [params.maximumAge] Maximum age
  * @param {number} [params.timeout] Timeout

diff --git a/packages/core/src/bundle/hooks/useLocalStorage/useLocalStorage.js b/packages/core/src/bundle/hooks/useLocalStorage/useLocalStorage.js
@@ -4,6 +4,8 @@ import { useStorage } from '../useStorage/useStorage';
  * @description - Hook that manages local storage value
  * @category Browser
  *
+ * @browserapi window.localStorage https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage
+ *
  * @template Value The type of the value
  * @param {string} key The key of the storage
  * @param {UseStorageInitialValue<Value>} [initialValue] The initial value of the storage

diff --git a/packages/core/src/bundle/hooks/useMediaQuery/useMediaQuery.js b/packages/core/src/bundle/hooks/useMediaQuery/useMediaQuery.js
@@ -5,6 +5,8 @@ const getServerSnapshot = () => false;
  * @description - Hook that manages a media query
  * @category Browser
  *
+ * @browserapi window.matchMedia https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia
+ *
  * @param {string} query The media query string
  * @returns {boolean} A boolean indicating if the media query matches
  *

diff --git a/packages/core/src/bundle/hooks/useMemory/useMemory.js b/packages/core/src/bundle/hooks/useMemory/useMemory.js
@@ -5,6 +5,8 @@ import { useInterval } from '../useInterval/useInterval';
  * @description - Hook that gives you current memory usage
  * @category Browser
  *
+ * @browserapi performance.memory https://developer.mozilla.org/en-US/docs/Web/API/Performance/memory
+ *
  * @returns {UseMemoryReturn} An object containing the current memory usage
  *
  * @example

diff --git a/packages/core/src/bundle/hooks/useNetwork/useNetwork.js b/packages/core/src/bundle/hooks/useNetwork/useNetwork.js
@@ -5,6 +5,8 @@ export const getConnection = () => navigator?.connection || navigator?.mozConnec
  * @description - Hook to track network status
  * @category Sensors
  *
+ * @browserapi navigator.connection https://developer.mozilla.org/en-US/docs/Web/API/Navigator/connection
+ *
  * @returns {UseNetworkReturn} An object containing the network status
  *
  * @example

diff --git a/packages/core/src/bundle/hooks/useOnline/useOnline.js b/packages/core/src/bundle/hooks/useOnline/useOnline.js
@@ -14,6 +14,8 @@ const subscribe = (callback) => {
  * @description - Hook that manages if the user is online
  * @category Sensors
  *
+ * @browserapi navigator.onLine https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine
+ *
  * @returns {boolean} A boolean indicating if the user is online
  *
  * @example

diff --git a/packages/core/src/bundle/hooks/useOrientation/useOrientation.js b/packages/core/src/bundle/hooks/useOrientation/useOrientation.js
@@ -4,6 +4,8 @@ import { useEffect, useState } from 'react';
  * @description - Hook that returns the current screen orientation
  * @category Browser
  *
+ * @browserapi window.screen.orientation https://developer.mozilla.org/en-US/docs/Web/API/Screen/orientation
+ *
  * @returns {UseOrientationReturn} An object containing the current screen orientation
  *
  * @example

diff --git a/packages/core/src/bundle/hooks/useOtpCredential/useOtpCredential.js b/packages/core/src/bundle/hooks/useOtpCredential/useOtpCredential.js
@@ -4,6 +4,8 @@ import { useRef, useState } from 'react';
  * @description - Hook that creates an otp credential
  * @category Browser
  *
+ * @browserapi navigator.credentials https://developer.mozilla.org/en-US/docs/Web/API/Navigator/credentials
+ *
  * @overload
  * @param {UseOtpCredentialCallback} callback The callback function to be invoked
  * @returns {UseOtpCredentialReturn}

diff --git a/packages/core/src/bundle/hooks/usePerformanceObserver/usePerformanceObserver.js b/packages/core/src/bundle/hooks/usePerformanceObserver/usePerformanceObserver.js
@@ -4,6 +4,8 @@ import { useEffect, useRef, useState } from 'react';
  * @description - Hook that allows you to observe performance entries
  * @category Sensors
  *
+ * @browserapi PerformanceObserver https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver
+ *
  * @param {UsePerformanceObserverOptions} options The options for the performance observer
  * @param {PerformanceObserverCallback} callback The function to handle performance entries
  * @returns {object} An object containing the observer's support status and methods to start and stop the observer

diff --git a/packages/core/src/bundle/hooks/usePermission/usePermission.js b/packages/core/src/bundle/hooks/usePermission/usePermission.js
@@ -5,6 +5,8 @@ import { useEvent } from '../useEvent/useEvent';
  *  @description - Hook that gives you the state of permission
  *  @category Browser
  *
+ *  @browserapi navigator.permissions https://developer.mozilla.org/en-US/docs/Web/API/Navigator/permissions
+ *
  *  @param {UsePermissionName} permissionDescriptorName - The permission name
  *  @param {boolean} [options.enabled=true] - Whether the permission is enabled
  *  @returns {UsePermissionReturn} An object containing the state and the supported status
@@ -13,8 +15,8 @@ import { useEvent } from '../useEvent/useEvent';
  *  const { state, supported, query } = usePermission('microphone');
  */
 export const usePermission = (permissionDescriptorName, options) => {
-    const [state, setState] = useState('prompt');
     const supported = typeof navigator !== 'undefined' && 'permissions' in navigator;
+    const [state, setState] = useState('prompt');
     const enabled = options?.enabled ?? true;
     const permissionDescriptor = { name: permissionDescriptorName };
     const query = useEvent(async () => {

diff --git a/packages/core/src/bundle/hooks/usePointerLock/usePointerLock.js b/packages/core/src/bundle/hooks/usePointerLock/usePointerLock.js
@@ -4,6 +4,8 @@ import { useEffect, useState } from 'react';
  * @description - Hook that provides reactive pointer lock
  * @category Sensors
  *
+ * @browserapi pointerLockElement https://developer.mozilla.org/en-US/docs/Web/API/Document/pointerLockElement
+ *
  * @returns {UsePointerLockReturn} An object containing the pointer lock element and functions to interact with the pointer lock
  *
  * @example

diff --git a/packages/core/src/bundle/hooks/usePreferredLanguages/usePreferredLanguages.js b/packages/core/src/bundle/hooks/usePreferredLanguages/usePreferredLanguages.js
@@ -12,6 +12,8 @@ const subscribe = (callback) => {
  * @description Hook that returns a browser preferred languages from navigator
  * @category Browser
  *
+ * @browserapi navigator.languages https://developer.mozilla.org/en-US/docs/Web/API/Navigator/languages
+ *
  * @returns {readonly string[]} An array of strings representing the user's preferred languages
  *
  * @example

diff --git a/packages/core/src/bundle/hooks/useRaf/useRaf.js b/packages/core/src/bundle/hooks/useRaf/useRaf.js
@@ -4,6 +4,8 @@ import { useEffect, useRef, useState } from 'react';
  * @description - Hook that defines the logic for raf callback
  * @category Utilities
  *
+ * @browserapi requestAnimationFrame https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame
+ *
  * @param {UseRafCallback} callback The callback to execute
  * @param {number} [options.delay] The delay between each frame in milliseconds
  * @param {boolean} [options.enabled=true] Whether the callback should be enabled

diff --git a/packages/core/src/bundle/hooks/useResizeObserver/useResizeObserver.js b/packages/core/src/bundle/hooks/useResizeObserver/useResizeObserver.js
@@ -6,6 +6,8 @@ import { useRefState } from '../useRefState/useRefState';
  *  @description - Hook that gives you resize observer state
  *  @category Browser
  *
+ *  @browserapi ResizeObserver https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver
+ *
  *  @overload
  *  @template Target The target element
  *  @param {boolean} [options.enabled=true] The IntersectionObserver options

diff --git a/packages/core/src/bundle/hooks/useScreenOrientation/useScreenOrientation.js b/packages/core/src/bundle/hooks/useScreenOrientation/useScreenOrientation.js
@@ -4,6 +4,8 @@ import { useEffect, useState } from 'react';
  * @description - Hook that provides the current screen orientation
  * @category Sensors
  *
+ * @browserapi screen.orientation https://developer.mozilla.org/en-US/docs/Web/API/Screen/orientation
+ *
  * @returns {useScreenOrientationReturn} The current screen orientation
  *
  * @example

diff --git a/packages/core/src/bundle/hooks/useSessionStorage/useSessionStorage.js b/packages/core/src/bundle/hooks/useSessionStorage/useSessionStorage.js
@@ -4,6 +4,8 @@ import { useStorage } from '../useStorage/useStorage';
  * @description - Hook that manages session storage value
  * @category Browser
  *
+ * @browserapi sessionStorage https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage
+ *
  * @template Value The type of the value
  * @param {string} key The key of the storage
  * @param {UseStorageInitialValue<Value>} [initialValue] The initial value of the storage

diff --git a/packages/core/src/bundle/hooks/useTextSelection/useTextSelection.js b/packages/core/src/bundle/hooks/useTextSelection/useTextSelection.js
@@ -9,6 +9,8 @@ export const getRangesSelection = (selection) => {
  * @description - Hook that manages the text selection
  * @category Sensors
  *
+ * @browserapi document.getSelection https://developer.mozilla.org/en-US/docs/Web/API/Document/getSelection
+ *
  * @returns {UseTextSelectionReturn} An object containing the current text selection
  *
  * @example

diff --git a/packages/core/src/bundle/hooks/useThrottleCallback/useThrottleCallback.js b/packages/core/src/bundle/hooks/useThrottleCallback/useThrottleCallback.js
@@ -3,7 +3,7 @@ import { throttle } from '@/utils/helpers';
 import { useEvent } from '../useEvent/useEvent';
 /**
  * @name useThrottleCallback
- * @description - Hook that creates a throttled callback and returns a stable reference of it
+ * @description - Hook that creates a throttled callback
  * @category Utilities
  *
  * @template Params The type of the params

diff --git a/packages/core/src/bundle/hooks/useThrottleValue/useThrottleValue.js b/packages/core/src/bundle/hooks/useThrottleValue/useThrottleValue.js
@@ -2,7 +2,7 @@ import { useEffect, useRef, useState } from 'react';
 import { useThrottleCallback } from '../useThrottleCallback/useThrottleCallback';
 /**
  * @name useThrottleValue
- * @description - Hook that creates a throttled value and returns a stable reference of it
+ * @description - Hook that creates a throttled value
  * @category Utilities
  *
  * @template Value The type of the value

diff --git a/packages/core/src/bundle/hooks/useVibrate/useVibrate.js b/packages/core/src/bundle/hooks/useVibrate/useVibrate.js
@@ -4,6 +4,8 @@ import { useEffect, useRef, useState } from 'react';
  * @description - Hook that provides vibrate api
  * @category Browser
  *
+ * @browserapi navigator.vibrate https://developer.mozilla.org/en-US/docs/Web/API/Navigator/vibrate
+ *
  * @overload
  * @param {UseVibratePattern} options.pattern The pattern for vibration
  * @param {number} [options.interval=0] Time in milliseconds between vibrations