react-simplikit 0.0.2 → 0.0.4

package/esm/hooks/useLoading/index.d.mts

@@ -0,0 +1,37 @@
+/**
+ * @description
+ * `useLoading` is a React hook that simplifies managing the loading state of a `Promise`.
+ * It provides a state to track whether an asynchronous operation is in progress and a function to handle the loading state automatically.
+ *
+ * @returns A tuple `[boolean, <T>(promise: Promise<T>) => Promise<T>]`:
+ *
+ * - `boolean`: Represents the current loading state.
+ *    - The initial value is `false`.
+ *    - It is set to `true` when an asynchronous task is in progress.
+ *
+ * - `<T>(promise: Promise<T>) => Promise<T>`: A function that executes asynchronous tasks while managing the loading state.
+ *    - This function takes a `Promise` as an argument and automatically resets the `isLoading` state to `false` when the `Promise` completes.
+ *
+ * @example
+ * function ConfirmButton() {
+ *   const [loading, startLoading] = useLoading();
+ *
+ *   const handleSubmit = useCallback(async () => {
+ *     try {
+ *       const result = await startLoading(postConfirmation());
+ *       router.push(`/success?id=${result.id}`);
+ *     } catch (error) {
+ *       console.error('Error:', error);
+ *     }
+ *   }, [startLoading]);
+ *
+ *   return (
+ *     <button disabled={loading} onClick={handleSubmit}>
+ *       {loading ? 'Loading...' : 'Confirm'}
+ *     </button>
+ *   );
+ * }
+ */
+declare function useLoading(): [boolean, <T>(promise: Promise<T>) => Promise<T>];
+
+export { useLoading };

package/esm/hooks/useLoading/index.mjs

@@ -0,0 +1,34 @@
+// src/hooks/useLoading/useLoading.ts
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+function useLoading() {
+  const [loading, setLoading] = useState(false);
+  const ref = useIsMountedRef();
+  const startTransition = useCallback(
+    async (promise) => {
+      try {
+        setLoading(true);
+        const data = await promise;
+        return data;
+      } finally {
+        if (ref.isMounted) {
+          setLoading(false);
+        }
+      }
+    },
+    [ref.isMounted]
+  );
+  return useMemo(() => [loading, startTransition], [loading, startTransition]);
+}
+function useIsMountedRef() {
+  const ref = useRef({ isMounted: true }).current;
+  useEffect(() => {
+    ref.isMounted = true;
+    return () => {
+      ref.isMounted = false;
+    };
+  }, [ref]);
+  return ref;
+}
+export {
+  useLoading
+};

package/esm/hooks/useOutsideClickEffect/index.d.mts

@@ -0,0 +1,27 @@
+type OneOrMore<T> = T | T[];
+/**
+ * @description
+ * `useOutsideClickEffect` is a React hook that triggers a callback when a click event occurs outside the specified container(s).
+ * It is useful for closing modals, dropdowns, tooltips, and other UI components when clicking outside.
+ *
+ * @param {HTMLElement | HTMLElement[] | null} container - A single HTML element, an array of HTML elements, or `null`.
+ *   If `null`, no event listener is attached.
+ * @param {() => void} callback - A function that is executed when clicking outside the specified container(s).
+ *
+ * @example
+ * import { useOutsideClickEffect } from 'react-simplikit';
+ * import { useState } from 'react';
+ *
+ * function Example() {
+ *   const [wrapperEl, setWrapperEl] = useState<HTMLDivElement | null>(null);
+ *
+ *   useOutsideClickEffect(wrapperEl, () => {
+ *     console.log('Outside clicked!');
+ *   });
+ *
+ *   return <div ref={setWrapperEl}>Content</div>;
+ * }
+ */
+declare function useOutsideClickEffect(container: OneOrMore<HTMLElement | null>, callback: () => void): void;
+
+export { useOutsideClickEffect };

package/esm/hooks/useOutsideClickEffect/index.mjs

