@oneplatformdev/ui 0.1.0-5 → 0.1.0-8

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

@@ -0,0 +1,186 @@
+import { useEffect, useRef, useState } from 'react'
+
+/** The hook internal state. */
+type State = {
+  /** A boolean indicating if the element is intersecting. */
+  isIntersecting: boolean
+  /** The intersection observer entry. */
+  entry?: IntersectionObserverEntry
+}
+
+/** Represents the options for configuring the Intersection Observer. */
+type UseIntersectionObserverOptions = {
+  /**
+   * The element that is used as the viewport for checking visibility of the target.
+   * @default null
+   */
+  root?: Element | Document | null
+  /**
+   * A margin around the root.
+   * @default '0%'
+   */
+  rootMargin?: string
+  /**
+   * A threshold indicating the percentage of the target's visibility needed to trigger the callback.
+   * @default 0
+   */
+  threshold?: number | number[]
+  /**
+   * If true, freezes the intersection state once the element becomes visible.
+   * @default false
+   */
+  freezeOnceVisible?: boolean
+  /**
+   * A callback function to be invoked when the intersection state changes.
+   * @param {boolean} isIntersecting - A boolean indicating if the element is intersecting.
+   * @param {IntersectionObserverEntry} entry - The intersection observer Entry.
+   * @default undefined
+   */
+  onChange?: (isIntersecting: boolean, entry: IntersectionObserverEntry) => void
+  /**
+   * The initial state of the intersection.
+   * @default false
+   */
+  initialIsIntersecting?: boolean
+}
+
+/**
+ * The return type of the useIntersectionObserver hook.
+ *
+ * Supports both tuple and object destructing.
+ * @param {(node: Element | null) => void} ref - The ref callback function.
+ * @param {boolean} isIntersecting - A boolean indicating if the element is intersecting.
+ * @param {IntersectionObserverEntry | undefined} entry - The intersection observer Entry.
+ */
+type IntersectionReturn = [
+  (node?: Element | null) => void,
+  boolean,
+  IntersectionObserverEntry | undefined,
+] & {
+  ref: (node?: Element | null) => void
+  isIntersecting: boolean
+  entry?: IntersectionObserverEntry
+}
+
+/**
+ * Custom hook that tracks the intersection of a DOM element with its containing element or the viewport using the [`Intersection Observer API`](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
+ * @param {UseIntersectionObserverOptions} options - The options for the Intersection Observer.
+ * @returns {IntersectionReturn} The ref callback, a boolean indicating if the element is intersecting, and the intersection observer entry.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-intersection-observer)
+ * @example
+ * ```tsx
+ * // Example 1
+ * const [ref, isIntersecting, entry] = useIntersectionObserver({ threshold: 0.5 });
+ * ```
+ *
+ * ```tsx
+ * // Example 2
+ * const { ref, isIntersecting, entry } = useIntersectionObserver({ threshold: 0.5 });
+ * ```
+ */
+export function useIntersectionObserver({
+  threshold = 0,
+  root = null,
+  rootMargin = '0%',
+  freezeOnceVisible = false,
+  initialIsIntersecting = false,
+  onChange,
+}: UseIntersectionObserverOptions = {}): IntersectionReturn {
+  const [ref, setRef] = useState<Element | null>(null)
+
+  const [state, setState] = useState<State>(() => ({
+    isIntersecting: initialIsIntersecting,
+    entry: undefined,
+  }))
+
+  const callbackRef = useRef<UseIntersectionObserverOptions['onChange']>(null)
+
+  callbackRef.current = onChange
+
+  const frozen = state.entry?.isIntersecting && freezeOnceVisible
+
+  useEffect(() => {
+    // Ensure we have a ref to observe
+    if (!ref) return
+
+    // Ensure the browser supports the Intersection Observer API
+    if (!('IntersectionObserver' in window)) return
+
+    // Skip if frozen
+    if (frozen) return
+
+    let unobserve: (() => void) | undefined
+
+    const observer = new IntersectionObserver(
+      (entries: IntersectionObserverEntry[]): void => {
+        const thresholds = Array.isArray(observer.thresholds)
+          ? observer.thresholds
+          : [observer.thresholds]
+
+        entries.forEach(entry => {
+          const isIntersecting =
+            entry.isIntersecting &&
+            thresholds.some(threshold => entry.intersectionRatio >= threshold)
+
+          setState({ isIntersecting, entry })
+
+          if (callbackRef.current) {
+            callbackRef.current(isIntersecting, entry)
+          }
+
+          if (isIntersecting && freezeOnceVisible && unobserve) {
+            unobserve()
+            unobserve = undefined
+          }
+        })
+      },
+      { threshold, root, rootMargin },
+    )
+
+    observer.observe(ref)
+
+    return () => {
+      observer.disconnect()
+    }
+
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    ref,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    JSON.stringify(threshold),
+    root,
+    rootMargin,
+    frozen,
+    freezeOnceVisible,
+  ])
+
+  // ensures that if the observed element changes, the intersection observer is reinitialized
+  const prevRef = useRef<Element | null>(null)
+
+  useEffect(() => {
+    if (
+      !ref &&
+      state.entry?.target &&
+      !freezeOnceVisible &&
+      !frozen &&
+      prevRef.current !== state.entry.target
+    ) {
+      prevRef.current = state.entry.target
+      setState({ isIntersecting: initialIsIntersecting, entry: undefined })
+    }
+  }, [ref, state.entry, freezeOnceVisible, frozen, initialIsIntersecting])
+
+  const result = [
+    setRef,
+    !!state.isIntersecting,
+    state.entry,
+  ] as IntersectionReturn
+
+  // Support object destructuring, by adding the specific values.
+  result.ref = result[0]
+  result.isIntersecting = result[1]
+  result.entry = result[2]
+
+  return result
+}

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

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

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

