react-simplikit 0.0.2 → 0.0.3

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

@@ -0,0 +1,41 @@
+import { DependencyList } from 'react';
+
+/**
+ * @description
+ * A React hook that ensures a callback function is executed only once, regardless of
+ * how many times it's called. This is useful for one-time operations that should not
+ * be repeated, even if the component re-renders.
+ *
+ * @param {() => void} callback - The callback function to be executed once.
+ * @param {DependencyList} deps - Dependencies array that will trigger a new one-time execution when changed.
+ *
+ * @returns {(...args: any[]) => void} A memoized function that will only execute once until dependencies change.
+ *
+ * @example
+ * import { useCallbackOnce } from 'react-simplikit';
+ *
+ * function Component() {
+ *   const handleOneTimeEvent = useCallbackOnce(() => {
+ *     console.log('This will only run once');
+ *   }, []);
+ *
+ *   return <button onClick={handleOneTimeEvent}>Click me</button>;
+ * }
+ *
+ * @example
+ * // With dependencies
+ * function TrackingComponent({ userId }: { userId: string }) {
+ *   const trackUserVisit = useCallbackOnce(() => {
+ *     analytics.trackVisit(userId);
+ *   }, [userId]);
+ *
+ *   useEffect(() => {
+ *     trackUserVisit();
+ *   }, [trackUserVisit]);
+ *
+ *   return <div>User page</div>;
+ * }
+ */
+declare function useCallbackOnce<F extends (...args: any[]) => void>(callback: F, deps: DependencyList): (...args: Parameters<F>) => void;
+
+export { useCallbackOnce };

package/esm/hooks/useCallbackOnce/index.mjs

@@ -0,0 +1,32 @@
+// src/hooks/useCallbackOnce/useCallbackOnce.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/useCallbackOnce/useCallbackOnce.ts
+function useCallbackOnce(callback, deps) {
+  const hasFired = useRef2(false);
+  useEffect2(() => {
+    hasFired.current = false;
+  }, deps);
+  return usePreservedCallback((...args) => {
+    if (hasFired.current) {
+      return;
+    }
+    callback(...args);
+    hasFired.current = true;
+  });
+}
+export {
+  useCallbackOnce
+};

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

@@ -0,0 +1,47 @@
+type DebouncedFunction<F extends (...args: any[]) => void> = {
+    (...args: Parameters<F>): void;
+    cancel: () => void;
+};
+
+type DebounceOptions = {
+    leading?: boolean;
+    trailing?: boolean;
+};
+/**
+ * @description
+ * `useDebounce` is a React hook that returns a debounced version of the provided callback function.
+ * It helps optimize event handling by delaying function execution and grouping multiple calls into one.
+ *
+ * @param {F} callback - The function to debounce.
+ * @param {number} wait - The number of milliseconds to delay the function execution.
+ * @param {object} [options] - Configuration options for debounce behavior.
+ * @param {boolean} [options.leading=false] - If `true`, the function is called at the start of the sequence.
+ * @param {boolean} [options.trailing=true] - If `true`, the function is called at the end of the sequence.
+ *
+ * @returns {F & { cancel: () => void }} A debounced function that delays invoking the callback.
+ *   It also includes a `cancel` method to cancel any pending debounced execution.
+ *
+ * @example
+ * function SearchInput() {
+ *   const [query, setQuery] = useState('');
+ *
+ *   const debouncedSearch = useDebounce((value: string) => {
+ *     // Actual API call
+ *     searchAPI(value);
+ *   }, 300);
+ *
+ *   return (
+ *     <input
+ *       value={query}
+ *       onChange={e => {
+ *         setQuery(e.target.value);
+ *         debouncedSearch(e.target.value);
+ *       }}
+ *       placeholder="Enter search term"
+ *     />
+ *   );
+ * }
+ */
+declare function useDebounce<F extends (...args: any[]) => unknown>(callback: F, wait: number, options?: DebounceOptions): DebouncedFunction<F>;
+
+export { useDebounce };

package/esm/hooks/useDebounce/index.mjs