@@ -0,0 +1,43 @@
+// src/hooks/useOutsideClickEffect/useOutsideClickEffect.ts
+import { useEffect as useEffect2, useRef as useRef2 } from "react";
+
+// src/hooks/usePreservedCallback/usePreservedCallback.ts
+import { useCallback, useEffect, useRef } from "react";
+function usePreservedCallback(callback) {
+  const callbackRef = useRef(callback);
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+  return useCallback((...args) => {
+    return callbackRef.current(...args);
+  }, []);
+}
+
+// src/hooks/useOutsideClickEffect/useOutsideClickEffect.ts
+function useOutsideClickEffect(container, callback) {
+  const containers = useRef2([]);
+  const handleDocumentClick = usePreservedCallback(({ target }) => {
+    if (target === null) {
+      return;
+    }
+    if (containers.current.length === 0) {
+      return;
+    }
+    if (containers.current.some((x) => x.contains(target))) {
+      return;
+    }
+    callback();
+  });
+  useEffect2(() => {
+    containers.current = [container].flat(1).filter((item) => item != null);
+  }, [container]);
+  useEffect2(() => {
+    document.addEventListener("click", handleDocumentClick);
+    return () => {
+      document.removeEventListener("click", handleDocumentClick);
+    };
+  }, [handleDocumentClick]);
+}
+export {
+  useOutsideClickEffect
+};

package/esm/hooks/usePreservedCallback/index.d.mts

@@ -0,0 +1,30 @@
+/**
+ * @description
+ * `usePreservedCallback` is a React hook that maintains a stable reference to a callback function
+ * while ensuring it always has access to the latest state or props. This prevents unnecessary re-renders
+ * and simplifies dependency management when passing callbacks to child components or handling event listeners.
+ *
+ * @param {(...args: any[]) => any} callback - The function to preserve.
+ *   It always references the latest state or props, even when the component re-renders.
+ *
+ * @returns {(...args: any[]) => any} A function with the same signature as the input callback.
+ *   The returned function maintains a stable reference while accessing the latest state or props.
+ *
+ * @example
+ * import { usePreservedCallback } from 'react-simplikit';
+ * import { useState } from 'react';
+ *
+ * function Counter() {
+ *   const [count, setCount] = useState(0);
+ *
+ *   const handleClick = usePreservedCallback(() => {
+ *     console.log(`Current count: ${count}`);
+ *     setCount(prev => prev + 1);
+ *   });
+ *
+ *   return <button onClick={handleClick}>Click me</button>;
+ * }
+ */
+declare function usePreservedCallback<Arguments extends any[] = any[], ReturnValue = unknown>(callback: (...args: Arguments) => ReturnValue): (...args: Arguments) => ReturnValue;
+
+export { usePreservedCallback };

package/esm/hooks/usePreservedCallback/index.mjs

@@ -0,0 +1,14 @@
+// src/hooks/usePreservedCallback/usePreservedCallback.ts
+import { useCallback, useEffect, useRef } from "react";
+function usePreservedCallback(callback) {
+  const callbackRef = useRef(callback);
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+  return useCallback((...args) => {
+    return callbackRef.current(...args);
+  }, []);
+}
+export {
+  usePreservedCallback
+};

package/esm/hooks/usePreservedReference/index.d.mts

@@ -0,0 +1,42 @@
+type NotNullishValue = {};
+/**
+ * @description
+ * `usePreservedReference` is a React hook that helps maintain the reference of a value
+ * when it hasn't changed, while ensuring you can safely use the latest state.
+ * It prevents unnecessary re-renders while always allowing access to the latest data.
+ *
+ * @param {T} value - The value to maintain the reference for. It returns a new reference
+ *   if the state value changes after comparison.
+ * @param {(a: T, b: T) => boolean} [areValuesEqual] - An optional function to determine
+ *   if two values are equal. By default, it uses `JSON.stringify` for comparison.
+ *
+ * @returns {T} Returns the same reference if the value is considered equal to the previous one,
+ *   otherwise returns a new reference.
+ *
+ * @example
+ * import { usePreservedReference } from 'react-simplikit';
+ * import { useState } from 'react';
+ *
+ * function ExampleComponent() {
+ *   const [state, setState] = useState({ key: 'value' });
+ *
+ *   const preservedState = usePreservedReference(state);
+ *
+ *   return <div>{preservedState.key}</div>;
+ * }
+ *
+ * @example
+ * import { usePreservedReference } from 'react-simplikit';
+ * import { useState } from 'react';
+ *
+ * function ExampleComponent() {
+ *   const [state, setState] = useState({ key: 'value' });
+ *
+ *   const preservedState = usePreservedReference(state, (a, b) => a.key === b.key);
+ *
+ *   return <div>{preservedState.key}</div>;
+ * }
+ */
+declare function usePreservedReference<T extends NotNullishValue>(value: T, areValuesEqual?: (a: T, b: T) => boolean): T;
+
+export { usePreservedReference };

