@oneplatformdev/ui 0.1.0-5 → 0.1.0-8

package/node_modules/@oneplatformdev/hooks/src/useMediaQuery/useMediaQuery.ts

@@ -0,0 +1,83 @@
+import { useState } from 'react'
+
+import { useIsomorphicLayoutEffect } from '../useIsomorphicLayoutEffect'
+
+/** Hook options. */
+type UseMediaQueryOptions = {
+  /**
+   * The default value to return if the hook is being run on the server.
+   * @default false
+   */
+  defaultValue?: boolean
+  /**
+   * If `true` (default), the hook will initialize reading the media query. In SSR, you should set it to `false`, returning `options.defaultValue` or `false` initially.
+   * @default true
+   */
+  initializeWithValue?: boolean
+}
+
+const IS_SERVER = typeof window === 'undefined'
+
+/**
+ * Custom hook that tracks the state of a media query using the [`Match Media API`](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia).
+ * @param {string} query - The media query to track.
+ * @param {?UseMediaQueryOptions} [options] - The options for customizing the behavior of the hook (optional).
+ * @returns {boolean} The current state of the media query (true if the query matches, false otherwise).
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-media-query)
+ * @example
+ * ```tsx
+ * const isSmallScreen = useMediaQuery('(max-width: 600px)');
+ * // Use `isSmallScreen` to conditionally apply styles or logic based on the screen size.
+ * ```
+ */
+export function useMediaQuery(
+  query: string,
+  {
+    defaultValue = false,
+    initializeWithValue = true,
+  }: UseMediaQueryOptions = {},
+): boolean {
+  const getMatches = (query: string): boolean => {
+    if (IS_SERVER) {
+      return defaultValue
+    }
+    return window.matchMedia(query).matches
+  }
+
+  const [matches, setMatches] = useState<boolean>(() => {
+    if (initializeWithValue) {
+      return getMatches(query)
+    }
+    return defaultValue
+  })
+
+  // Handles the change event of the media query.
+  function handleChange() {
+    setMatches(getMatches(query))
+  }
+
+  useIsomorphicLayoutEffect(() => {
+    const matchMedia = window.matchMedia(query)
+
+    // Triggered at the first client-side load and if query changes
+    handleChange()
+
+    // Use deprecated `addListener` and `removeListener` to support Safari < 14 (#135)
+    if (matchMedia.addListener) {
+      matchMedia.addListener(handleChange)
+    } else {
+      matchMedia.addEventListener('change', handleChange)
+    }
+
+    return () => {
+      if (matchMedia.removeListener) {
+        matchMedia.removeListener(handleChange)
+      } else {
+        matchMedia.removeEventListener('change', handleChange)
+      }
+    }
+  }, [query])
+
+  return matches
+}

package/node_modules/@oneplatformdev/hooks/src/useOnClickOutside/index.ts

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

package/node_modules/@oneplatformdev/hooks/src/useOnClickOutside/useOnClickOutside.ts

@@ -0,0 +1,61 @@
+import type { RefObject } from 'react'
+
+import { useEventListener } from '../useEventListener'
+
+/** Supported event types. */
+type EventType =
+  | 'mousedown'
+  | 'mouseup'
+  | 'touchstart'
+  | 'touchend'
+  | 'focusin'
+  | 'focusout'
+
+/**
+ * Custom hook that handles clicks outside a specified element.
+ * @template T - The type of the element's reference.
+ * @param {RefObject<T> | RefObject<T>[]} ref - The React ref object(s) representing the element(s) to watch for outside clicks.
+ * @param {(event: MouseEvent | TouchEvent | FocusEvent) => void} handler - The callback function to be executed when a click outside the element occurs.
+ * @param {EventType} [eventType] - The mouse event type to listen for (optional, default is 'mousedown').
+ * @param {?AddEventListenerOptions} [eventListenerOptions] - The options object to be passed to the `addEventListener` method (optional).
+ * @returns {void}
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-on-click-outside)
+ * @example
+ * ```tsx
+ * const containerRef = useRef(null);
+ * useOnClickOutside([containerRef], () => {
+ *   // Handle clicks outside the container.
+ * });
+ * ```
+ */
+export function useOnClickOutside<T extends HTMLElement = HTMLElement>(
+  ref: RefObject<T> | RefObject<T>[],
+  handler: (event: MouseEvent | TouchEvent | FocusEvent) => void,
+  eventType: EventType = 'mousedown',
+  eventListenerOptions: AddEventListenerOptions = {},
+): void {
+  useEventListener(
+    eventType,
+    event => {
+      const target = event.target as Node
+
+      // Do nothing if the target is not connected element with document
+      if (!target || !target.isConnected) {
+        return
+      }
+
+      const isOutside = Array.isArray(ref)
+        ? ref
+            .filter(r => Boolean(r.current))
+            .every(r => r.current && !r.current.contains(target))
+        : ref.current && !ref.current.contains(target)
+
+      if (isOutside) {
+        handler(event)
+      }
+    },
+    undefined,
+    eventListenerOptions,
+  )
+}

package/node_modules/@oneplatformdev/hooks/src/useQueryString/index.ts

@@ -0,0 +1 @@
+export * from "./useQueryString"

package/node_modules/@oneplatformdev/hooks/src/useQueryString/useQueryString.ts

