@oneplatformdev/hooks 0.1.0-7 → 0.1.0-9

package/src/useResizeObserver/useResizeObserver.ts

@@ -0,0 +1,131 @@
+import { useEffect, useRef, useState } from 'react'
+
+import type { RefObject } from 'react'
+
+import { useIsMounted } from '../useIsMounted'
+
+/** The size of the observed element. */
+type Size = {
+  /** The width of the observed element. */
+  width: number | undefined
+  /** The height of the observed element. */
+  height: number | undefined
+}
+
+/** The options for the ResizeObserver. */
+type UseResizeObserverOptions<T extends HTMLElement = HTMLElement> = {
+  /** The ref of the element to observe. */
+  ref: RefObject<T>
+  /**
+   * When using `onResize`, the hook doesn't re-render on element size changes; it delegates handling to the provided callback.
+   * @default undefined
+   */
+  onResize?: (size: Size) => void
+  /**
+   * The box model to use for the ResizeObserver.
+   * @default 'content-box'
+   */
+  box?: 'border-box' | 'content-box' | 'device-pixel-content-box'
+}
+
+const initialSize: Size = {
+  width: undefined,
+  height: undefined,
+}
+
+/**
+ * Custom hook that observes the size of an element using the [`ResizeObserver API`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver).
+ * @template T - The type of the element to observe.
+ * @param {UseResizeObserverOptions<T>} options - The options for the ResizeObserver.
+ * @returns {Size} - The size of the observed element.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-resize-observer)
+ * @example
+ * ```tsx
+ * const myRef = useRef(null);
+ * const { width = 0, height = 0 } = useResizeObserver({
+ *   ref: myRef,
+ *   box: 'content-box',
+ * });
+ *
+ * <div ref={myRef}>Hello, world!</div>
+ * ```
+ */
+export function useResizeObserver<T extends HTMLElement = HTMLElement>(
+  options: UseResizeObserverOptions<T>,
+): Size {
+  const { ref, box = 'content-box' } = options
+  const [{ width, height }, setSize] = useState<Size>(initialSize)
+  const isMounted = useIsMounted()
+  const previousSize = useRef<Size>({ ...initialSize })
+  const onResize = useRef<((size: Size) => void) | undefined>(undefined)
+  onResize.current = options.onResize
+
+  useEffect(() => {
+    if (!ref.current) return
+
+    if (typeof window === 'undefined' || !('ResizeObserver' in window)) return
+
+    const observer = new ResizeObserver(([entry]) => {
+      const boxProp =
+        box === 'border-box'
+          ? 'borderBoxSize'
+          : box === 'device-pixel-content-box'
+            ? 'devicePixelContentBoxSize'
+            : 'contentBoxSize'
+
+      const newWidth = extractSize(entry, boxProp, 'inlineSize')
+      const newHeight = extractSize(entry, boxProp, 'blockSize')
+
+      const hasChanged =
+        previousSize.current.width !== newWidth ||
+        previousSize.current.height !== newHeight
+
+      if (hasChanged) {
+        const newSize: Size = { width: newWidth, height: newHeight }
+        previousSize.current.width = newWidth
+        previousSize.current.height = newHeight
+
+        if (onResize.current) {
+          onResize.current(newSize)
+        } else {
+          if (isMounted()) {
+            setSize(newSize)
+          }
+        }
+      }
+    })
+
+    observer.observe(ref.current, { box })
+
+    return () => {
+      observer.disconnect()
+    }
+  }, [box, ref, isMounted])
+
+  return { width, height }
+}
+
+/** @private */
+type BoxSizesKey = keyof Pick<
+  ResizeObserverEntry,
+  'borderBoxSize' | 'contentBoxSize' | 'devicePixelContentBoxSize'
+>
+
+function extractSize(
+  entry: ResizeObserverEntry,
+  box: BoxSizesKey,
+  sizeType: keyof ResizeObserverSize,
+): number | undefined {
+  if (!entry[box]) {
+    if (box === 'contentBoxSize') {
+      return entry.contentRect[sizeType === 'inlineSize' ? 'width' : 'height']
+    }
+    return undefined
+  }
+
+  return Array.isArray(entry[box])
+    ? entry[box][0][sizeType]
+    : // @ts-ignore Support Firefox's non-standard behavior
+      (entry[box][sizeType] as number)
+}

