react-simplikit 0.0.2 → 0.0.4

package/dist/hooks/useRefEffect/index.js

@@ -0,0 +1,68 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/hooks/useRefEffect/index.ts
+var useRefEffect_exports = {};
+__export(useRefEffect_exports, {
+  useRefEffect: () => useRefEffect
+});
+module.exports = __toCommonJS(useRefEffect_exports);
+
+// src/hooks/useRefEffect/useRefEffect.ts
+var import_react2 = require("react");
+
+// src/hooks/usePreservedCallback/usePreservedCallback.ts
+var import_react = require("react");
+function usePreservedCallback(callback) {
+  const callbackRef = (0, import_react.useRef)(callback);
+  (0, import_react.useEffect)(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+  return (0, import_react.useCallback)((...args) => {
+    return callbackRef.current(...args);
+  }, []);
+}
+
+// src/hooks/useRefEffect/useRefEffect.ts
+function useRefEffect(callback, deps) {
+  const preservedCallback = usePreservedCallback(callback);
+  const cleanupCallbackRef = (0, import_react2.useRef)(() => {
+  });
+  const effect = (0, import_react2.useCallback)(
+    (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;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useRefEffect
+});

package/dist/hooks/useStorageState/index.d.ts

@@ -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/dist/hooks/useStorageState/index.js

@@ -0,0 +1,168 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/hooks/useStorageState/index.ts
+var useStorageState_exports = {};
+__export(useStorageState_exports, {
+  useStorageState: () => useStorageState
+});
+module.exports = __toCommonJS(useStorageState_exports);
+
+// src/hooks/useStorageState/useStorageState.ts
+var import_react = require("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 = (0, import_react.useRef)({
+    data: null,
+    parsed: defaultValue
+  });
+  const getSnapshot = (0, import_react.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 = (0, import_react.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 = (0, import_react.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];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useStorageState
+});

package/dist/hooks/useThrottle/index.d.ts

@@ -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 };

package/dist/hooks/useThrottle/index.js

@@ -0,0 +1,147 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/hooks/useThrottle/index.ts
+var useThrottle_exports = {};
+__export(useThrottle_exports, {
+  useThrottle: () => useThrottle
+});
+module.exports = __toCommonJS(useThrottle_exports);
+
+// src/hooks/useThrottle/useThrottle.ts
+var import_react3 = require("react");
+
+// src/hooks/usePreservedCallback/usePreservedCallback.ts
+var import_react = require("react");
+function usePreservedCallback(callback) {
+  const callbackRef = (0, import_react.useRef)(callback);
+  (0, import_react.useEffect)(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+  return (0, import_react.useCallback)((...args) => {
+    return callbackRef.current(...args);
+  }, []);
+}
+
+// src/hooks/usePreservedReference/usePreservedReference.ts
+var import_react2 = require("react");
+function usePreservedReference(value, areValuesEqual = areDeeplyEqual) {
+  const ref = (0, import_react2.useRef)(value);
+  return (0, import_react2.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);
+}
+
+// src/hooks/useDebounce/debounce.ts
+function debounce(func, debounceMs, { edges = ["leading", "trailing"] } = {}) {
+  let pendingThis = void 0;
+  let pendingArgs = null;
+  const leading = edges != null && edges.includes("leading");
+  const trailing = edges == null || edges.includes("trailing");
+  const invoke = () => {
+    if (pendingArgs !== null) {
+      func.apply(pendingThis, pendingArgs);
+      pendingThis = void 0;
+      pendingArgs = null;
+    }
+  };
+  const onTimerEnd = () => {
+    if (trailing) {
+      invoke();
+    }
+    cancel();
+  };
+  let timeoutId = null;
+  const schedule = () => {
+    if (timeoutId != null) {
+      clearTimeout(timeoutId);
+    }
+    timeoutId = setTimeout(() => {
+      timeoutId = null;
+      onTimerEnd();
+    }, debounceMs);
+  };
+  const cancelTimer = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+  };
+  const cancel = () => {
+    cancelTimer();
+    pendingThis = void 0;
+    pendingArgs = null;
+  };
+  const debounced = function(...args) {
+    pendingThis = this;
+    pendingArgs = args;
+    const isFirstCall = timeoutId == null;
+    schedule();
+    if (leading && isFirstCall) {
+      invoke();
+    }
+  };
+  debounced.cancel = cancel;
+  return debounced;
+}
+
+// src/hooks/useThrottle/throttle.ts
+function throttle(func, throttleMs, { edges = ["leading", "trailing"] } = {}) {
+  let pendingAt = null;
+  const debounced = debounce(func, throttleMs, { edges });
+  const throttled = function(...args) {
+    if (pendingAt == null) {
+      pendingAt = Date.now();
+    } else {
+      if (Date.now() - pendingAt >= throttleMs) {
+        pendingAt = Date.now();
+        debounced.cancel();
+        debounced(...args);
+      }
+    }
+    debounced(...args);
+  };
+  throttled.cancel = debounced.cancel;
+  return throttled;
+}
+
+// src/hooks/useThrottle/useThrottle.ts
+function useThrottle(callback, wait, options) {
+  const preservedCallback = usePreservedCallback(callback);
+  const preservedOptions = usePreservedReference(options ?? {});
+  const throttledCallback = (0, import_react3.useMemo)(() => {
+    return throttle(preservedCallback, wait, preservedOptions);
+  }, [preservedOptions, preservedCallback, wait]);
+  (0, import_react3.useEffect)(() => {
+    return () => {
+      throttledCallback.cancel();
+    };
+  }, [throttledCallback]);
+  return throttledCallback;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useThrottle
+});

