react-simplikit 0.0.2 → 0.0.4

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

@@ -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 { useCallbackOncePerRender } from 'react-simplikit';
+ *
+ * function Component() {
+ *   const handleOneTimeEvent = useCallbackOncePerRender(() => {
+ *     console.log('This will only run once');
+ *   }, []);
+ *
+ *   return <button onClick={handleOneTimeEvent}>Click me</button>;
+ * }
+ *
+ * @example
+ * // With dependencies
+ * function TrackingComponent({ userId }: { userId: string }) {
+ *   const trackUserVisit = useCallbackOncePerRender(() => {
+ *     analytics.trackVisit(userId);
+ *   }, [userId]);
+ *
+ *   useEffect(() => {
+ *     trackUserVisit();
+ *   }, [trackUserVisit]);
+ *
+ *   return <div>User page</div>;
+ * }
+ */
+declare function useCallbackOncePerRender<F extends (...args: any[]) => void>(callback: F, deps: DependencyList): (...args: Parameters<F>) => void;
+
+export { useCallbackOncePerRender };

package/dist/hooks/useCallbackOncePerRender/index.js

@@ -0,0 +1,59 @@
+"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/useCallbackOncePerRender/index.ts
+var useCallbackOncePerRender_exports = {};
+__export(useCallbackOncePerRender_exports, {
+  useCallbackOncePerRender: () => useCallbackOncePerRender
+});
+module.exports = __toCommonJS(useCallbackOncePerRender_exports);
+
+// src/hooks/useCallbackOncePerRender/useCallbackOncePerRender.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/useCallbackOncePerRender/useCallbackOncePerRender.ts
+function useCallbackOncePerRender(callback, deps) {
+  const hasFired = (0, import_react2.useRef)(false);
+  (0, import_react2.useEffect)(() => {
+    hasFired.current = false;
+  }, deps);
+  return usePreservedCallback((...args) => {
+    if (hasFired.current) {
+      return;
+    }
+    callback(...args);
+    hasFired.current = true;
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useCallbackOncePerRender
+});

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

@@ -0,0 +1,48 @@
+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.
+ *
+ * @template {(...args: unknown[]) => unknown} F - The type of the callback function.
+ * @param {F} callback - The function to debounce.
+ * @param {number} wait - The number of milliseconds to delay the function execution.
+ * @param {DebounceOptions} [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/dist/hooks/useDebounce/index.js

@@ -0,0 +1,123 @@
+"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/useDebounce/index.ts
+var useDebounce_exports = {};
+__export(useDebounce_exports, {
+  useDebounce: () => useDebounce
+});
+module.exports = __toCommonJS(useDebounce_exports);
+
+// src/hooks/useDebounce/useDebounce.ts
+var import_react2 = require("react");
+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/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 = (0, import_react3.useMemo)(() => {
+    const _edges = [];
+    if (leading) {
+      _edges.push("leading");
+    }
+    if (trailing) {
+      _edges.push("trailing");
+    }
+    return _edges;
+  }, [leading, trailing]);
+  const debounced = (0, import_react3.useMemo)(() => {
+    return debounce(preservedCallback, wait, { edges });
+  }, [preservedCallback, wait, edges]);
+  (0, import_react2.useEffect)(() => {
+    return () => {
+      debounced.cancel();
+    };
+  }, [debounced]);
+  return debounced;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useDebounce
+});

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

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

@@ -0,0 +1,237 @@
+"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/useImpressionRef/index.ts
+var useImpressionRef_exports = {};
+__export(useImpressionRef_exports, {
+  useImpressionRef: () => useImpressionRef
+});
+module.exports = __toCommonJS(useImpressionRef_exports);
+
+// src/hooks/useImpressionRef/useImpressionRef.ts
+var import_react6 = require("react");
+
+// src/hooks/useIntersectionObserver/useIntersectionObserver.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/useRefEffect/useRefEffect.ts
+var import_react2 = require("react");
+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;
+}
+
+// src/hooks/useIntersectionObserver/useIntersectionObserver.ts
+function useIntersectionObserver(callback, options) {
+  const preservedCallback = usePreservedCallback(callback);
+  const observer = (0, import_react3.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
+var import_react4 = require("react");
+function useVisibilityEvent(callback, options = {}) {
+  const handleVisibilityChange = (0, import_react4.useCallback)(() => {
+    callback(document.visibilityState);
+  }, [callback]);
+  (0, import_react4.useEffect)(() => {
+    if (options?.immediate ?? false) {
+      handleVisibilityChange();
+    }
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    return () => {
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+    };
+  }, [handleVisibilityChange, options?.immediate]);
+}
+
+// src/hooks/useImpressionRef/useDebouncedCallback.ts
+var import_react5 = require("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 = (0, import_react5.useRef)({ value: false, clearPreviousDebounce: () => {
+  } });
+  (0, import_react5.useEffect)(() => {
+    const current = ref.current;
+    return () => {
+      current.clearPreviousDebounce();
+    };
+  }, []);
+  return (0, import_react5.useCallback)(
+    (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 = (0, import_react6.useRef)(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 }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useImpressionRef
+});

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

@@ -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=(v: string) => v] - A function to transform the input value.
+ *   Defaults to an identity function that returns the input unchanged.
+ *
+ * @returns {readonly [value: string, onChange: (value: string) => void]} A tuple containing:
+ * - value `string` - The current state value.
+ * - onChange `(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/dist/hooks/useInputState/index.js

@@ -0,0 +1,45 @@
+"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/useInputState/index.ts
+var useInputState_exports = {};
+__export(useInputState_exports, {
+  useInputState: () => useInputState
+});
+module.exports = __toCommonJS(useInputState_exports);
+
+// src/hooks/useInputState/useInputState.ts
+var import_react = require("react");
+function useInputState(initialValue = "", transformValue = echo) {
+  const [value, setValue] = (0, import_react.useState)(initialValue);
+  const handleValueChange = (0, import_react.useCallback)(
+    ({ target: { value: value2 } }) => {
+      setValue(transformValue(value2));
+    },
+    [transformValue]
+  );
+  return [value, handleValueChange];
+}
+function echo(v) {
+  return v;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useInputState
+});

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

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