react-simplikit 0.0.3 → 0.0.5

package/dist/components/ImpressionArea/index.d.ts

@@ -14,22 +14,19 @@ type Props<Tag extends ElementType> = React__default.ComponentPropsWithoutRef<Ta
  * and executes callbacks when the element enters or exits the viewport. This component uses the `useImpressionRef`
  * hook to track the element's visibility.
  *
- * @param {Object} props - The props for the component.
- * @param {ElementType} [props.as='div'] - The HTML tag to render. Defaults to `div`.
- * @param {string} [props.rootMargin] - Margin to adjust the detection area.
- * @param {number} [props.areaThreshold] - Minimum ratio of the element that must be visible (0 to 1).
- * @param {number} [props.timeThreshold] - Minimum time the element must be visible (in milliseconds).
- * @param {() => void} [props.onImpressionStart] - Callback function executed when the element enters the view.
- * @param {() => void} [props.onImpressionEnd] - Callback function executed when the element exits the view.
- * @param {Ref<HTMLElement>} [props.ref] - Reference to the element.
- * @param {React.ReactNode} [props.children] - Child elements to be rendered inside the component.
- * @param {string} [props.className] - Additional class names for styling.
+ * @param {ElementType} [as='div'] - The HTML tag to render. Defaults to `div`.
+ * @param {string} [rootMargin] - Margin to adjust the detection area.
+ * @param {number} [areaThreshold] - Minimum ratio of the element that must be visible (0 to 1).
+ * @param {number} [timeThreshold] - Minimum time the element must be visible (in milliseconds).
+ * @param {() => void} [onImpressionStart] - Callback function executed when the element enters the view.
+ * @param {() => void} [onImpressionEnd] - Callback function executed when the element exits the view.
+ * @param {Ref<HTMLElement>} [ref] - Reference to the element.
+ * @param {React.ReactNode} [children] - Child elements to be rendered inside the component.
+ * @param {string} [className] - Additional class names for styling.
  *
  * @returns {JSX.Element} A React component that tracks the visibility of its child elements.
  *
  * @example
- * import { ImpressionArea } from 'react-simplikit';
- *
  * function App() {
  *   return (
  *     <ImpressionArea
@@ -38,7 +35,7 @@ type Props<Tag extends ElementType> = React__default.ComponentPropsWithoutRef<Ta
  *       timeThreshold={1000}
  *       areaThreshold={0.5}
  *     >
- *       <div>Track my visibility!</div>
+ *       <div>Track me!</div>
  *     </ImpressionArea>
  *   );
  * }

package/dist/components/Separated/index.d.ts

@@ -2,7 +2,7 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
 type Props = {
-    with: ReactNode;
+    by: ReactNode;
     children: ReactNode;
 };
 /**
@@ -12,14 +12,14 @@ type Props = {
  *
  * @param {React.ReactNode} children - The child elements to render.
  *   Only valid React elements (`React.isValidElement`) will be rendered.
- * @param {React.ReactNode} with - The component to insert between child elements.
+ * @param {React.ReactNode} by - The component to insert between child elements.
  *
  * @returns {JSX.Element} A React component that separates children with a specified separator.
  *
  * @example
  * function App() {
  *   return (
- *     <Separated with={<Border type="padding24" />}>
+ *     <Separated by={<Border type="padding24" />}>
  *       {['hello', 'react', 'world'].map(item => (
  *         <div key={item}>{item}</div>
  *       ))}
@@ -33,6 +33,6 @@ type Props = {
  *   // <div>world</div>
  * }
  */
-declare function Separated({ children, with: separator }: Props): react_jsx_runtime.JSX.Element;
+declare function Separated({ children, by: separator }: Props): react_jsx_runtime.JSX.Element;
 
 export { Separated };

package/dist/components/Separated/index.js

@@ -27,7 +27,7 @@ module.exports = __toCommonJS(Separated_exports);
 // src/components/Separated/Separated.tsx
 var import_react = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