@@ -0,0 +1,96 @@
+// src/hooks/useDebounce/useDebounce.ts
+import { useEffect as useEffect2 } from "react";
+import { useMemo } 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/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/useDebounce/useDebounce.ts
+function useDebounce(callback, wait, options = {}) {
+  const preservedCallback = usePreservedCallback(callback);
+  const { leading = false, trailing = true } = options;
+  const edges = useMemo(() => {
+    const _edges = [];
+    if (leading) {
+      _edges.push("leading");
+    }
+    if (trailing) {
+      _edges.push("trailing");
+    }
+    return _edges;
+  }, [leading, trailing]);
+  const debounced = useMemo(() => {
+    return debounce(preservedCallback, wait, { edges });
+  }, [preservedCallback, wait, edges]);
+  useEffect2(() => {
+    return () => {
+      debounced.cancel();
+    };
+  }, [debounced]);
+  return debounced;
+}
+export {
+  useDebounce
+};

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

@@ -0,0 +1,38 @@
+type UseImpressionRefOptions = Partial<{
+    onImpressionStart: () => void;
+    onImpressionEnd: () => void;
+    rootMargin: string;
+    areaThreshold: number;
+    timeThreshold: number;
+}>;
+/**
+ * @description
+ * `useImpressionRef` is a custom hook that measures the time a specific DOM element is visible on the screen and executes callbacks when the element enters or exits the viewport.
+ * This hook uses `IntersectionObserver` and the `Visibility API` to track the element's visibility.
+ *
+ * @param options - An options object for tracking the element's visibility.
+ *                  - `onImpressionStart`: Callback function executed when the element enters the view
+ *                  - `onImpressionEnd`: Callback function executed when the element exits the view
+ *                  - `timeThreshold`: Minimum time the element must be visible (in milliseconds)
+ *                  - `areaThreshold`: Minimum ratio of the element that must be visible (0 to 1)
+ *                  - `rootMargin`: Margin to adjust the detection area
+ *
+ * @returns A function to set the element. Attach this function to the `ref` attribute, and the callbacks will be executed whenever the element's visibility changes.
+ *
+ * @example
+ * import { useImpressionRef } from 'react-simplikit';
+ *
+ * function Component() {
+ *   const ref = useImpressionRef<HTMLDivElement>({
+ *     onImpressionStart: () => console.log('Element entered view'),
+ *     onImpressionEnd: () => console.log('Element exited view'),
+ *     timeThreshold: 1000,
+ *     areaThreshold: 0.5,
+ *   });
+ *
+ *   return <div ref={ref}>Track my visibility!</div>;
+ * }
+ */
+declare function useImpressionRef<Element extends HTMLElement>({ onImpressionStart, onImpressionEnd, rootMargin, areaThreshold, timeThreshold, }: UseImpressionRefOptions): (element: Element | null) => void;
+
+export { type UseImpressionRefOptions, useImpressionRef };

package/esm/hooks/useImpressionRef/index.mjs

