@oneplatformdev/ui 0.0.1-beta.99 → 0.1.0-8

package/node_modules/@oneplatformdev/hooks/src/useSessionStorage/useSessionStorage.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 {
+    'session-storage': CustomEvent
+  }
+}
+
+/**
+ * Represents the options for customizing the behavior of serialization and deserialization.
+ * @template T - The type of the state to be stored in session storage.
+ */
+type UseSessionStorageOptions<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 session 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 [`sessionStorage API`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) to persist state across page reloads.
+ * @template T - The type of the state to be stored in session storage.
+ * @param {string} key - The key under which the value will be stored in session storage.
+ * @param {T | (() => T)} initialValue - The initial value of the state or a function that returns the initial value.
+ * @param {?UseSessionStorageOptions<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-session-storage)
+ * @example
+ * ```tsx
+ * const [count, setCount, removeCount] = useSessionStorage('count', 0);
+ * // Access the `count` value, the `setCount` function to update it and `removeCount` function to remove the key from storage.
+ * ```
+ */
+export function useSessionStorage<T>(
+  key: string,
+  initialValue: T | (() => T),
+  options: UseSessionStorageOptions<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 session 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.sessionStorage.getItem(key)
+      return raw ? deserializer(raw) : initialValueToUse
+    } catch (error) {
+      console.warn(`Error reading sessionStorage 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 sessionStorage.
+  const setValue: Dispatch<SetStateAction<T>> = useEventCallback(value => {
+    // Prevent build error "window is undefined" but keeps working
+    if (IS_SERVER) {
+      console.warn(
+        `Tried setting sessionStorage 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 session storage
+      window.sessionStorage.setItem(key, serializer(newValue))
+
+      // Save state
+      setStoredValue(newValue)
+
+      // We dispatch a custom event so every similar useSessionStorage hook is notified
+      window.dispatchEvent(new StorageEvent('session-storage', { key }))
+    } catch (error) {
+      console.warn(`Error setting sessionStorage key “${key}”:`, error)
+    }
+  })
+
+  const removeValue = useEventCallback(() => {
+    // Prevent build error "window is undefined" but keeps working
+    if (IS_SERVER) {
+      console.warn(
+        `Tried removing sessionStorage key “${key}” even though environment is not a client`,
+      )
+    }
+
+    const defaultValue =
+      initialValue instanceof Function ? initialValue() : initialValue
+
+    // Remove the key from session storage
+    window.sessionStorage.removeItem(key)
+
+    // Save state with default value
+    setStoredValue(defaultValue)
+
+    // We dispatch a custom event so every similar useSessionStorage hook is notified
+    window.dispatchEvent(new StorageEvent('session-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 writeValueToSessionStorage
+  // See: useSessionStorage()
+  useEventListener('session-storage', handleStorageChange)
+
+  return [storedValue, setValue, removeValue]
+}

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

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

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

@@ -0,0 +1,83 @@
+import { useCallback, useState } from 'react'
+
+import type { Dispatch, SetStateAction } from 'react'
+
+/** Represents the second element of the output of the `useStep` hook. */
+type UseStepActions = {
+  /** Go to the next step in the process. */
+  goToNextStep: () => void
+  /** Go to the previous step in the process. */
+  goToPrevStep: () => void
+  /** Reset the step to the initial step. */
+  reset: () => void
+  /** Check if the next step is available. */
+  canGoToNextStep: boolean
+  /** Check if the previous step is available. */
+  canGoToPrevStep: boolean
+  /** Set the current step to a specific value. */
+  setStep: Dispatch<SetStateAction<number>>
+}
+
+type SetStepCallbackType = (step: number | ((step: number) => number)) => void
+
+/**
+ * Custom hook that manages and navigates between steps in a multi-step process.
+ * @param {number} maxStep - The maximum step in the process.
+ * @returns {[number, UseStepActions]} An tuple containing the current step and helper functions for navigating steps.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-step)
+ * @example
+ * ```tsx
+ * const [currentStep, { goToNextStep, goToPrevStep, reset, canGoToNextStep, canGoToPrevStep, setStep }] = useStep(3);
+ * // Access and use the current step and provided helper functions.
+ * ```
+ */
+export function useStep(maxStep: number): [number, UseStepActions] {
+  const [currentStep, setCurrentStep] = useState(1)
+
+  const canGoToNextStep = currentStep + 1 <= maxStep
+  const canGoToPrevStep = currentStep - 1 > 0
+
+  const setStep = useCallback<SetStepCallbackType>(
+    step => {
+      // Allow value to be a function so we have the same API as useState
+      const newStep = step instanceof Function ? step(currentStep) : step
+
+      if (newStep >= 1 && newStep <= maxStep) {
+        setCurrentStep(newStep)
+        return
+      }
+
+      throw new Error('Step not valid')
+    },
+    [maxStep, currentStep],
+  )
+
+  const goToNextStep = useCallback(() => {
+    if (canGoToNextStep) {
+      setCurrentStep(step => step + 1)
+    }
+  }, [canGoToNextStep])
+
+  const goToPrevStep = useCallback(() => {
+    if (canGoToPrevStep) {
+      setCurrentStep(step => step - 1)
+    }
+  }, [canGoToPrevStep])
+
+  const reset = useCallback(() => {
+    setCurrentStep(1)
+  }, [])
+
+  return [
+    currentStep,
+    {
+      goToNextStep,
+      goToPrevStep,
+      canGoToNextStep,
+      canGoToPrevStep,
+      setStep,
+      reset,
+    },
+  ]
+}

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

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

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

@@ -0,0 +1,81 @@
+import type { Dispatch, SetStateAction } from 'react'
+
+import { useLocalStorage } from '../useLocalStorage'
+import { useMediaQuery } from '../useMediaQuery'
+
+const COLOR_SCHEME_QUERY = '(prefers-color-scheme: dark)'
+const LOCAL_STORAGE_KEY = 'usehooks-ts-ternary-dark-mode'
+
+/** Ternary dark mode options. */
+export type TernaryDarkMode = 'system' | 'dark' | 'light'
+
+/** Options for the `useTernaryDarkMode` hook. */
+export type TernaryDarkModeOptions = {
+  /**
+   * The default value for the dark mode.
+   * @default 'system'
+   */
+  defaultValue?: TernaryDarkMode
+  /**
+   * The key for storing dark mode preference in local storage.
+   * @default 'usehooks-ts-ternary-dark-mode'
+   */
+  localStorageKey?: string
+  /**
+   * If `true` (default), the hook will initialize reading `localStorage`. In SSR, you should set it to `false`, returning default values initially.
+   * @default true
+   */
+  initializeWithValue?: boolean
+}
+
+/** Represents the return type of the `useTernaryDarkMode` hook. */
+export type TernaryDarkModeReturn = {
+  /** The current state of the dark mode. */
+  isDarkMode: boolean
+  /** The current state of the dark mode. */
+  ternaryDarkMode: TernaryDarkMode
+  /** A function to set the dark mode state. */
+  setTernaryDarkMode: Dispatch<SetStateAction<TernaryDarkMode>>
+  /** A function to toggle the dark mode state. */
+  toggleTernaryDarkMode: () => void
+}
+
+/**
+ * Custom hook that manages ternary (system, dark, light) dark mode with local storage support.
+ * @param {?TernaryDarkModeOptions | string} [options] - Options or the local storage key for the hook.
+ * @returns {TernaryDarkModeReturn} An object containing the dark mode state and helper functions.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-ternary-dark-mode)
+ * @example
+ * ```tsx
+ * const { isDarkMode, ternaryDarkMode, setTernaryDarkMode, toggleTernaryDarkMode } = useTernaryDarkMode({ defaultValue: 'dark' });
+ * // Access and use the dark mode state and provided helper functions.
+ * ```
+ */
+export function useTernaryDarkMode({
+  defaultValue = 'system',
+  localStorageKey = LOCAL_STORAGE_KEY,
+  initializeWithValue = true,
+}: TernaryDarkModeOptions = {}): TernaryDarkModeReturn {
+  const isDarkOS = useMediaQuery(COLOR_SCHEME_QUERY, { initializeWithValue })
+  const [mode, setMode] = useLocalStorage(localStorageKey, defaultValue, {
+    initializeWithValue,
+  })
+
+  const isDarkMode = mode === 'dark' || (mode === 'system' && isDarkOS)
+
+  const toggleTernaryDarkMode = () => {
+    const modes: TernaryDarkMode[] = ['light', 'system', 'dark']
+    setMode((prevMode): TernaryDarkMode => {
+      const nextIndex = (modes.indexOf(prevMode) + 1) % modes.length
+      return modes[nextIndex]
+    })
+  }
+
+  return {
+    isDarkMode,
+    ternaryDarkMode: mode,
+    setTernaryDarkMode: setMode,
+    toggleTernaryDarkMode,
+  }
+}

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

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

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

@@ -0,0 +1,44 @@
+import { useEffect, useRef } from 'react'
+
+import { useIsomorphicLayoutEffect } from '../useIsomorphicLayoutEffect'
+
+/**
+ * Custom hook that handles timeouts in React components using the [`setTimeout API`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout).
+ * @param {() => void} callback - The function to be executed when the timeout elapses.
+ * @param {number | null} delay - The duration (in milliseconds) for the timeout. Set to `null` to clear the timeout.
+ * @returns {void} This hook does not return anything.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-timeout)
+ * @example
+ * ```tsx
+ * // Usage of useTimeout hook
+ * useTimeout(() => {
+ *   // Code to be executed after the specified delay
+ * }, 1000); // Set a timeout of 1000 milliseconds (1 second)
+ * ```
+ */
+export function useTimeout(callback: () => void, delay: number | null): void {
+  const savedCallback = useRef(callback)
+
+  // Remember the latest callback if it changes.
+  useIsomorphicLayoutEffect(() => {
+    savedCallback.current = callback
+  }, [callback])
+
+  // Set up the timeout.
+  useEffect(() => {
+    // Don't schedule if no delay is specified.
+    // Note: 0 is a valid value for delay.
+    if (!delay && delay !== 0) {
+      return
+    }
+
+    const id = setTimeout(() => {
+      savedCallback.current()
+    }, delay)
+
+    return () => {
+      clearTimeout(id)
+    }
+  }, [delay])
+}

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

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

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

@@ -0,0 +1,30 @@
+import { useCallback, useState } from 'react'
+
+import type { Dispatch, SetStateAction } from 'react'
+
+/**
+ * Custom hook that manages a boolean toggle state in React components.
+ * @param {boolean} [defaultValue] - The initial value for the toggle state.
+ * @returns {[boolean, () => void, Dispatch<SetStateAction<boolean>>]} A tuple containing the current state,
+ * a function to toggle the state, and a function to set the state explicitly.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-toggle)
+ * @example
+ * ```tsx
+ * const [isToggled, toggle, setToggle] = useToggle(); // Initial value is false
+ * // OR
+ * const [isToggled, toggle, setToggle] = useToggle(true); // Initial value is true
+ * // Use isToggled in your component, toggle to switch the state, setToggle to set the state explicitly.
+ * ```
+ */
+export function useToggle(
+  defaultValue?: boolean,
+): [boolean, () => void, Dispatch<SetStateAction<boolean>>] {
+  const [value, setValue] = useState(!!defaultValue)
+
+  const toggle = useCallback(() => {
+    setValue(x => !x)
+  }, [])
+
+  return [value, toggle, setValue]
+}

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

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

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

@@ -0,0 +1,26 @@
+import { useEffect, useRef } from 'react'
+
+/**
+ * Custom hook that runs a cleanup function when the component is unmounted.
+ * @param {() => void} func - The cleanup function to be executed on unmount.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-unmount)
+ * @example
+ * ```tsx
+ * useUnmount(() => {
+ *   // Cleanup logic here
+ * });
+ * ```
+ */
+export function useUnmount(func: () => void) {
+  const funcRef = useRef(func)
+
+  funcRef.current = func
+
+  useEffect(
+    () => () => {
+      funcRef.current()
+    },
+    [],
+  )
+}

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

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

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

@@ -0,0 +1,100 @@
+import { useState } from 'react'
+
+import { useDebounceCallback } from '../useDebounceCallback'
+import { useEventListener } from '../useEventListener'
+import { useIsomorphicLayoutEffect } from '../useIsomorphicLayoutEffect'
+
+/**
+ * Represent the dimension of the window.
+ * @template T - The type of the dimension (number or undefined).
+ */
+type WindowSize<T extends number | undefined = number | undefined> = {
+  /** The width of the window. */
+  width: T
+  /** The height of the window. */
+  height: T
+}
+
+/**
+ * Hook options.
+ * @template InitializeWithValue - If `true` (default), the hook will initialize reading the window size. In SSR, you should set it to `false`, returning `undefined` initially.
+ */
+type UseWindowSizeOptions<InitializeWithValue extends boolean | undefined> = {
+  /**
+   * If `true` (default), the hook will initialize reading the window size. 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 useWindowSize.
+export function useWindowSize(options: UseWindowSizeOptions<false>): WindowSize
+// CSR version of useWindowSize.
+export function useWindowSize(
+  options?: Partial<UseWindowSizeOptions<true>>,
+): WindowSize<number>
+/**
+ * Custom hook that tracks the size of the window.
+ * @param {?UseWindowSizeOptions} [options] - The options for customizing the behavior of the hook (optional).
+ * @returns {object} An object containing the width and height of the window.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-window-size)
+ * @example
+ * ```tsx
+ * const { width = 0, height = 0 } = useWindowSize();
+ * console.log(`Window size: ${width} x ${height}`);
+ * ```
+ */
+export function useWindowSize(
+  options: Partial<UseWindowSizeOptions<boolean>> = {},
+): WindowSize | WindowSize<number> {
+  let { initializeWithValue = true } = options
+  if (IS_SERVER) {
+    initializeWithValue = false
+  }
+
+  const [windowSize, setWindowSize] = useState<WindowSize>(() => {
+    if (initializeWithValue) {
+      return {
+        width: window.innerWidth,
+        height: window.innerHeight,
+      }
+    }
+    return {
+      width: undefined,
+      height: undefined,
+    }
+  })
+
+  const debouncedSetWindowSize = useDebounceCallback(
+    setWindowSize,
+    options.debounceDelay,
+  )
+
+  function handleSize() {
+    const setSize = options.debounceDelay
+      ? debouncedSetWindowSize
+      : setWindowSize
+
+    setSize({
+      width: window.innerWidth,
+      height: window.innerHeight,
+    })
+  }
+
+  useEventListener('resize', handleSize)
+
+  // Set size at the first client-side load
+  useIsomorphicLayoutEffect(() => {
+    handleSize()
+  }, [])
+
+  return windowSize
+}

package/node_modules/@oneplatformdev/hooks/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    }
+  ],
+  "extends": "../../tsconfig.base.json"
+}

package/node_modules/@oneplatformdev/hooks/tsconfig.lib.json

@@ -0,0 +1,33 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "types": [
+      "node",
+      "@nx/react/typings/cssmodule.d.ts",
+      "@nx/react/typings/image.d.ts",
+      "vite/client"
+    ],
+    "rootDir": "src",
+    "jsx": "react-jsx",
+    "tsBuildInfoFile": "dist/tsconfig.lib.tsbuildinfo"
+  },
+  "exclude": [
+    "out-tsc",
+    "dist",
+    "**/*.spec.ts",
+    "**/*.test.ts",
+    "**/*.spec.tsx",
+    "**/*.test.tsx",
+    "**/*.spec.js",
+    "**/*.test.js",
+    "**/*.spec.jsx",
+    "**/*.test.jsx"
+  ],
+  "include": [
+    "src/**/*.js",
+    "src/**/*.jsx",
+    "src/**/*.ts",
+    "src/**/*.tsx"
+  ]
+}