-function Separated({ children, with: separator }) {
+function Separated({ children, by: separator }) {
   const childrenArray = import_react.Children.toArray(children).filter(import_react.isValidElement);
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: childrenArray.map((child, i, { length }) => /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_react.Fragment, { children: [
     child,

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

@@ -16,9 +16,9 @@ import { DependencyList } from 'react';
  *   setData(data);
  *
  *   return () => {
- *     console.log('Cleanup on unmount or dependency change');
+ *     console.log('Cleanup on unmount or dependencies change');
  *   };
- * }, [dependency]);
+ * }, [dependencies]);
  */
 declare function useAsyncEffect(effect: () => Promise<void | (() => void)>, deps?: DependencyList): void;
 

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

@@ -5,11 +5,11 @@
  *
  * @param {boolean} [defaultValue=false] - The initial value of the state. Defaults to `false`.
  *
- * @returns {readonly [boolean, () => void, () => void, () => void]} A tuple containing:
- * - `boolean` - The current state value.
- * - `() => void` - A function to set the state to `true`.
- * - `() => void` - A function to set the state to `false`.
- * - `() => void` - A function to toggle the state.
+ * @returns {readonly [state: boolean, setTrue: () => void, setFalse: () => void, toggle: () => void]} A tuple containing:
+ * - state `boolean` - The current state value;
+ * - setTrue `() => void` - A function to set the state to `true`;
+ * - setFalse `() => void` - A function to set the state to `false`;
+ * - toggle `() => void` - A function to toggle the state;
  *
  * @example
  * const [open, openBottomSheet, closeBottomSheet, toggleBottomSheet] = useBooleanState(false);

package/dist/hooks/{useCallbackOnce → useCallbackOncePerRender}/index.d.ts

@@ -12,10 +12,10 @@ import { DependencyList } from 'react';
  * @returns {(...args: any[]) => void} A memoized function that will only execute once until dependencies change.
  *
  * @example
- * import { useCallbackOnce } from 'react-simplikit';
+ * import { useCallbackOncePerRender } from 'react-simplikit';
  *
  * function Component() {
- *   const handleOneTimeEvent = useCallbackOnce(() => {
+ *   const handleOneTimeEvent = useCallbackOncePerRender(() => {
  *     console.log('This will only run once');
  *   }, []);
  *
@@ -25,7 +25,7 @@ import { DependencyList } from 'react';
  * @example
  * // With dependencies
  * function TrackingComponent({ userId }: { userId: string }) {
- *   const trackUserVisit = useCallbackOnce(() => {
+ *   const trackUserVisit = useCallbackOncePerRender(() => {
  *     analytics.trackVisit(userId);
  *   }, [userId]);
  *
@@ -36,6 +36,6 @@ import { DependencyList } from 'react';
  *   return <div>User page</div>;
  * }
  */
-declare function useCallbackOnce<F extends (...args: any[]) => void>(callback: F, deps: DependencyList): (...args: Parameters<F>) => void;
+declare function useCallbackOncePerRender<F extends (...args: any[]) => void>(callback: F, deps: DependencyList): (...args: Parameters<F>) => void;
 
-export { useCallbackOnce };
+export { useCallbackOncePerRender };

package/dist/hooks/{useCallbackOnce → useCallbackOncePerRender}/index.js

@@ -17,14 +17,14 @@ var __copyProps = (to, from, except, desc) => {
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/hooks/useCallbackOnce/index.ts
-var useCallbackOnce_exports = {};
-__export(useCallbackOnce_exports, {
-  useCallbackOnce: () => useCallbackOnce
+// src/hooks/useCallbackOncePerRender/index.ts
+var useCallbackOncePerRender_exports = {};
+__export(useCallbackOncePerRender_exports, {
+  useCallbackOncePerRender: () => useCallbackOncePerRender
 });
-module.exports = __toCommonJS(useCallbackOnce_exports);
+module.exports = __toCommonJS(useCallbackOncePerRender_exports);
 
-// src/hooks/useCallbackOnce/useCallbackOnce.ts
+// src/hooks/useCallbackOncePerRender/useCallbackOncePerRender.ts
 var import_react2 = require("react");
 
 // src/hooks/usePreservedCallback/usePreservedCallback.ts
@@ -39,8 +39,8 @@ function usePreservedCallback(callback) {
   }, []);
 }
 
-// src/hooks/useCallbackOnce/useCallbackOnce.ts
-function useCallbackOnce(callback, deps) {
+// src/hooks/useCallbackOncePerRender/useCallbackOncePerRender.ts
+function useCallbackOncePerRender(callback, deps) {
   const hasFired = (0, import_react2.useRef)(false);
   (0, import_react2.useEffect)(() => {
     hasFired.current = false;
@@ -55,5 +55,5 @@ function useCallbackOnce(callback, deps) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  useCallbackOnce
+  useCallbackOncePerRender
 });

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

@@ -12,9 +12,10 @@ type DebounceOptions = {
  * `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 {object} [options] - Configuration options for debounce behavior.
+ * @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.
  *

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

@@ -10,14 +10,14 @@ type UseImpressionRefOptions = Partial<{
  * `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
+ * @param {UseImpressionRefOptions} options - Options for tracking the element's visibility.
+ * @param {() => void} options.onImpressionStart - Callback function executed when the element enters the view
+ * @param {() => void} options.onImpressionEnd - Callback function executed when the element exits the view
+ * @param {number} options.timeThreshold - Minimum time the element must be visible (in milliseconds)
+ * @param {number} options.areaThreshold - Minimum ratio of the element that must be visible (0 to 1)
+ * @param {string} options.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.
+ * @returns {(element: Element | null) => void} 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';

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

@@ -4,13 +4,13 @@ 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.
+ * @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 [string, (value: string) => void]} A tuple containing:
- * - `string` - The current state value.
- * - `(value: string) => void` - A function to update the state.
+ * @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';

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

@@ -3,12 +3,12 @@
  * `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`.
+ * @param {(entry: IntersectionObserverEntry) => void} 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 {IntersectionObserverInit} 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.
+ * @returns {(element: Element | null) => void} 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';

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

@@ -3,14 +3,13 @@
  * `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>]`:
+ * @returns {[loading: boolean, startLoading: <T>(promise: Promise<T>) => Promise<T>]} A tuple containing:
+ * - loading `boolean` - Represents the current loading state.
+ *    : The initial value is `false`.
+ *    : It is set to `true` when an asynchronous task is in progress;
  *
- * - `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.
+ * - startLoading `<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() {

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

@@ -6,10 +6,10 @@ type CleanupCallback = () => void;
  * `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.
+ * @param {(element: Element) => CleanupCallback | void} callback - A callback function that is executed when the element is set. This function can return a cleanup function.
+ * @param {DependencyList} 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.
+ * @returns {(element: Element | null) => void} 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';

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

@@ -27,9 +27,9 @@ type StorageStateOptionsWithDefaultValue<T> = StorageStateOptions<T> & {
  * @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.
+ * @returns {[state: Serializable<T> | undefined, setState: (value: SetStateAction<Serializable<T> | undefined>) => void]} A tuple:
+ * - state `Serializable<T> | undefined` - The current state value retrieved from storage;
+ * - setState `(value: SetStateAction<Serializable<T> | undefined>) => void` - A function to update and persist the state;
  *
  * @example
  * // Counter with persistent state

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

@@ -7,9 +7,9 @@ import * as React from 'react';
  *
  * @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.
+ * @returns {[state: boolean, toggle: () => void]} A tuple:
+ * - state `boolean` - The current state value;
+ * - toggle `() => void` - A function to toggle the state;
  *
  * @example
  * import { useToggle } from 'react-simplikit';

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { Separated } from './components/Separated/index.js';
 export { SwitchCase } from './components/SwitchCase/index.js';
 export { useAsyncEffect } from './hooks/useAsyncEffect/index.js';
 export { useBooleanState } from './hooks/useBooleanState/index.js';
-export { useCallbackOnce } from './hooks/useCallbackOnce/index.js';
+export { useCallbackOncePerRender } from './hooks/useCallbackOncePerRender/index.js';
 export { useDebounce } from './hooks/useDebounce/index.js';
 export { useImpressionRef } from './hooks/useImpressionRef/index.js';
 export { useInputState } from './hooks/useInputState/index.js';

package/dist/index.js

@@ -27,7 +27,7 @@ __export(index_exports, {
   mergeRefs: () => mergeRefs,
   useAsyncEffect: () => useAsyncEffect,
   useBooleanState: () => useBooleanState,
-  useCallbackOnce: () => useCallbackOnce,
+  useCallbackOncePerRender: () => useCallbackOncePerRender,
   useDebounce: () => useDebounce,
   useImpressionRef: () => useImpressionRef,
   useInputState: () => useInputState,
@@ -297,7 +297,7 @@ function ImpressionArea({
 // src/components/Separated/Separated.tsx
 var import_react7 = require("react");
 var import_jsx_runtime2 = require("react/jsx-runtime");
-function Separated({ children, with: separator }) {
+function Separated({ children, by: separator }) {
   const childrenArray = import_react7.Children.toArray(children).filter(import_react7.isValidElement);
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children: childrenArray.map((child, i, { length }) => /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_react7.Fragment, { children: [
     child,
@@ -341,9 +341,9 @@ var useBooleanState = (defaultValue = false) => {
   return [bool, setTrue, setFalse, toggle2];
 };
 
-// src/hooks/useCallbackOnce/useCallbackOnce.ts
+// src/hooks/useCallbackOncePerRender/useCallbackOncePerRender.ts
 var import_react10 = require("react");
-function useCallbackOnce(callback, deps) {
+function useCallbackOncePerRender(callback, deps) {
   const hasFired = (0, import_react10.useRef)(false);
   (0, import_react10.useEffect)(() => {
     hasFired.current = false;
@@ -741,7 +741,7 @@ function buildContext(contextName, defaultContextValues) {
   mergeRefs,
   useAsyncEffect,
   useBooleanState,
-  useCallbackOnce,
+  useCallbackOncePerRender,
   useDebounce,
   useImpressionRef,
   useInputState,

package/dist/utils/buildContext/index.d.ts

@@ -10,12 +10,12 @@ type ProviderProps<ContextValuesType> = (ContextValuesType & {
  * @description
  * `buildContext` is a helper function that reduces repetitive code when defining React Context.
  *
- * @param contextName - The name of the context.
- * @param defaultContextValues - The default values to be passed to the context.
+ * @param {string} contextName - The name of the context.
+ * @param {ContextValuesType} [defaultContextValues] - The default values to be passed to the context.
  *
- * @returns A tuple of the form [Provider, useContext]:
- * - `Provider`: The component that provides the context.
- * - `useContext`: The hook that uses the context.
+ * @returns {[Provider: (props: ProviderProps<ContextValuesType>) => JSX.Element, useContext: () => ContextValuesType]} A tuple of the form :
+ * - Provider `(props: ProviderProps<ContextValuesType>) => JSX.Element` - The component that provides the context;
+ * - useContext `() => ContextValuesType` - The hook that uses the context;
  *
  * @example
  * const [Provider, useContext] = buildContext<{ title: string }>('TestContext', null);

package/dist/utils/mergeRefs/index.d.ts

@@ -5,9 +5,9 @@ import { RefObject, RefCallback } from 'react';
  * This function takes multiple refs (RefObject or RefCallback) and returns a single ref that updates all provided refs.
  * It's useful when you need to pass multiple refs to a single element.
  *
- * @param refs - An array of refs to be merged. Each ref can be either a RefObject or RefCallback.
+ * @param {Array<RefObject<T> | RefCallback<T> | null | undefined>} refs - An array of refs to be merged. Each ref can be either a RefObject or RefCallback.
  *
- * @returns A single ref callback that updates all provided refs.
+ * @returns {RefCallback<T>} A single ref callback that updates all provided refs.
  *
  * @example
  * forwardRef(function Component(props, parentRef) {

package/esm/components/ImpressionArea/index.d.mts

@@ -14,22 +14,19 @@ type Props<Tag extends ElementType> = React__default.ComponentPropsWithoutRef<Ta
  * and executes callbacks when the element enters or exits the viewport. This component uses the `useImpressionRef`
  * hook to track the element's visibility.
  *
- * @param {Object} props - The props for the component.
- * @param {ElementType} [props.as='div'] - The HTML tag to render. Defaults to `div`.
- * @param {string} [props.rootMargin] - Margin to adjust the detection area.
- * @param {number} [props.areaThreshold] - Minimum ratio of the element that must be visible (0 to 1).
- * @param {number} [props.timeThreshold] - Minimum time the element must be visible (in milliseconds).
- * @param {() => void} [props.onImpressionStart] - Callback function executed when the element enters the view.
- * @param {() => void} [props.onImpressionEnd] - Callback function executed when the element exits the view.
- * @param {Ref<HTMLElement>} [props.ref] - Reference to the element.
- * @param {React.ReactNode} [props.children] - Child elements to be rendered inside the component.
- * @param {string} [props.className] - Additional class names for styling.
+ * @param {ElementType} [as='div'] - The HTML tag to render. Defaults to `div`.
+ * @param {string} [rootMargin] - Margin to adjust the detection area.
+ * @param {number} [areaThreshold] - Minimum ratio of the element that must be visible (0 to 1).
+ * @param {number} [timeThreshold] - Minimum time the element must be visible (in milliseconds).
+ * @param {() => void} [onImpressionStart] - Callback function executed when the element enters the view.
+ * @param {() => void} [onImpressionEnd] - Callback function executed when the element exits the view.
+ * @param {Ref<HTMLElement>} [ref] - Reference to the element.
+ * @param {React.ReactNode} [children] - Child elements to be rendered inside the component.
+ * @param {string} [className] - Additional class names for styling.
  *
  * @returns {JSX.Element} A React component that tracks the visibility of its child elements.
  *
  * @example
- * import { ImpressionArea } from 'react-simplikit';
- *
  * function App() {
  *   return (
  *     <ImpressionArea
@@ -38,7 +35,7 @@ type Props<Tag extends ElementType> = React__default.ComponentPropsWithoutRef<Ta
  *       timeThreshold={1000}
  *       areaThreshold={0.5}
  *     >
- *       <div>Track my visibility!</div>
+ *       <div>Track me!</div>
  *     </ImpressionArea>
  *   );
  * }

package/esm/components/Separated/index.d.mts

@@ -2,7 +2,7 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
 type Props = {
-    with: ReactNode;
+    by: ReactNode;
     children: ReactNode;
 };
 /**
@@ -12,14 +12,14 @@ type Props = {
  *
  * @param {React.ReactNode} children - The child elements to render.
  *   Only valid React elements (`React.isValidElement`) will be rendered.
- * @param {React.ReactNode} with - The component to insert between child elements.
+ * @param {React.ReactNode} by - The component to insert between child elements.
  *
  * @returns {JSX.Element} A React component that separates children with a specified separator.
  *
  * @example
  * function App() {
  *   return (
- *     <Separated with={<Border type="padding24" />}>
+ *     <Separated by={<Border type="padding24" />}>
  *       {['hello', 'react', 'world'].map(item => (
  *         <div key={item}>{item}</div>
  *       ))}
@@ -33,6 +33,6 @@ type Props = {
  *   // <div>world</div>
  * }
  */
-declare function Separated({ children, with: separator }: Props): react_jsx_runtime.JSX.Element;
+declare function Separated({ children, by: separator }: Props): react_jsx_runtime.JSX.Element;
 
 export { Separated };

package/esm/components/Separated/index.mjs

@@ -1,7 +1,7 @@
 // src/components/Separated/Separated.tsx
 import { Children, Fragment, isValidElement } from "react";
 import { Fragment as Fragment2, jsx, jsxs } from "react/jsx-runtime";
-function Separated({ children, with: separator }) {
+function Separated({ children, by: separator }) {
   const childrenArray = Children.toArray(children).filter(isValidElement);
   return /* @__PURE__ */ jsx(Fragment2, { children: childrenArray.map((child, i, { length }) => /* @__PURE__ */ jsxs(Fragment, { children: [
     child,

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

@@ -16,9 +16,9 @@ import { DependencyList } from 'react';
  *   setData(data);
  *
  *   return () => {
- *     console.log('Cleanup on unmount or dependency change');
+ *     console.log('Cleanup on unmount or dependencies change');
  *   };
- * }, [dependency]);
+ * }, [dependencies]);
  */
 declare function useAsyncEffect(effect: () => Promise<void | (() => void)>, deps?: DependencyList): void;
 

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

@@ -5,11 +5,11 @@
  *
  * @param {boolean} [defaultValue=false] - The initial value of the state. Defaults to `false`.
  *
- * @returns {readonly [boolean, () => void, () => void, () => void]} A tuple containing:
- * - `boolean` - The current state value.
- * - `() => void` - A function to set the state to `true`.
- * - `() => void` - A function to set the state to `false`.
- * - `() => void` - A function to toggle the state.
+ * @returns {readonly [state: boolean, setTrue: () => void, setFalse: () => void, toggle: () => void]} A tuple containing:
+ * - state `boolean` - The current state value;
+ * - setTrue `() => void` - A function to set the state to `true`;
+ * - setFalse `() => void` - A function to set the state to `false`;
+ * - toggle `() => void` - A function to toggle the state;
  *
  * @example
  * const [open, openBottomSheet, closeBottomSheet, toggleBottomSheet] = useBooleanState(false);

package/esm/hooks/{useCallbackOnce → useCallbackOncePerRender}/index.d.mts

@@ -12,10 +12,10 @@ import { DependencyList } from 'react';
  * @returns {(...args: any[]) => void} A memoized function that will only execute once until dependencies change.
  *
  * @example
- * import { useCallbackOnce } from 'react-simplikit';
+ * import { useCallbackOncePerRender } from 'react-simplikit';
  *
  * function Component() {
- *   const handleOneTimeEvent = useCallbackOnce(() => {
+ *   const handleOneTimeEvent = useCallbackOncePerRender(() => {
  *     console.log('This will only run once');
  *   }, []);
  *
@@ -25,7 +25,7 @@ import { DependencyList } from 'react';
  * @example
  * // With dependencies
  * function TrackingComponent({ userId }: { userId: string }) {
- *   const trackUserVisit = useCallbackOnce(() => {
+ *   const trackUserVisit = useCallbackOncePerRender(() => {
  *     analytics.trackVisit(userId);
  *   }, [userId]);
  *
@@ -36,6 +36,6 @@ import { DependencyList } from 'react';
  *   return <div>User page</div>;
  * }
  */
-declare function useCallbackOnce<F extends (...args: any[]) => void>(callback: F, deps: DependencyList): (...args: Parameters<F>) => void;
+declare function useCallbackOncePerRender<F extends (...args: any[]) => void>(callback: F, deps: DependencyList): (...args: Parameters<F>) => void;
 
-export { useCallbackOnce };
+export { useCallbackOncePerRender };

package/esm/hooks/{useCallbackOnce → useCallbackOncePerRender}/index.mjs

@@ -1,4 +1,4 @@
-// src/hooks/useCallbackOnce/useCallbackOnce.ts
+// src/hooks/useCallbackOncePerRender/useCallbackOncePerRender.ts
 import { useEffect as useEffect2, useRef as useRef2 } from "react";
 
 // src/hooks/usePreservedCallback/usePreservedCallback.ts
@@ -13,8 +13,8 @@ function usePreservedCallback(callback) {
   }, []);
 }
 
-// src/hooks/useCallbackOnce/useCallbackOnce.ts
-function useCallbackOnce(callback, deps) {
+// src/hooks/useCallbackOncePerRender/useCallbackOncePerRender.ts
+function useCallbackOncePerRender(callback, deps) {
   const hasFired = useRef2(false);
   useEffect2(() => {
     hasFired.current = false;
@@ -28,5 +28,5 @@ function useCallbackOnce(callback, deps) {
   });
 }
 export {
-  useCallbackOnce
+  useCallbackOncePerRender
 };

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

@@ -12,9 +12,10 @@ type DebounceOptions = {
  * `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 {object} [options] - Configuration options for debounce behavior.
+ * @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.
  *

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

@@ -10,14 +10,14 @@ type UseImpressionRefOptions = Partial<{
  * `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
+ * @param {UseImpressionRefOptions} options - Options for tracking the element's visibility.
+ * @param {() => void} options.onImpressionStart - Callback function executed when the element enters the view
+ * @param {() => void} options.onImpressionEnd - Callback function executed when the element exits the view
+ * @param {number} options.timeThreshold - Minimum time the element must be visible (in milliseconds)
+ * @param {number} options.areaThreshold - Minimum ratio of the element that must be visible (0 to 1)
+ * @param {string} options.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.
+ * @returns {(element: Element | null) => void} 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';

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

@@ -4,13 +4,13 @@ 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.
+ * @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 [string, (value: string) => void]} A tuple containing:
- * - `string` - The current state value.
- * - `(value: string) => void` - A function to update the state.
+ * @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';

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

@@ -3,12 +3,12 @@
  * `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`.
+ * @param {(entry: IntersectionObserverEntry) => void} 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 {IntersectionObserverInit} 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.
+ * @returns {(element: Element | null) => void} 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';

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

@@ -3,14 +3,13 @@
  * `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>]`:
+ * @returns {[loading: boolean, startLoading: <T>(promise: Promise<T>) => Promise<T>]} A tuple containing:
+ * - loading `boolean` - Represents the current loading state.
+ *    : The initial value is `false`.
+ *    : It is set to `true` when an asynchronous task is in progress;
  *
- * - `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.
+ * - startLoading `<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() {

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

@@ -6,10 +6,10 @@ type CleanupCallback = () => void;
  * `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.
+ * @param {(element: Element) => CleanupCallback | void} callback - A callback function that is executed when the element is set. This function can return a cleanup function.
+ * @param {DependencyList} 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.
+ * @returns {(element: Element | null) => void} 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';

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

@@ -27,9 +27,9 @@ type StorageStateOptionsWithDefaultValue<T> = StorageStateOptions<T> & {
  * @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.
+ * @returns {[state: Serializable<T> | undefined, setState: (value: SetStateAction<Serializable<T> | undefined>) => void]} A tuple:
+ * - state `Serializable<T> | undefined` - The current state value retrieved from storage;
+ * - setState `(value: SetStateAction<Serializable<T> | undefined>) => void` - A function to update and persist the state;
  *
  * @example
  * // Counter with persistent state

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

@@ -7,9 +7,9 @@ import * as React from 'react';
  *
  * @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.
+ * @returns {[state: boolean, toggle: () => void]} A tuple:
+ * - state `boolean` - The current state value;
+ * - toggle `() => void` - A function to toggle the state;
  *
  * @example
  * import { useToggle } from 'react-simplikit';

package/esm/index.d.mts

@@ -3,7 +3,7 @@ export { Separated } from './components/Separated/index.mjs';
 export { SwitchCase } from './components/SwitchCase/index.mjs';
 export { useAsyncEffect } from './hooks/useAsyncEffect/index.mjs';
 export { useBooleanState } from './hooks/useBooleanState/index.mjs';
-export { useCallbackOnce } from './hooks/useCallbackOnce/index.mjs';
+export { useCallbackOncePerRender } from './hooks/useCallbackOncePerRender/index.mjs';
 export { useDebounce } from './hooks/useDebounce/index.mjs';
 export { useImpressionRef } from './hooks/useImpressionRef/index.mjs';
 export { useInputState } from './hooks/useInputState/index.mjs';

package/esm/index.mjs

@@ -248,7 +248,7 @@ function ImpressionArea({
 // src/components/Separated/Separated.tsx
 import { Children, Fragment, isValidElement } from "react";
 import { Fragment as Fragment2, jsx as jsx2, jsxs } from "react/jsx-runtime";
-function Separated({ children, with: separator }) {
+function Separated({ children, by: separator }) {
   const childrenArray = Children.toArray(children).filter(isValidElement);
   return /* @__PURE__ */ jsx2(Fragment2, { children: childrenArray.map((child, i, { length }) => /* @__PURE__ */ jsxs(Fragment, { children: [
     child,
@@ -292,9 +292,9 @@ var useBooleanState = (defaultValue = false) => {
   return [bool, setTrue, setFalse, toggle2];
 };
 
-// src/hooks/useCallbackOnce/useCallbackOnce.ts
+// src/hooks/useCallbackOncePerRender/useCallbackOncePerRender.ts
 import { useEffect as useEffect5, useRef as useRef5 } from "react";
-function useCallbackOnce(callback, deps) {
+function useCallbackOncePerRender(callback, deps) {
   const hasFired = useRef5(false);
   useEffect5(() => {
     hasFired.current = false;
@@ -691,7 +691,7 @@ export {
   mergeRefs,
   useAsyncEffect,
   useBooleanState,
-  useCallbackOnce,
+  useCallbackOncePerRender,
   useDebounce,
   useImpressionRef,
   useInputState,

package/esm/utils/buildContext/index.d.mts

@@ -10,12 +10,12 @@ type ProviderProps<ContextValuesType> = (ContextValuesType & {
  * @description
  * `buildContext` is a helper function that reduces repetitive code when defining React Context.
  *
- * @param contextName - The name of the context.
- * @param defaultContextValues - The default values to be passed to the context.
+ * @param {string} contextName - The name of the context.
+ * @param {ContextValuesType} [defaultContextValues] - The default values to be passed to the context.
  *
- * @returns A tuple of the form [Provider, useContext]:
- * - `Provider`: The component that provides the context.
- * - `useContext`: The hook that uses the context.
+ * @returns {[Provider: (props: ProviderProps<ContextValuesType>) => JSX.Element, useContext: () => ContextValuesType]} A tuple of the form :
+ * - Provider `(props: ProviderProps<ContextValuesType>) => JSX.Element` - The component that provides the context;
+ * - useContext `() => ContextValuesType` - The hook that uses the context;
  *
  * @example
  * const [Provider, useContext] = buildContext<{ title: string }>('TestContext', null);

package/esm/utils/mergeRefs/index.d.mts

@@ -5,9 +5,9 @@ import { RefObject, RefCallback } from 'react';
  * This function takes multiple refs (RefObject or RefCallback) and returns a single ref that updates all provided refs.
  * It's useful when you need to pass multiple refs to a single element.
  *
- * @param refs - An array of refs to be merged. Each ref can be either a RefObject or RefCallback.
+ * @param {Array<RefObject<T> | RefCallback<T> | null | undefined>} refs - An array of refs to be merged. Each ref can be either a RefObject or RefCallback.
  *
- * @returns A single ref callback that updates all provided refs.
+ * @returns {RefCallback<T>} A single ref callback that updates all provided refs.
  *
  * @example
  * forwardRef(function Component(props, parentRef) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-simplikit",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "main": "./dist/index.js",
   "sideEffects": false,
   "files": [
@@ -8,6 +8,7 @@
     "esm/**/*"
   ],
   "scripts": {
+    "docs:gen": "tsx .scripts/index.ts generate-docs",
     "docs:dev": "vitepress dev",
     "docs:build": "vitepress build",
     "docs:preview": "vitepress preview",
@@ -34,6 +35,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.16.0",
+    "@openai/openai": "npm:@jsr/openai__openai@^4.93.0",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
@@ -41,7 +43,10 @@
     "@types/node": "^22.10.2",
     "@types/react": "^19.0.7",
     "@vitest/coverage-v8": "^2.1.8",
+    "commander": "^13.1.0",
+    "comment-parser": "^1.4.1",
     "corepack": "^0.30.0",
+    "dotenv": "^16.4.7",
     "esbuild": "^0.24.0",
     "eslint": "^9.16.0",
     "eslint-config-prettier": "^9.1.0",
@@ -54,11 +59,14 @@
     "fast-glob": "^3.3.3",
     "globals": "^15.13.0",
     "jsdom": "^25.0.1",
+    "listr2": "^8.2.5",
+    "ora": "^8.2.0",
     "prettier": "^3.4.2",
     "prettier-plugin-sort-re-exports": "^0.1.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "typescript-eslint": "^8.18.0",
     "vitepress": "^1.5.0",