package/dist/hooks/useTimeout/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @description
+ * `useTimeout` is a React hook that executes a callback function after a specified delay.
+ * It manages `window.setTimeout` in accordance with the React lifecycle, ensuring cleanup on unmount or when dependencies change.
+ *
+ * @param {() => void} callback - The function to be executed after the delay.
+ * @param {number} [delay=0] - The time in milliseconds to wait before executing the callback.
+ *
+ * @example
+ * // Updating a title after a delay
+ * import { useTimeout } from 'react-simplikit';
+ * import { useState } from 'react';
+ *
+ * function Example() {
+ *   const [title, setTitle] = useState('');
+ *
+ *   useTimeout(() => {
+ *     setTitle('Searching for products...');
+ *   }, 2000);
+ *
+ *   useTimeout(() => {
+ *     setTitle('Almost done...');
+ *   }, 4000);
+ *
+ *   return <div>{title}</div>;
+ * }
+ */
+declare function useTimeout(callback: () => void, delay?: number): void;
+
+export { useTimeout };

package/dist/hooks/useTimeout/index.js

@@ -0,0 +1,53 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/hooks/useTimeout/index.ts
+var useTimeout_exports = {};
+__export(useTimeout_exports, {
+  useTimeout: () => useTimeout
+});
+module.exports = __toCommonJS(useTimeout_exports);
+
+// src/hooks/useTimeout/useTimeout.ts
+var import_react2 = require("react");
+
+// src/hooks/usePreservedCallback/usePreservedCallback.ts
+var import_react = require("react");
+function usePreservedCallback(callback) {
+  const callbackRef = (0, import_react.useRef)(callback);
+  (0, import_react.useEffect)(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+  return (0, import_react.useCallback)((...args) => {
+    return callbackRef.current(...args);
+  }, []);
+}
+
+// src/hooks/useTimeout/useTimeout.ts
+function useTimeout(callback, delay = 0) {
+  const preservedCallback = usePreservedCallback(callback);
+  (0, import_react2.useEffect)(() => {
+    const timeoutId = window.setTimeout(preservedCallback, delay);
+    return () => window.clearTimeout(timeoutId);
+  }, [delay, preservedCallback]);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useTimeout
+});

package/dist/hooks/useToggle/index.d.ts

@@ -0,0 +1,30 @@
+import * as React from 'react';
+
+/**
+ * @description
+ * `useToggle` is a React hook that simplifies managing a boolean state.
+ * It provides a function to toggle the state between `true` and `false`.
+ *
+ * @param {boolean} [initialValue=false] - The initial state value. Defaults to `false`.
+ *
+ * @returns {[boolean, () => void]} A tuple:
+ * - `state`: The current state value.
+ * - `toggle`: A function to toggle the state.
+ *
+ * @example
+ * import { useToggle } from 'react-simplikit';
+ *
+ * function Component() {
+ *   const [open, toggle] = useToggle(false);
+ *
+ *   return (
+ *     <div>
+ *       <p>Bottom Sheet state: {open ? 'opened' : 'closed'}</p>
+ *       <button onClick={toggle}>Toggle</button>
+ *     </div>
+ *   );
+ * }
+ */
+declare function useToggle(initialValue?: boolean): [boolean, React.ActionDispatch<[]>];
+
+export { useToggle };

package/dist/hooks/useToggle/index.js

@@ -0,0 +1,36 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/hooks/useToggle/index.ts
+var useToggle_exports = {};
+__export(useToggle_exports, {
+  useToggle: () => useToggle
+});
+module.exports = __toCommonJS(useToggle_exports);
+
+// src/hooks/useToggle/useToggle.ts
+var import_react = require("react");
+function useToggle(initialValue = false) {
+  return (0, import_react.useReducer)(toggle, initialValue);
+}
+var toggle = (state) => !state;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useToggle
+});

package/dist/hooks/useVisibilityEvent/index.d.ts

@@ -0,0 +1,27 @@
+type Options = {
+    immediate?: boolean;
+};
+/**
+ * @description
+ * A React hook that listens to changes in the document's visibility state and triggers a callback.
+ *
+ * @param {(visibilityState: 'visible' | 'hidden') => void} callback - A function to be called
+ * when the visibility state changes. It receives the current visibility state ('visible' or 'hidden') as an argument.
+ * @param {object} [options] - Optional configuration for the hook.
+ * @param {boolean} [options.immediate=false] - If true, the callback is invoked immediately upon mounting
+ * with the current visibility state.
+ *
+ * @example
+ * import { useVisibilityEvent } from 'react-simplikit';
+ *
+ * function Component() {
+ *   useVisibilityEvent(visibilityState => {
+ *     console.log(`Document is now ${visibilityState}`);
+ *   });
+ *
+ *   return <p>Check the console for visibility changes.</p>;
+ * }
+ */
+declare function useVisibilityEvent(callback: (visibilityState: 'visible' | 'hidden') => void, options?: Options): void;
+
+export { useVisibilityEvent };