package/esm/hooks/usePreservedReference/index.mjs

@@ -0,0 +1,17 @@
+// src/hooks/usePreservedReference/usePreservedReference.ts
+import { useMemo, useRef } from "react";
+function usePreservedReference(value, areValuesEqual = areDeeplyEqual) {
+  const ref = useRef(value);
+  return useMemo(() => {
+    if (!areValuesEqual(ref.current, value)) {
+      ref.current = value;
+    }
+    return ref.current;
+  }, [areValuesEqual, value]);
+}
+function areDeeplyEqual(x, y) {
+  return JSON.stringify(x) === JSON.stringify(y);
+}
+export {
+  usePreservedReference
+};

package/esm/hooks/usePrevious/index.d.mts

@@ -0,0 +1,21 @@
+/**
+ * @description
+ * Returns the previous value of the input state.
+ * If a re-render occurs but the state value does not change, the previous value remains unchanged.
+ * If the state is an object or requires custom change detection, a `compare` function can be provided.
+ * By default, state changes are detected using `prev === next`.
+ *
+ * @template T - The type of the state.
+ * @param {T} state - The state whose previous value is to be tracked.
+ * @param {(prev: T | undefined, next: T) => boolean} [compare] - An optional comparison function to determine if the state has changed.
+ *
+ * @returns {T | undefined} The previous value of the state.
+ *
+ * @example
+ * const [count, setCount] = useState(0);
+ * // initial value of previousCount is `0`
+ * const previousCount = usePrevious(count);
+ */
+declare function usePrevious<T>(state: T, compare?: (prev: T, next: T) => boolean): T;
+
+export { usePrevious };

package/esm/hooks/usePrevious/index.mjs

@@ -0,0 +1,20 @@
+// src/hooks/usePrevious/usePrevious.ts
+import { useEffect, useRef } from "react";
+var strictEquals = (prev, next) => prev === next;
+function usePrevious(state, compare = strictEquals) {
+  const prevRef = useRef(state);
+  const currentRef = useRef(state);
+  const isFirstRender = useRef(true);
+  useEffect(() => {
+    isFirstRender.current = false;
+  }, []);
+  if (isFirstRender.current || compare(currentRef.current, state)) {
+    return prevRef.current;
+  }
+  prevRef.current = currentRef.current;
+  currentRef.current = state;
+  return prevRef.current;
+}
+export {
+  usePrevious
+};

package/esm/hooks/useRefEffect/index.d.mts

@@ -0,0 +1,31 @@
+import { DependencyList } from 'react';
+
+type CleanupCallback = () => void;
+/**
+ * @description
+ * `useRefEffect` is a custom hook that helps you set a reference to a specific DOM element and execute a callback whenever the element changes.
+ * This hook calls a cleanup function whenever the element changes to prevent memory leaks.
+ *
+ * @param callback - A callback function that is executed when the element is set. This function can return a cleanup function.
+ * @param deps - An array of dependencies that define when the callback should be re-executed. The `callback` is re-executed whenever the `deps` change.
+ *
+ * @returns A function to set the element. Pass this function to the `ref` attribute, and the `callback` will be called whenever the element changes.
+ *
+ * @example
+ * import { useRefEffect } from 'react-simplikit';
+ *
+ * function Component() {
+ *   const ref = useRefEffect<HTMLDivElement>(element => {
+ *     console.log('Element mounted:', element);
+ *
+ *     return () => {
+ *       console.log('Element unmounted:', element);
+ *     };
+ *   }, []);
+ *
+ *   return <div ref={ref}>Basic Example</div>;
+ * }
+ */
+declare function useRefEffect<Element extends HTMLElement = HTMLElement>(callback: (element: Element) => CleanupCallback | void, deps: DependencyList): (element: Element | null) => void;
+
+export { useRefEffect };

package/esm/hooks/useRefEffect/index.mjs