package/src/useScreen/index.ts

@@ -0,0 +1 @@
+export * from './useScreen'

package/src/useScreen/useScreen.ts

@@ -0,0 +1,106 @@
+import { useState } from 'react'
+
+import { useDebounceCallback } from '../useDebounceCallback'
+import { useEventListener } from '../useEventListener'
+import { useIsomorphicLayoutEffect } from '../useIsomorphicLayoutEffect'
+
+/**
+ * The hooks options.
+ * @template InitializeWithValue - If `true` (default), the hook will initialize reading the screen dimensions. In SSR, you should set it to `false`, returning `undefined` initially.
+ */
+type UseScreenOptions<InitializeWithValue extends boolean | undefined> = {
+  /**
+   * If `true` (default), the hook will initialize reading the screen dimensions. In SSR, you should set it to `false`, returning `undefined` initially.
+   * @default true
+   */
+  initializeWithValue: InitializeWithValue
+  /**
+   * The delay in milliseconds before the state is updated (disabled by default for retro-compatibility).
+   * @default undefined
+   */
+  debounceDelay?: number
+}
+
+const IS_SERVER = typeof window === 'undefined'
+
+// SSR version of useScreen.
+export function useScreen(options: UseScreenOptions<false>): Screen | undefined
+// CSR version of useScreen.
+export function useScreen(options?: Partial<UseScreenOptions<true>>): Screen
+/**
+ * Custom hook that tracks the [`screen`](https://developer.mozilla.org/en-US/docs/Web/API/Window/screen) dimensions and properties.
+ * @param {?UseScreenOptions} [options] - The options for customizing the behavior of the hook (optional).
+ * @returns {Screen | undefined} The current `Screen` object representing the screen dimensions and properties, or `undefined` if not available.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-screen)
+ * @example
+ * ```tsx
+ * const currentScreen = useScreen();
+ * // Access properties of the current screen, such as width and height.
+ * ```
+ */
+export function useScreen(
+  options: Partial<UseScreenOptions<boolean>> = {},
+): Screen | undefined {
+  let { initializeWithValue = true } = options
+  if (IS_SERVER) {
+    initializeWithValue = false
+  }
+
+  const readScreen = () => {
+    if (IS_SERVER) {
+      return undefined
+    }
+    return window.screen
+  }
+
+  const [screen, setScreen] = useState<Screen | undefined>(() => {
+    if (initializeWithValue) {
+      return readScreen()
+    }
+    return undefined
+  })
+
+  const debouncedSetScreen = useDebounceCallback(
+    setScreen,
+    options.debounceDelay,
+  )
+
+  // Handles the resize event of the window.
+  function handleSize() {
+    const newScreen = readScreen()
+    const setSize = options.debounceDelay ? debouncedSetScreen : setScreen
+
+    if (newScreen) {
+      // Create a shallow clone to trigger a re-render (#280).
+      const {
+        width,
+        height,
+        availHeight,
+        availWidth,
+        colorDepth,
+        orientation,
+        pixelDepth,
+      } = newScreen
+
+      setSize({
+        width,
+        height,
+        availHeight,
+        availWidth,
+        colorDepth,
+        orientation,
+        pixelDepth,
+      })
+    }
+  }
+
+  useEventListener('resize', handleSize)
+
+  // Set size at the first client-side load
+  useIsomorphicLayoutEffect(() => {
+    handleSize()
+  }, [])
+
+  return screen
+}

package/src/useScript/index.ts

@@ -0,0 +1 @@
+export * from './useScript'

package/src/useScript/useScript.ts