@@ -0,0 +1,43 @@
+import { useEffect, useRef } from 'react'
+
+import { useIsomorphicLayoutEffect } from '../useIsomorphicLayoutEffect'
+
+/**
+ * Custom hook that creates an interval that invokes a callback function at a specified delay using the [`setInterval API`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setInterval).
+ * @param {() => void} callback - The function to be invoked at each interval.
+ * @param {number | null} delay - The time, in milliseconds, between each invocation of the callback. Use `null` to clear the interval.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-interval)
+ * @example
+ * ```tsx
+ * const handleInterval = () => {
+ *   // Code to be executed at each interval
+ * };
+ * useInterval(handleInterval, 1000);
+ * ```
+ */
+export function useInterval(callback: () => void, delay: number | null) {
+  const savedCallback = useRef(callback)
+
+  // Remember the latest callback if it changes.
+  useIsomorphicLayoutEffect(() => {
+    savedCallback.current = callback
+  }, [callback])
+
+  // Set up the interval.
+  useEffect(() => {
+    // Don't schedule if no delay is specified.
+    // Note: 0 is a valid value for delay.
+    if (delay === null) {
+      return
+    }
+
+    const id = setInterval(() => {
+      savedCallback.current()
+    }, delay)
+
+    return () => {
+      clearInterval(id)
+    }
+  }, [delay])
+}

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

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

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

@@ -0,0 +1,22 @@
+import { useEffect, useState } from 'react'
+
+/**
+ * Custom hook that determines if the code is running on the client side (in the browser).
+ * @returns {boolean} A boolean value indicating whether the code is running on the client side.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-is-client)
+ * @example
+ * ```tsx
+ * const isClient = useIsClient();
+ * // Use isClient to conditionally render or execute code specific to the client side.
+ * ```
+ */
+export function useIsClient() {
+  const [isClient, setClient] = useState(false)
+
+  useEffect(() => {
+    setClient(true)
+  }, [])
+
+  return isClient
+}

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

@@ -0,0 +1,2 @@
+export * from './useIsMobile'
+export type * from './types'

package/node_modules/@oneplatformdev/hooks/src/useIsMobile/types.ts

@@ -0,0 +1,3 @@
+export interface IUseIsMobileParams {
+  mobileBreakpoint?: number;
+}

package/node_modules/@oneplatformdev/hooks/src/useIsMobile/useIsMobile.tsx