@@ -0,0 +1,41 @@
+// src/hooks/useRefEffect/useRefEffect.ts
+import { useCallback as useCallback2, useRef as useRef2 } from "react";
+
+// src/hooks/usePreservedCallback/usePreservedCallback.ts
+import { useCallback, useEffect, useRef } from "react";
+function usePreservedCallback(callback) {
+  const callbackRef = useRef(callback);
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+  return useCallback((...args) => {
+    return callbackRef.current(...args);
+  }, []);
+}
+
+// src/hooks/useRefEffect/useRefEffect.ts
+function useRefEffect(callback, deps) {
+  const preservedCallback = usePreservedCallback(callback);
+  const cleanupCallbackRef = useRef2(() => {
+  });
+  const effect = useCallback2(
+    (element) => {
+      cleanupCallbackRef.current();
+      cleanupCallbackRef.current = () => {
+      };
+      if (element == null) {
+        return;
+      }
+      const cleanup = preservedCallback(element);
+      if (typeof cleanup === "function") {
+        cleanupCallbackRef.current = cleanup;
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [preservedCallback, ...deps]
+  );
+  return effect;
+}
+export {
+  useRefEffect
+};

package/esm/hooks/useStorageState/index.d.mts

@@ -0,0 +1,50 @@
+import { SetStateAction } from 'react';
+
+type Storage = {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+    clear(): void;
+};
+
+type ToPrimitive<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : never;
+type ToObject<T> = T extends unknown[] | Record<string, unknown> ? T : never;
+type Serializable<T> = T extends string | number | boolean ? ToPrimitive<T> : ToObject<T>;
+type StorageStateOptions<T> = {
+    storage?: Storage;
+    defaultValue?: Serializable<T>;
+};
+type StorageStateOptionsWithDefaultValue<T> = StorageStateOptions<T> & {
+    defaultValue: Serializable<T>;
+};
+/**
+ * @description
+ * A React hook that functions like `useState` but persists the state value in browser storage.
+ * The value is retained across page reloads and can be shared between tabs when using `localStorage`.
+ *
+ * @param {string} key - The key used to store the value in storage.
+ * @param {object} [options] - Configuration options for storage behavior.
+ * @param {Storage} [options.storage=localStorage] - The storage type (`localStorage` or `sessionStorage`). Defaults to `localStorage`.
+ * @param {T} [options.defaultValue] - The initial value if no existing value is found.
+ *
+ * @returns {[Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void]} A tuple:
+ * - `state`: The current state value retrieved from storage.
+ * - `setState`: A function to update and persist the state.
+ *
+ * @example
+ * // Counter with persistent state
+ * import { useStorageState } from 'react-simplikit';
+ *
+ * function Counter() {
+ *   const [count, setCount] = useStorageState<number>('counter', {
+ *     defaultValue: 0,
+ *   });
+ *
+ *   return <button onClick={() => setCount(prev => prev + 1)}>Count: {count}</button>;
+ * }
+ */
+declare function useStorageState<T>(key: string): readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void];
+declare function useStorageState<T>(key: string, { storage, defaultValue }: StorageStateOptionsWithDefaultValue<T>): readonly [Serializable<T>, (value: SetStateAction<Serializable<T>>) => void];
+declare function useStorageState<T>(key: string, { storage, defaultValue }: StorageStateOptions<T>): readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void];
+
+export { type Serializable, useStorageState };

package/esm/hooks/useStorageState/index.mjs