@@ -0,0 +1,210 @@
+// src/hooks/useImpressionRef/useImpressionRef.ts
+import { useRef as useRef4 } from "react";
+
+// src/hooks/useIntersectionObserver/useIntersectionObserver.ts
+import { useMemo } 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
+import { useCallback as useCallback2, useRef as useRef2 } from "react";
+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;
+}
+
+// src/hooks/useIntersectionObserver/useIntersectionObserver.ts
+function useIntersectionObserver(callback, options) {
+  const preservedCallback = usePreservedCallback(callback);
+  const observer = useMemo(() => {
+    if (typeof IntersectionObserver === "undefined") {
+      return;
+    }
+    return new IntersectionObserver(([entry]) => {
+      preservedCallback(entry);
+    }, options);
+  }, [preservedCallback, options]);
+  return useRefEffect(
+    (element) => {
+      observer?.observe(element);
+      return () => {
+        observer?.unobserve(element);
+      };
+    },
+    [preservedCallback, options]
+  );
+}
+
+// src/hooks/useVisibilityEvent/useVisibilityEvent.ts
+import { useCallback as useCallback3, useEffect as useEffect2 } from "react";
+function useVisibilityEvent(callback, options = {}) {
+  const handleVisibilityChange = useCallback3(() => {
+    callback(document.visibilityState);
+  }, [callback]);
+  useEffect2(() => {
+    if (options?.immediate ?? false) {
+      handleVisibilityChange();
+    }
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    return () => {
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+    };
+  }, [handleVisibilityChange, options?.immediate]);
+}
+
+// src/hooks/useImpressionRef/useDebouncedCallback.ts
+import { useCallback as useCallback4, useEffect as useEffect3, useRef as useRef3 } from "react";
+
+// 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/useImpressionRef/useDebouncedCallback.ts
+function useDebouncedCallback({
+  onChange,
+  timeThreshold
+}) {
+  const handleChange = usePreservedCallback(onChange);
+  const ref = useRef3({ value: false, clearPreviousDebounce: () => {
+  } });
+  useEffect3(() => {
+    const current = ref.current;
+    return () => {
+      current.clearPreviousDebounce();
+    };
+  }, []);
+  return useCallback4(
+    (nextValue) => {
+      if (nextValue === ref.current.value) {
+        return;
+      }
+      const debounced = debounce(() => {
+        handleChange(nextValue);
+        ref.current.value = nextValue;
+      }, timeThreshold);
+      ref.current.clearPreviousDebounce();
+      debounced();
+      ref.current.clearPreviousDebounce = debounced.cancel;
+    },
+    [handleChange, timeThreshold]
+  );
+}
+
+// src/hooks/useImpressionRef/useImpressionRef.ts
+function useImpressionRef({
+  onImpressionStart = () => {
+  },
+  onImpressionEnd = () => {
+  },
+  rootMargin,
+  areaThreshold = 0,
+  timeThreshold = 0
+}) {
+  const impressionStartHandler = usePreservedCallback(onImpressionStart);
+  const impressionEndHandler = usePreservedCallback(onImpressionEnd);
+  const isIntersectingRef = useRef4(false);
+  const impressionEventHandler = useDebouncedCallback({
+    timeThreshold,
+    onChange: (impressed) => {
+      (impressed ? impressionStartHandler : impressionEndHandler)();
+    }
+  });
+  useVisibilityEvent((documentVisible) => {
+    if (!isIntersectingRef.current) {
+      return;
+    }
+    impressionEventHandler(documentVisible === "visible");
+  });
+  return useIntersectionObserver(
+    (entry) => {
+      if (document.visibilityState === "hidden") {
+        return;
+      }
+      const currentRatio = entry.intersectionRatio;
+      const isIntersecting = areaThreshold === 0 ? entry.isIntersecting : currentRatio >= areaThreshold;
+      isIntersectingRef.current = isIntersecting;
+      impressionEventHandler(isIntersecting);
+    },
+    { rootMargin, threshold: areaThreshold }
+  );
+}
+export {
+  useImpressionRef
+};

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

@@ -0,0 +1,27 @@
+import { ChangeEventHandler } from 'react';
+
+/**
+ * @description
+ * `useInputState` is a React hook that manages an input state with optional value transformation.
+ *
+ * @param {string} initialValue - The initial value of the input. Defaults to an empty string (`""`).
+ * @param {(value: string) => string} [transformValue] - A function to transform the input value.
+ *   Defaults to an identity function that returns the input unchanged.
+ *
+ * @returns {readonly [string, (value: string) => void]} A tuple containing:
+ * - `string` - The current state value.
+ * - `(value: string) => void` - A function to update the state.
+ *
+ * @example
+ * import { useInputState } from 'react-simplikit';
+ *
+ * function Example() {
+ *   const [value, setValue] = useInputState('');
+ *   return <input type="text" value={value} onChange={setValue} />;
+ * }
+ */
+declare function useInputState(initialValue?: string, transformValue?: (value: string) => string): readonly [string, ChangeEventHandler<HTMLElement & {
+    value: string;
+}>];
+
+export { useInputState };

package/esm/hooks/useInputState/index.mjs

@@ -0,0 +1,18 @@
+// src/hooks/useInputState/useInputState.ts
+import { useCallback, useState } from "react";
+function useInputState(initialValue = "", transformValue = echo) {
+  const [value, setValue] = useState(initialValue);
+  const handleValueChange = useCallback(
+    ({ target: { value: value2 } }) => {
+      setValue(transformValue(value2));
+    },
+    [transformValue]
+  );
+  return [value, handleValueChange];
+}
+function echo(v) {
+  return v;
+}
+export {
+  useInputState
+};

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