@@ -0,0 +1,142 @@
+import { useEffect, useState } from 'react'
+
+/** Script loading status. */
+type UseScriptStatus = 'idle' | 'loading' | 'ready' | 'error'
+
+/** Hook options. */
+type UseScriptOptions = {
+  /** If `true`, prevents the script from being loaded (optional). */
+  shouldPreventLoad?: boolean
+  /** If `true`, removes the script from the DOM when the component unmounts (optional). */
+  removeOnUnmount?: boolean
+  /** Script's `id` (optional). */
+  id?: string
+}
+
+// Cached script statuses
+const cachedScriptStatuses = new Map<string, UseScriptStatus | undefined>()
+
+/**
+ * Gets the script element with the specified source URL.
+ * @param {string} src - The source URL of the script to get.
+ * @returns {{ node: HTMLScriptElement | null, status: UseScriptStatus | undefined }} The script element and its loading status.
+ * @public
+ * @example
+ * ```tsx
+ * const script = getScriptNode(src);
+ * ```
+ */
+function getScriptNode(src: string) {
+  const node: HTMLScriptElement | null = document.querySelector(
+    `script[src="${src}"]`,
+  )
+  const status = node?.getAttribute('data-status') as
+    | UseScriptStatus
+    | undefined
+
+  return {
+    node,
+    status,
+  }
+}
+
+/**
+ * Custom hook that dynamically loads scripts and tracking their loading status.
+ * @param {string | null} src - The source URL of the script to load. Set to `null` or omit to prevent loading (optional).
+ * @param {UseScriptOptions} [options] - Additional options for controlling script loading (optional).
+ * @returns {UseScriptStatus} The status of the script loading, which can be one of 'idle', 'loading', 'ready', or 'error'.
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-script)
+ * @example
+ * const scriptStatus = useScript('https://example.com/script.js', { removeOnUnmount: true });
+ * // Access the status of the script loading (e.g., 'loading', 'ready', 'error').
+ */
+export function useScript(
+  src: string | null,
+  options?: UseScriptOptions,
+): UseScriptStatus {
+  const [status, setStatus] = useState<UseScriptStatus>(() => {
+    if (!src || options?.shouldPreventLoad) {
+      return 'idle'
+    }
+
+    if (typeof window === 'undefined') {
+      // SSR Handling - always return 'loading'
+      return 'loading'
+    }
+
+    return cachedScriptStatuses.get(src) ?? 'loading'
+  })
+
+  useEffect(() => {
+    if (!src || options?.shouldPreventLoad) {
+      return
+    }
+
+    const cachedScriptStatus = cachedScriptStatuses.get(src)
+    if (cachedScriptStatus === 'ready' || cachedScriptStatus === 'error') {
+      // If the script is already cached, set its status immediately
+      setStatus(cachedScriptStatus)
+      return
+    }
+
+    // Fetch existing script element by src
+    // It may have been added by another instance of this hook
+    const script = getScriptNode(src)
+    let scriptNode = script.node
+
+    if (!scriptNode) {
+      // Create script element and add it to document body
+      scriptNode = document.createElement('script')
+      scriptNode.src = src
+      scriptNode.async = true
+      if (options?.id) {
+        scriptNode.id = options.id
+      }
+      scriptNode.setAttribute('data-status', 'loading')
+      document.body.appendChild(scriptNode)
+
+      // Store status in attribute on script
+      // This can be read by other instances of this hook
+      const setAttributeFromEvent = (event: Event) => {
+        const scriptStatus: UseScriptStatus =
+          event.type === 'load' ? 'ready' : 'error'
+
+        scriptNode?.setAttribute('data-status', scriptStatus)
+      }
+
+      scriptNode.addEventListener('load', setAttributeFromEvent)
+      scriptNode.addEventListener('error', setAttributeFromEvent)
+    } else {
+      // Grab existing script status from attribute and set to state.
+      setStatus(script.status ?? cachedScriptStatus ?? 'loading')
+    }
+
+    // Script event handler to update status in state
+    // Note: Even if the script already exists we still need to add
+    // event handlers to update the state for *this* hook instance.
+    const setStateFromEvent = (event: Event) => {
+      const newStatus = event.type === 'load' ? 'ready' : 'error'
+      setStatus(newStatus)
+      cachedScriptStatuses.set(src, newStatus)
+    }
+
+    // Add event listeners
+    scriptNode.addEventListener('load', setStateFromEvent)
+    scriptNode.addEventListener('error', setStateFromEvent)
+
+    // Remove event listeners on cleanup
+    return () => {
+      if (scriptNode) {
+        scriptNode.removeEventListener('load', setStateFromEvent)
+        scriptNode.removeEventListener('error', setStateFromEvent)
+      }
+
+      if (scriptNode && options?.removeOnUnmount) {
+        scriptNode.remove()
+        cachedScriptStatuses.delete(src)
+      }
+    }
+  }, [src, options?.shouldPreventLoad, options?.removeOnUnmount, options?.id])
+
+  return status
+}

package/src/useScrollLock/index.ts

@@ -0,0 +1 @@
+export * from './useScrollLock'