@@ -0,0 +1,141 @@
+// src/hooks/useStorageState/useStorageState.ts
+import { useCallback, useRef, useSyncExternalStore } from "react";
+
+// src/hooks/useStorageState/storage.ts
+var MemoStorage = class {
+  storage = /* @__PURE__ */ new Map();
+  get(key) {
+    return this.storage.get(key) ?? null;
+  }
+  set(key, value) {
+    this.storage.set(key, value);
+  }
+  remove(key) {
+    this.storage.delete(key);
+  }
+  clear() {
+    this.storage.clear();
+  }
+};
+var LocalStorage = class {
+  static canUse() {
+    const TEST_KEY = generateTestKey();
+    try {
+      localStorage.setItem(TEST_KEY, "test");
+      localStorage.removeItem(TEST_KEY);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  get(key) {
+    return localStorage.getItem(key);
+  }
+  set(key, value) {
+    localStorage.setItem(key, value);
+  }
+  remove(key) {
+    localStorage.removeItem(key);
+  }
+  clear() {
+    localStorage.clear();
+  }
+};
+var SessionStorage = class {
+  static canUse() {
+    const TEST_KEY = generateTestKey();
+    try {
+      sessionStorage.setItem(TEST_KEY, "test");
+      sessionStorage.removeItem(TEST_KEY);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  get(key) {
+    return sessionStorage.getItem(key);
+  }
+  set(key, value) {
+    sessionStorage.setItem(key, value);
+  }
+  remove(key) {
+    sessionStorage.removeItem(key);
+  }
+  clear() {
+    sessionStorage.clear();
+  }
+};
+function generateTestKey() {
+  return new Array(4).fill(null).map(() => Math.random().toString(36).slice(2)).join("");
+}
+function generateStorage() {
+  if (LocalStorage.canUse()) {
+    return new LocalStorage();
+  }
+  return new MemoStorage();
+}
+function generateSessionStorage() {
+  if (SessionStorage.canUse()) {
+    return new SessionStorage();
+  }
+  return new MemoStorage();
+}
+var safeLocalStorage = generateStorage();
+var safeSessionStorage = generateSessionStorage();
+
+// src/hooks/useStorageState/useStorageState.ts
+var listeners = /* @__PURE__ */ new Set();
+var emitListeners = () => {
+  listeners.forEach((listener) => listener());
+};
+function useStorageState(key, { storage = safeLocalStorage, defaultValue } = {}) {
+  const cache = useRef({
+    data: null,
+    parsed: defaultValue
+  });
+  const getSnapshot = useCallback(() => {
+    const data = storage.get(key);
+    if (data !== cache.current.data) {
+      try {
+        cache.current.parsed = data != null ? JSON.parse(data) : defaultValue;
+      } catch {
+        cache.current.parsed = defaultValue;
+      }
+      cache.current.data = data;
+    }
+    return cache.current.parsed;
+  }, [defaultValue, key, storage]);
+  const storageState = useSyncExternalStore(
+    (onStoreChange) => {
+      listeners.add(onStoreChange);
+      const handler = (event) => {
+        if (event.key === key) {
+          onStoreChange();
+        }
+      };
+      window.addEventListener("storage", handler);
+      return () => {
+        listeners.delete(onStoreChange);
+        window.removeEventListener("storage", handler);
+      };
+    },
+    () => getSnapshot(),
+    () => defaultValue
+  );
+  const setStorageState = useCallback(
+    (value) => {
+      const nextValue = typeof value === "function" ? value(getSnapshot()) : value;
+      if (nextValue == null) {
+        storage.remove(key);
+      } else {
+        storage.set(key, JSON.stringify(nextValue));
+      }
+      emitListeners();
+    },
+    [getSnapshot, key, storage]
+  );
+  return [storageState, setStorageState];
+}
+export {
+  useStorageState
+};

package/esm/hooks/useThrottle/index.d.mts

@@ -0,0 +1,47 @@
+type ThrottleOptions = {
+    /**
+     * An optional array specifying whether the function should be invoked on the leading edge, trailing edge, or both.
+     * If `edges` includes "leading", the function will be invoked at the start of the delay period.
+     * If `edges` includes "trailing", the function will be invoked at the end of the delay period.
+     * If both "leading" and "trailing" are included, the function will be invoked at both the start and end of the delay period.
+     * @default ["leading", "trailing"]
+     */
+    edges?: Array<'leading' | 'trailing'>;
+};
+type ThrottledFunction<F extends (...args: any[]) => void> = {
+    (...args: Parameters<F>): void;
+    cancel: () => void;
+};
+declare function throttle<F extends (...args: any[]) => void>(func: F, throttleMs: number, { edges }?: ThrottleOptions): ThrottledFunction<F>;
+
+/**
+ * @description
+ * A React hook that creates a throttled version of a callback function.
+ * This is useful for limiting the rate at which a function can be called,
+ * such as when handling scroll or resize events.
+ *
+ * @template F - The type of the callback function.
+ * @param {F} callback - The function to be throttled.
+ * @param {number} wait - The number of milliseconds to throttle invocations to.
+ * @param {{ edges?: Array<'leading' | 'trailing'> }} [options] - Options to control the behavior of the throttle.
+ * @returns {F & { cancel: () => void }} - Returns the throttled function with a `cancel` method to cancel pending executions.
+ *
+ * @example
+ * const throttledScroll = useThrottle(() => {
+ *   console.log('Scroll event');
+ * }, 200, { edges: ['leading', 'trailing'] });
+ *
+ * useEffect(() => {
+ *   window.addEventListener('scroll', throttledScroll);
+ *   return () => {
+ *     window.removeEventListener('scroll', throttledScroll);
+ *     throttledScroll.cancel();
+ *   };
+ * }, [throttledScroll]);
+ */
+declare function useThrottle<F extends (...args: any[]) => any>(callback: F, wait: number, options?: Parameters<typeof throttle>[2]): {
+    (...args: any[]): void;
+    cancel: () => void;
+};
+
+export { useThrottle };