@@ -0,0 +1,33 @@
+/**
+ * @description
+ * `useIntersectionObserver` is a custom hook that detects whether a specific DOM element is visible on the screen.
+ * This hook uses the `IntersectionObserver` API to execute a callback when the element enters or exits the viewport.
+ *
+ * @param callback - A callback function that is executed when the visibility of the element changes.
+ *                   You can check `entry.isIntersecting` to determine if the element is in view.
+ * @param options - Options for the `IntersectionObserver`.
+ *                  You can specify values such as `root`, `rootMargin`, and `threshold`.
+ *
+ * @returns A function to set the element. Attach this function to the `ref` attribute, and the `callback` will be executed whenever the element's visibility changes.
+ *
+ * @example
+ * import { useIntersectionObserver } from 'react-simplikit';
+ *
+ * function Component() {
+ *   const ref = useIntersectionObserver<HTMLDivElement>(
+ *     entry => {
+ *       if (entry.isIntersecting) {
+ *         console.log('Element is in view:', entry.target);
+ *       } else {
+ *         console.log('Element is out of view:', entry.target);
+ *       }
+ *     },
+ *     { threshold: 0.5 }
+ *   );
+ *
+ *   return <div ref={ref}>Observe me!</div>;
+ * }
+ */
+declare function useIntersectionObserver<Element extends HTMLElement>(callback: (entry: IntersectionObserverEntry) => void, options: IntersectionObserverInit): (element: Element | null) => void;
+
+export { useIntersectionObserver };

package/esm/hooks/useIntersectionObserver/index.mjs

@@ -0,0 +1,64 @@
+// src/hooks/useIntersectionObserver/useIntersectionObserver.ts
+import { useMemo } 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
+import { useCallback as useCallback2, useRef as useRef2 } from "react";
+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;
+}
+
+// src/hooks/useIntersectionObserver/useIntersectionObserver.ts
+function useIntersectionObserver(callback, options) {
+  const preservedCallback = usePreservedCallback(callback);
+  const observer = useMemo(() => {
+    if (typeof IntersectionObserver === "undefined") {
+      return;
+    }
+    return new IntersectionObserver(([entry]) => {
+      preservedCallback(entry);
+    }, options);
+  }, [preservedCallback, options]);
+  return useRefEffect(
+    (element) => {
+      observer?.observe(element);
+      return () => {
+        observer?.unobserve(element);
+      };
+    },
+    [preservedCallback, options]
+  );
+}
+export {
+  useIntersectionObserver
+};

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

@@ -0,0 +1,37 @@
+type IntervalOptions = number | {
+    delay: number;
+    immediate?: boolean;
+    enabled?: boolean;
+};
+/**
+ * @description
+ * `useInterval` is a React hook that executes a function at a specified interval.
+ * It is useful for timers, polling data, and other recurring tasks.
+ *
+ * @param {() => void} callback - The function to be executed periodically.
+ * @param {number | { delay: number; enabled?: boolean; immediate?: boolean }} options - Configures the interval behavior.
+ * @param {number} options.delay - The interval duration in milliseconds. If `null`, the interval will not run.
+ * @param {boolean} [options.immediate=false] - If `true`, executes immediately before starting the interval.
+ * @param {boolean} [options.enabled=true] - If `false`, the interval will not run.
+ *
+ * @example
+ * import { useInterval } from 'react-simplikit';
+ * import { useState } from 'react';
+ *
+ * function Timer() {
+ *   const [time, setTime] = useState(0);
+ *
+ *   useInterval(() => {
+ *     setTime(prev => prev + 1);
+ *   }, 1000);
+ *
+ *   return (
+ *     <div>
+ *       <p>{time} seconds</p>
+ *     </div>
+ *   );
+ * }
+ */
+declare function useInterval(callback: () => void, options: IntervalOptions): void;
+
+export { useInterval };

package/esm/hooks/useInterval/index.mjs

@@ -0,0 +1,37 @@
+// src/hooks/useInterval/useInterval.ts
+import { useEffect as useEffect2 } 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/useInterval/useInterval.ts
+function useInterval(callback, options) {
+  const delay = typeof options === "number" ? options : options.delay;
+  const immediate = typeof options === "number" ? false : options.immediate;
+  const enabled = typeof options === "number" ? true : options.enabled ?? true;
+  const preservedCallback = usePreservedCallback(callback);
+  useEffect2(() => {
+    if (immediate === true && enabled) {
+      preservedCallback();
+    }
+  }, [immediate, preservedCallback, enabled]);
+  useEffect2(() => {
+    if (!enabled) {
+      return;
+    }
+    const id = window.setInterval(preservedCallback, delay);
+    return () => window.clearInterval(id);
+  }, [delay, preservedCallback, enabled]);
+}
+export {
+  useInterval
+};