package/node_modules/@oneplatformdev/hooks/vite.config.ts

@@ -0,0 +1,62 @@
+/// <reference types='vitest' />
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import dts from 'vite-plugin-dts';
+import * as path from 'path';
+import { globSync } from 'glob';
+import { viteStaticCopy } from 'vite-plugin-static-copy';
+import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
+import { nxCopyAssetsPlugin } from '@nx/vite/plugins/nx-copy-assets.plugin';
+
+export default defineConfig(() => ({
+  root: __dirname,
+  cacheDir: '../../node_modules/.vite/packages/hooks',
+  plugins: [
+    react(),
+    nxViteTsPaths(),
+    nxCopyAssetsPlugin(['*.md', 'LICENSE', 'package.json']),
+    dts({
+      entryRoot: 'src',
+      tsconfigPath: path.join(__dirname, 'tsconfig.lib.json')
+    })
+  ],
+  build: {
+    outDir: './dist',
+    emptyOutDir: true,
+    reportCompressedSize: true,
+    commonjsOptions: {
+      transformMixedEsModules: true,
+    },
+    sourcemap: false,
+    target: 'es2022',
+    lib: {
+      name: '@oneplatformdev/hooks',
+      formats: [ 'es' as const ],
+      entry: {
+        index: path.resolve(__dirname, 'src/index.ts'),
+        ...Object.fromEntries(
+          globSync('src/**/*.{ts,tsx}').map((filename) => {
+            return [
+              path.relative(
+                'src',
+                filename.slice(0, filename.length - path.extname(filename).length)
+              ),
+              path.resolve(__dirname, filename),
+            ]
+          })
+        )
+      }
+    },
+    rollupOptions: {
+      external: [ 'react', 'react-dom', 'react/jsx-runtime', "lodash.debounce" ],
+      output: {
+        preserveModules: true,
+        preserveModulesRoot: 'src',
+        globals: {
+          react: 'React',
+          'react-dom': 'ReactDOM',
+        }
+      }
+    }
+  },
+}));