@@ -0,0 +1,23 @@
+import * as React from "react"
+import { IUseIsMobileParams } from './types';
+
+const DEFAULT_MOBILE_BREAKPOINT = 768
+
+export function useIsMobile(params: IUseIsMobileParams = {}) {
+  const {
+    mobileBreakpoint = DEFAULT_MOBILE_BREAKPOINT
+  } = params;
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${mobileBreakpoint - 1}px)`)
+    const onChange = () => {
+      setIsMobile(window.innerWidth < mobileBreakpoint)
+    }
+    mql.addEventListener("change", onChange)
+    setIsMobile(window.innerWidth < mobileBreakpoint)
+    return () => mql.removeEventListener("change", onChange)
+  }, [mobileBreakpoint])
+
+  return !!isMobile
+}

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

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

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

@@ -0,0 +1,15 @@
+import { useCallback, useEffect, useRef } from 'react'
+
+export function useIsMounted(): () => boolean {
+  const isMounted = useRef(false)
+
+  useEffect(() => {
+    isMounted.current = true
+
+    return () => {
+      isMounted.current = false
+    }
+  }, [])
+
+  return useCallback(() => isMounted.current, [])
+}

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

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

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

@@ -0,0 +1,17 @@
+import { useEffect, useLayoutEffect } from 'react'
+
+/**
+ * Custom hook that uses either `useLayoutEffect` or `useEffect` based on the environment (client-side or server-side).
+ * @param {Function} effect - The effect function to be executed.
+ * @param {Array<any>} [dependencies] - An array of dependencies for the effect (optional).
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-isomorphic-layout-effect)
+ * @example
+ * ```tsx
+ * useIsomorphicLayoutEffect(() => {
+ *   // Code to be executed during the layout phase on the client side
+ * }, [dependency1, dependency2]);
+ * ```
+ */
+export const useIsomorphicLayoutEffect =
+  typeof window !== 'undefined' ? useLayoutEffect : useEffect

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

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

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

@@ -0,0 +1,191 @@
+import { useCallback, useEffect, useState } from 'react'
+
+import type { Dispatch, SetStateAction } from 'react'
+
+import { useEventCallback } from '../useEventCallback'
+import { useEventListener } from '../useEventListener'
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface WindowEventMap {
+    'local-storage': CustomEvent
+  }
+}
+
+/**
+ * Options for customizing the behavior of serialization and deserialization.
+ * @template T - The type of the state to be stored in local storage.
+ */
+type UseLocalStorageOptions<T> = {
+  /** A function to serialize the value before storing it. */
+  serializer?: (value: T) => string
+  /** A function to deserialize the stored value. */
+  deserializer?: (value: string) => T
+  /**
+   * If `true` (default), the hook will initialize reading the local storage. In SSR, you should set it to `false`, returning the initial value initially.
+   * @default true
+   */
+  initializeWithValue?: boolean
+}
+
+const IS_SERVER = typeof window === 'undefined'
+
+/**
+ * Custom hook that uses the [`localStorage API`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) to persist state across page reloads.
+ * @template T - The type of the state to be stored in local storage.
+ * @param {string} key - The key under which the value will be stored in local storage.
+ * @param {T | (() => T)} initialValue - The initial value of the state or a function that returns the initial value.
+ * @param {UseLocalStorageOptions<T>} [options] - Options for customizing the behavior of serialization and deserialization (optional).
+ * @returns {[T, Dispatch<SetStateAction<T>>, () => void]} A tuple containing the stored value, a function to set the value and a function to remove the key from storage.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-local-storage)
+ * @example
+ * ```tsx
+ * const [count, setCount, removeCount] = useLocalStorage('count', 0);
+ * // Access the `count` value, the `setCount` function to update it and `removeCount` function to remove the key from storage.
+ * ```
+ */
+export function useLocalStorage<T>(
+  key: string,
+  initialValue: T | (() => T),
+  options: UseLocalStorageOptions<T> = {},
+): [T, Dispatch<SetStateAction<T>>, () => void] {
+  const { initializeWithValue = true } = options
+
+  const serializer = useCallback<(value: T) => string>(
+    value => {
+      if (options.serializer) {
+        return options.serializer(value)
+      }
+
+      return JSON.stringify(value)
+    },
+    [options],
+  )
+
+  const deserializer = useCallback<(value: string) => T>(
+    value => {
+      if (options.deserializer) {
+        return options.deserializer(value)
+      }
+      // Support 'undefined' as a value
+      if (value === 'undefined') {
+        return undefined as unknown as T
+      }
+
+      const defaultValue =
+        initialValue instanceof Function ? initialValue() : initialValue
+
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(value)
+      } catch (error) {
+        console.error('Error parsing JSON:', error)
+        return defaultValue // Return initialValue if parsing fails
+      }
+
+      return parsed as T
+    },
+    [options, initialValue],
+  )
+
+  // Get from local storage then
+  // parse stored json or return initialValue
+  const readValue = useCallback((): T => {
+    const initialValueToUse =
+      initialValue instanceof Function ? initialValue() : initialValue
+
+    // Prevent build error "window is undefined" but keep working
+    if (IS_SERVER) {
+      return initialValueToUse
+    }
+
+    try {
+      const raw = window.localStorage.getItem(key)
+      return raw ? deserializer(raw) : initialValueToUse
+    } catch (error) {
+      console.warn(`Error reading localStorage key “${key}”:`, error)
+      return initialValueToUse
+    }
+  }, [initialValue, key, deserializer])
+
+  const [storedValue, setStoredValue] = useState(() => {
+    if (initializeWithValue) {
+      return readValue()
+    }
+
+    return initialValue instanceof Function ? initialValue() : initialValue
+  })
+
+  // Return a wrapped version of useState's setter function that ...
+  // ... persists the new value to localStorage.
+  const setValue: Dispatch<SetStateAction<T>> = useEventCallback(value => {
+    // Prevent build error "window is undefined" but keeps working
+    if (IS_SERVER) {
+      console.warn(
+        `Tried setting localStorage key “${key}” even though environment is not a client`,
+      )
+    }
+
+    try {
+      // Allow value to be a function so we have the same API as useState
+      const newValue = value instanceof Function ? value(readValue()) : value
+
+      // Save to local storage
+      window.localStorage.setItem(key, serializer(newValue))
+
+      // Save state
+      setStoredValue(newValue)
+
+      // We dispatch a custom event so every similar useLocalStorage hook is notified
+      window.dispatchEvent(new StorageEvent('local-storage', { key }))
+    } catch (error) {
+      console.warn(`Error setting localStorage key “${key}”:`, error)
+    }
+  })
+
+  const removeValue = useEventCallback(() => {
+    // Prevent build error "window is undefined" but keeps working
+    if (IS_SERVER) {
+      console.warn(
+        `Tried removing localStorage key “${key}” even though environment is not a client`,
+      )
+    }
+
+    const defaultValue =
+      initialValue instanceof Function ? initialValue() : initialValue
+
+    // Remove the key from local storage
+    window.localStorage.removeItem(key)
+
+    // Save state with default value
+    setStoredValue(defaultValue)
+
+    // We dispatch a custom event so every similar useLocalStorage hook is notified
+    window.dispatchEvent(new StorageEvent('local-storage', { key }))
+  })
+
+  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, setValue, removeValue]
+}

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

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

package/node_modules/@oneplatformdev/hooks/src/useLockBody/useLockBody.tsx

@@ -0,0 +1,12 @@
+import * as React from "react"
+
+// @see https://usehooks.com/useLockBodyScroll.
+export function useLockBody() {
+  React.useLayoutEffect((): (() => void) => {
+    const originalStyle: string = window.getComputedStyle(
+      document.body
+    ).overflow
+    document.body.style.overflow = "hidden"
+    return () => (document.body.style.overflow = originalStyle)
+  }, [])
+}

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

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

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

@@ -0,0 +1,83 @@
+import { useCallback, useState } from 'react'
+
+/**
+ * Represents the type for either a Map or an array of key-value pairs.
+ * @template K - The type of keys in the map.
+ * @template V - The type of values in the map.
+ */
+type MapOrEntries<K, V> = Map<K, V> | [K, V][]
+
+/**
+ * Represents the actions available to interact with the map state.
+ * @template K - The type of keys in the map.
+ * @template V - The type of values in the map.
+ */
+type UseMapActions<K, V> = {
+  /** Set a key-value pair in the map. */
+  set: (key: K, value: V) => void
+  /** Set all key-value pairs in the map. */
+  setAll: (entries: MapOrEntries<K, V>) => void
+  /** Remove a key-value pair from the map. */
+  remove: (key: K) => void
+  /** Reset the map to an empty state. */
+  reset: Map<K, V>['clear']
+}
+
+/**
+ * Represents the return type of the `useMap` hook.
+ * We hide some setters from the returned map to disable autocompletion.
+ * @template K - The type of keys in the map.
+ * @template V - The type of values in the map.
+ */
+type UseMapReturn<K, V> = [
+  Omit<Map<K, V>, 'set' | 'clear' | 'delete'>,
+  UseMapActions<K, V>,
+]
+
+/**
+ * Custom hook that manages a key-value [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) state with setter actions.
+ * @template K - The type of keys in the map.
+ * @template V - The type of values in the map.
+ * @param {MapOrEntries<K, V>} [initialState] - The initial state of the map as a Map or an array of key-value pairs (optional).
+ * @returns {UseMapReturn<K, V>} A tuple containing the map state and actions to interact with the map.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-map)
+ * @example
+ * ```tsx
+ * const [map, mapActions] = useMap();
+ * // Access the `map` state and use `mapActions` to set, remove, or reset entries.
+ * ```
+ */
+export function useMap<K, V>(
+  initialState: MapOrEntries<K, V> = new Map(),
+): UseMapReturn<K, V> {
+  const [map, setMap] = useState(new Map(initialState))
+
+  const actions: UseMapActions<K, V> = {
+    set: useCallback((key, value) => {
+      setMap(prev => {
+        const copy = new Map(prev)
+        copy.set(key, value)
+        return copy
+      })
+    }, []),
+
+    setAll: useCallback(entries => {
+      setMap(() => new Map(entries))
+    }, []),
+
+    remove: useCallback(key => {
+      setMap(prev => {
+        const copy = new Map(prev)
+        copy.delete(key)
+        return copy
+      })
+    }, []),
+
+    reset: useCallback(() => {
+      setMap(() => new Map())
+    }, []),
+  }
+
+  return [map, actions]
+}

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

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