package/src/useScrollLock/useScrollLock.ts

@@ -0,0 +1,141 @@
+import { useRef, useState } from 'react'
+
+import { useIsomorphicLayoutEffect } from '../useIsomorphicLayoutEffect'
+
+/** Hook options. */
+type UseScrollLockOptions = {
+  /**
+   * Whether to lock the scroll initially.
+   * @default true
+   */
+  autoLock?: boolean
+  /**
+   * The target element to lock the scroll (default is the body element).
+   * @default document.body
+   */
+  lockTarget?: HTMLElement | string
+  /**
+   * Whether to prevent width reflow when locking the scroll.
+   * @default true
+   */
+  widthReflow?: boolean
+}
+
+/** Hook return type. */
+type UseScrollLockReturn = {
+  /** Whether the scroll is locked. */
+  isLocked: boolean
+  /** Lock the scroll. */
+  lock: () => void
+  /** Unlock the scroll. */
+  unlock: () => void
+}
+
+type OriginalStyle = {
+  overflow: CSSStyleDeclaration['overflow']
+  paddingRight: CSSStyleDeclaration['paddingRight']
+}
+
+const IS_SERVER = typeof window === 'undefined'
+
+/**
+ * A custom hook that locks and unlocks scroll.
+ * @param {UseScrollLockOptions} [options] - Options to configure the hook, by default it will lock the scroll automatically.
+ * @returns {UseScrollLockReturn} - An object containing the lock and unlock functions.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-scroll-lock)
+ * @example
+ * ```tsx
+ * // Lock the scroll when the modal is mounted, and unlock it when it's unmounted
+ * useScrollLock()
+ * ```
+ * @example
+ * ```tsx
+ * // Manually lock and unlock the scroll
+ * const { lock, unlock } = useScrollLock({ autoLock: false })
+ *
+ * return (
+ *  <div>
+ *   <button onClick={lock}>Lock</button>
+ *   <button onClick={unlock}>Unlock</button>
+ *  </div>
+ * )
+ * ```
+ */
+export function useScrollLock(
+  options: UseScrollLockOptions = {},
+): UseScrollLockReturn {
+  const { autoLock = true, lockTarget, widthReflow = true } = options
+  const [isLocked, setIsLocked] = useState(false)
+  const target = useRef<HTMLElement | null>(null)
+  const originalStyle = useRef<OriginalStyle | null>(null)
+
+  const lock = () => {
+    if (target.current) {
+      const { overflow, paddingRight } = target.current.style
+
+      // Save the original styles
+      originalStyle.current = { overflow, paddingRight }
+
+      // Prevent width reflow
+      if (widthReflow) {
+        // Use window inner width if body is the target as global scrollbar isn't part of the document
+        const offsetWidth =
+          target.current === document.body
+            ? window.innerWidth
+            : target.current.offsetWidth
+        // Get current computed padding right in pixels
+        const currentPaddingRight =
+          parseInt(window.getComputedStyle(target.current).paddingRight, 10) ||
+          0
+
+        const scrollbarWidth = offsetWidth - target.current.scrollWidth
+        target.current.style.paddingRight = `${scrollbarWidth + currentPaddingRight}px`
+      }
+
+      // Lock the scroll
+      target.current.style.overflow = 'hidden'
+
+      setIsLocked(true)
+    }
+  }
+
+  const unlock = () => {
+    if (target.current && originalStyle.current) {
+      target.current.style.overflow = originalStyle.current.overflow
+
+      // Only reset padding right if we changed it
+      if (widthReflow) {
+        target.current.style.paddingRight = originalStyle.current.paddingRight
+      }
+    }
+
+    setIsLocked(false)
+  }
+
+  useIsomorphicLayoutEffect(() => {
+    if (IS_SERVER) return
+
+    if (lockTarget) {
+      target.current =
+        typeof lockTarget === 'string'
+          ? document.querySelector(lockTarget)
+          : lockTarget
+    }
+
+    if (!target.current) {
+      target.current = document.body
+    }
+
+    if (autoLock) {
+      lock()
+    }
+
+    return () => {
+      unlock()
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [autoLock, lockTarget, widthReflow])
+
+  return { isLocked, lock, unlock }
+}

package/src/useSessionStorage/index.ts

@@ -0,0 +1 @@
+export * from './useSessionStorage'