@@ -0,0 +1,26 @@
+import { useCallback } from 'react';
+
+type Nullable<T> = {
+    [P in keyof T]: T[P] | null;
+  };
+type QueryParamsValue = Nullable<string | number | boolean | undefined>
+type QueryParams = Record<string, QueryParamsValue>
+
+export const useQueryString = (searchParams: URLSearchParams) => {
+
+    const createQueryString = useCallback((baseUrl: string, params: QueryParams) => {
+        const newSearchParams = new URLSearchParams(searchParams?.toString());
+
+        Object.entries(params).forEach(([key, value]) => {
+            if (value === null || value === "" || value === undefined) {
+                newSearchParams.delete(key);
+            } else {
+                newSearchParams.set(key, String(value));
+            }
+        });
+
+        return `${baseUrl}?${newSearchParams.toString()}`;
+    }, [searchParams],);
+
+    return { createQueryString, };
+};

package/node_modules/@oneplatformdev/hooks/src/useReadLocalStorage/index.ts

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

package/node_modules/@oneplatformdev/hooks/src/useReadLocalStorage/useReadLocalStorage.ts

@@ -0,0 +1,122 @@
+import { useCallback, useEffect, useState } from 'react'
+
+import { useEventListener } from '../useEventListener'
+
+const IS_SERVER = typeof window === 'undefined'
+
+/**
+ * Represents the type for the options available when reading from local storage.
+ * @template T - The type of the stored value.
+ */
+type Options<T, InitializeWithValue extends boolean | undefined> = {
+  /** Custom deserializer function to convert the stored string value to the desired type (optional). */
+  deserializer?: (value: string) => T
+  /** If `true` (default), the hook will initialize reading the local storage. In SSR, you should set it to `false`, returning `undefined` initially. */
+  initializeWithValue: InitializeWithValue
+}
+
+// SSR version
+export function useReadLocalStorage<T>(
+  key: string,
+  options: Options<T, false>,
+): T | null | undefined
+// CSR version
+export function useReadLocalStorage<T>(
+  key: string,
+  options?: Partial<Options<T, true>>,
+): T | null
+/**
+ * Custom hook that reads a value from [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage), closely related to [`useLocalStorage()`](https://usehooks-ts.com/react-hook/use-local-storage).
+ * @template T - The type of the stored value.
+ * @param {string} key - The key associated with the value in local storage.
+ * @param {Options<T>} [options] - Additional options for reading the value (optional).
+ * @returns {T | null | undefined} The stored value, or null if the key is not present or an error occurs.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-read-local-storage)
+ * @example
+ * ```tsx
+ * const storedData = useReadLocalStorage('myKey');
+ * // Access the stored data from local storage.
+ * ```
+ */
+export function useReadLocalStorage<T>(
+  key: string,
+  options: Partial<Options<T, boolean>> = {},
+): T | null | undefined {
+  let { initializeWithValue = true } = options
+  if (IS_SERVER) {
+    initializeWithValue = false
+  }
+
+  const deserializer = useCallback<(value: string) => T | null>(
+    value => {
+      if (options.deserializer) {
+        return options.deserializer(value)
+      }
+      // Support 'undefined' as a value
+      if (value === 'undefined') {
+        return undefined as unknown as T
+      }
+
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(value)
+      } catch (error) {
+        console.error('Error parsing JSON:', error)
+        return null
+      }
+
+      return parsed as T
+    },
+    [options],
+  )
+
+  // Get from local storage then
+  // parse stored json or return initialValue
+  const readValue = useCallback((): T | null => {
+    // Prevent build error "window is undefined" but keep keep working
+    if (IS_SERVER) {
+      return null
+    }
+
+    try {
+      const raw = window.localStorage.getItem(key)
+      return raw ? deserializer(raw) : null
+    } catch (error) {
+      console.warn(`Error reading localStorage key “${key}”:`, error)
+      return null
+    }
+  }, [key, deserializer])
+
+  const [storedValue, setStoredValue] = useState(() => {
+    if (initializeWithValue) {
+      return readValue()
+    }
+    return undefined
+  })
+
+  // Listen if localStorage changes
+  useEffect(() => {
+    setStoredValue(readValue())
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key])
+
+  const handleStorageChange = useCallback(
+    (event: StorageEvent | CustomEvent) => {
+      if ((event as StorageEvent).key && (event as StorageEvent).key !== key) {
+        return
+      }
+      setStoredValue(readValue())
+    },
+    [key, readValue],
+  )
+
+  // this only works for other documents, not the current one
+  useEventListener('storage', handleStorageChange)
+
+  // this is a custom event, triggered in writeValueToLocalStorage
+  // See: useLocalStorage()
+  useEventListener('local-storage', handleStorageChange)
+
+  return storedValue
+}

package/node_modules/@oneplatformdev/hooks/src/useResizeObserver/index.ts

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

package/node_modules/@oneplatformdev/hooks/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/node_modules/@oneplatformdev/hooks/src/useScreen/index.ts

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

package/node_modules/@oneplatformdev/hooks/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/node_modules/@oneplatformdev/hooks/src/useScript/index.ts

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

package/node_modules/@oneplatformdev/hooks/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/node_modules/@oneplatformdev/hooks/src/useScrollLock/index.ts

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