Add more documentation for hooks #16

README.md

@@ -33,11 +33,12 @@ import { useEffectOnMount, Hideable, useIntersectionObserver } from "transmish";
 
 ### Hooks
 
-- useAsyncEffect
-- useEffectOnMount
-- useIntersectionObserver
-- useInterval
-- useBooleanState
+- [useAsyncEffect](/src/useAsyncEffect/README.md)
+- [useBooleanState](/src/useBooleanState/README.md)
+- [useEffectOnMount](/src/useEffectOnMount/README.md)
+- [useIntersectionObserver](/src/useIntersectionObserver/README.md)
+- [useInterval](/src/useInterval/README.md)
+- [useReducedMotion](/src/useReducedMotion/README.md)
 
 ## Development
 

cjs/useBooleanState/index.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Custom React hook for managing boolean state.
+ * @param {boolean} [defaultState=false] The default state value.
+ * @returns {{
+*   value: boolean,
+*   toTrue: () => void,
+*   toFalse: () => void,
+*   toggle: () => void
+* }} An object containing the boolean state value and functions to manipulate it.
+*/
 export declare const useBooleanState: (defaultState?: boolean) => {
     value: boolean;
     toTrue: () => void;

cjs/useBooleanState/index.js

@@ -2,6 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useBooleanState = void 0;
 const react_1 = require("react");
+/**
+ * Custom React hook for managing boolean state.
+ * @param {boolean} [defaultState=false] The default state value.
+ * @returns {{
+*   value: boolean,
+*   toTrue: () => void,
+*   toFalse: () => void,
+*   toggle: () => void
+* }} An object containing the boolean state value and functions to manipulate it.
+*/
 const useBooleanState = (defaultState = false) => {
     const [value, setValue] = (0, react_1.useState)(defaultState);
     const toTrue = () => {

cjs/useIntersectionObserver/index.d.ts

@@ -8,6 +8,7 @@
  *      @property rootMargin <undefined|string>: Margin around the root.
  *      @property threshold <number|number[]>: Either a single number or an array of numbers which indicate at what
  *      percentage of the target's visibility the observer's callback should be executed.
+ * @returns {{containerRef: React.MutableRefObject<HTMLDivElement | null>}} An object containing a ref to the container element.
  */
 export declare const useIntersectionObserver: (callback: (entries: IntersectionObserverEntry[]) => void, options: IntersectionObserverInit) => {
     containerRef: import("react").MutableRefObject<HTMLDivElement | null>;

cjs/useIntersectionObserver/index.js

@@ -12,6 +12,7 @@ const react_1 = require("react");
  *      @property rootMargin <undefined|string>: Margin around the root.
  *      @property threshold <number|number[]>: Either a single number or an array of numbers which indicate at what
  *      percentage of the target's visibility the observer's callback should be executed.
+ * @returns {{containerRef: React.MutableRefObject<HTMLDivElement | null>}} An object containing a ref to the container element.
  */
 const useIntersectionObserver = (callback, options) => {
     const containerRef = (0, react_1.useRef)(null);

cjs/useInterval/index.d.ts

@@ -1 +1,7 @@
+/**
+ * Custom React hook for creating an interval that executes a callback function.
+ * @param {function} callback The function to be executed at each interval.
+ * @param {number|null} delay The delay in milliseconds between each execution of the callback function. If `null`, the interval is cleared.
+ * @returns {function} A function to stop the interval.
+ */
 export declare const useInterval: (callback: () => void, delay: number | null) => () => void;

cjs/useInterval/index.js

@@ -2,6 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useInterval = void 0;
 const react_1 = require("react");
+/**
+ * Custom React hook for creating an interval that executes a callback function.
+ * @param {function} callback The function to be executed at each interval.
+ * @param {number|null} delay The delay in milliseconds between each execution of the callback function. If `null`, the interval is cleared.
+ * @returns {function} A function to stop the interval.
+ */
 const useInterval = (callback, delay) => {
     const savedCallback = (0, react_1.useRef)(callback);
     const intervalId = (0, react_1.useRef)();

esm/useBooleanState/index.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Custom React hook for managing boolean state.
+ * @param {boolean} [defaultState=false] The default state value.
+ * @returns {{
+*   value: boolean,
+*   toTrue: () => void,
+*   toFalse: () => void,
+*   toggle: () => void
+* }} An object containing the boolean state value and functions to manipulate it.
+*/
 export declare const useBooleanState: (defaultState?: boolean) => {
     value: boolean;
     toTrue: () => void;

esm/useBooleanState/index.js

@@ -1,4 +1,14 @@
 import { useState } from 'react';
+/**
+ * Custom React hook for managing boolean state.
+ * @param {boolean} [defaultState=false] The default state value.
+ * @returns {{
+*   value: boolean,
+*   toTrue: () => void,
+*   toFalse: () => void,
+*   toggle: () => void
+* }} An object containing the boolean state value and functions to manipulate it.
+*/
 export const useBooleanState = (defaultState = false) => {
     const [value, setValue] = useState(defaultState);
     const toTrue = () => {

esm/useIntersectionObserver/index.d.ts

@@ -8,6 +8,7 @@
  *      @property rootMargin <undefined|string>: Margin around the root.
  *      @property threshold <number|number[]>: Either a single number or an array of numbers which indicate at what
  *      percentage of the target's visibility the observer's callback should be executed.
+ * @returns {{containerRef: React.MutableRefObject<HTMLDivElement | null>}} An object containing a ref to the container element.
  */
 export declare const useIntersectionObserver: (callback: (entries: IntersectionObserverEntry[]) => void, options: IntersectionObserverInit) => {
     containerRef: import("react").MutableRefObject<HTMLDivElement | null>;

esm/useIntersectionObserver/index.js

@@ -9,6 +9,7 @@ import { useEffect, useRef } from 'react';
  *      @property rootMargin <undefined|string>: Margin around the root.
  *      @property threshold <number|number[]>: Either a single number or an array of numbers which indicate at what
  *      percentage of the target's visibility the observer's callback should be executed.
+ * @returns {{containerRef: React.MutableRefObject<HTMLDivElement | null>}} An object containing a ref to the container element.
  */
 export const useIntersectionObserver = (callback, options) => {
     const containerRef = useRef(null);

esm/useInterval/index.d.ts

@@ -1 +1,7 @@
+/**
+ * Custom React hook for creating an interval that executes a callback function.
+ * @param {function} callback The function to be executed at each interval.
+ * @param {number|null} delay The delay in milliseconds between each execution of the callback function. If `null`, the interval is cleared.
+ * @returns {function} A function to stop the interval.
+ */
 export declare const useInterval: (callback: () => void, delay: number | null) => () => void;

esm/useInterval/index.js

@@ -1,4 +1,10 @@
 import { useEffect, useLayoutEffect, useRef } from 'react';
+/**
+ * Custom React hook for creating an interval that executes a callback function.
+ * @param {function} callback The function to be executed at each interval.
+ * @param {number|null} delay The delay in milliseconds between each execution of the callback function. If `null`, the interval is cleared.
+ * @returns {function} A function to stop the interval.
+ */
 export const useInterval = (callback, delay) => {
     const savedCallback = useRef(callback);
     const intervalId = useRef();

src/useAsyncEffect/README.md

@@ -0,0 +1,51 @@
+# useAsyncEffect React Hook
+A custom React hook for handling common state requirements for tracking asynchronous behavior.
+
+## Description
+This hook simplifies the management of asynchronous operations in React components by providing state variables and callbacks to track loading, data, and error states. It executes an asynchronous function and provides the result, error, and loading state.
+
+## Usage
+
+```tsx
+import React from 'react';
+import { useAsyncEffect } from 'transmish';
+
+const MyComponent = () => {
+    // Define an async function to be executed
+    const fetchData = async () => {
+        // Simulate a delay
+        await new Promise(resolve => setTimeout(resolve, 1000));
+        // Fetch data from an API
+        const response = await fetch('https://api.example.com/data');
+        if (!response.ok) {
+            throw new Error('Failed to fetch data');
+        }
+        return response.json();
+    };
+
+    // Use useAsyncEffect hook
+    const { data, loading, error, fireCallback } = useAsyncEffect(fetchData, {
+        // Optional callbacks
+        onComplete: (data) => console.log('Data fetched successfully:', data),
+        onError: (error) => console.error('Error fetching data:', error),
+        onReset: () => console.log('State reset'),
+    });
+
+    // Render loading state
+    if (loading) return <div>Loading...</div>;
+
+    // Render error state
+    if (error) return <div>Error: {error.message}</div>;
+
+    // Render data
+    return (
+        <div>
+            <h1>Data:</h1>
+            <pre>{JSON.stringify(data, null, 2)}</pre>
+            <button onClick={() => fireCallback()}>Fetch Data</button>
+        </div>
+    );
+};
+
+export default MyComponent;
+```

src/useBooleanState/README.md

@@ -0,0 +1,25 @@
+# useBooleanState React Hook
+
+A custom React hook for managing boolean state. This hook provides functionality to manage boolean state within React components. It includes functions to set the state to true, false, or toggle between the two states.
+
+## Usage
+
+```tsx
+import React from 'react';
+import { useBooleanState } from 'transmish';
+
+const MyComponent = () => {
+    const { value, toTrue, toFalse, toggle } = useBooleanState(false);
+
+    return (
+        <div>
+            <p>Current state: {value.toString()}</p>
+            <button onClick={toTrue}>Set to true</button>
+            <button onClick={toFalse}>Set to false</button>
+            <button onClick={toggle}>Toggle</button>
+        </div>
+    );
+};
+
+export default MyComponent;
+```

src/useBooleanState/index.tsx

@@ -1,11 +1,22 @@
 import { useState } from 'react';
 
+/**
+ * Custom React hook for managing boolean state.
+ * @param {boolean} [defaultState=false] The default state value.
+ * @returns {{
+*   value: boolean,
+*   toTrue: () => void,
+*   toFalse: () => void,
+*   toggle: () => void
+* }} An object containing the boolean state value and functions to manipulate it.
+*/
 export const useBooleanState = (defaultState = false) => {
     const [value, setValue] = useState(defaultState);
 
     const toTrue = () => {
         setValue(true);
     };
+
     const toFalse = () => {
         setValue(false);
     };

src/useEffectOnMount/README.md

@@ -0,0 +1,43 @@
+# useEffectOnMount React Hook
+
+A custom React hook for handling common state requirements for tracking async behavior when a component mounts.
+
+## Usage
+
+```tsx
+import React, { useState } from 'react';
+import { useEffectOnMount } from 'transmish';
+
+const MyComponent = () => {
+    // Define an async function to be executed
+    const fetchData = async ({ url }) => {
+        const response = await fetch(url);
+        const data = await response.json();
+        return data;
+    };
+
+    // Define initial props (optional)
+    const initialProps = {
+        url: 'https://api.example.com/data',
+    };
+
+    // Use useEffectOnMount hook
+    const { loading, data, error } = useEffectOnMount(fetchData, { initialProps });
+
+    // Render loading state
+    if (loading) return <div>Loading...</div>;
+
+    // Render error state
+    if (error) return <div>Error</div>;
+
+    // Render data
+    return (
+        <div>
+            <h1>Data:</h1>
+            <pre>{JSON.stringify(data, null, 2)}</pre>
+        </div>
+    );
+};
+
+export default MyComponent;
+```

src/useIntersectionObserver/README.md

@@ -0,0 +1,37 @@
+# useIntersectionObserver Hook
+
+A custom React hook for executing a callback function when a component is scrolled into view using the IntersectionObserver API.
+
+## Usage
+
+```tsx
+import React from 'react';
+import { useIntersectionObserver } from 'transmish';
+
+const MyComponent = () => {
+    const handleIntersection = (entries) => {
+        entries.forEach(entry => {
+            if (entry.isIntersecting) {
+                // Do something when component is in view
+                console.log('Component is in view!');
+            }
+        });
+    };
+
+    const options = {
+        root: null, // Use the viewport as the root
+        rootMargin: '0px', // No margin around the root
+        threshold: 0.5 // Trigger when 50% of the component is in view
+    };
+
+    const { containerRef } = useIntersectionObserver(handleIntersection, options);
+
+    return (
+        <div ref={containerRef} style={{ height: '100vh', backgroundColor: 'lightgray' }}>
+            {/* Your component content */}
+        </div>
+    );
+};
+
+export default MyComponent;
+```

src/useIntersectionObserver/index.ts

@@ -10,6 +10,7 @@ import { useEffect, useRef } from 'react';
  *      @property rootMargin <undefined|string>: Margin around the root.
  *      @property threshold <number|number[]>: Either a single number or an array of numbers which indicate at what
  *      percentage of the target's visibility the observer's callback should be executed.
+ * @returns {{containerRef: React.MutableRefObject<HTMLDivElement | null>}} An object containing a ref to the container element.
  */
 export const useIntersectionObserver = (
     callback: (entries: IntersectionObserverEntry[]) => void,

src/useInterval/README.md

@@ -0,0 +1,31 @@
+# useInterval Hook
+
+A custom React hook for creating intervals that execute a callback function.
+
+## Usage
+
+```tsx
+import React, { useState } from 'react';
+import { useInterval } from 'transmish';
+
+const MyComponent = () => {
+  const [count, setCount] = useState(0);
+
+  // Define your callback function
+  const incrementCount = () => {
+    setCount((prevCount) => prevCount + 1);
+  };
+
+  // Use the useInterval hook
+  // This will increment count every 1000ms (1 second)
+  useInterval(incrementCount, 1000);
+
+  return (
+    <div>
+      <p>Count: {count}</p>
+    </div>
+  );
+};
+
+export default MyComponent;
+```

src/useInterval/index.tsx

@@ -1,5 +1,11 @@
 import { useEffect, useLayoutEffect, useRef } from 'react';
 
+/**
+ * Custom React hook for creating an interval that executes a callback function.
+ * @param {function} callback The function to be executed at each interval.
+ * @param {number|null} delay The delay in milliseconds between each execution of the callback function. If `null`, the interval is cleared.
+ * @returns {function} A function to stop the interval.
+ */
 export const useInterval = (callback: () => void, delay: number | null) => {
     const savedCallback = useRef(callback);
     const intervalId = useRef<number>();