diff --git a/README.md b/README.md index 2b3619e..b7395f5 100644 --- a/README.md +++ b/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 diff --git a/cjs/useBooleanState/index.d.ts b/cjs/useBooleanState/index.d.ts index f1d052c..7143c0f 100644 --- a/cjs/useBooleanState/index.d.ts +++ b/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; diff --git a/cjs/useBooleanState/index.js b/cjs/useBooleanState/index.js index 11eb669..64d7c94 100644 --- a/cjs/useBooleanState/index.js +++ b/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 = () => { diff --git a/cjs/useIntersectionObserver/index.d.ts b/cjs/useIntersectionObserver/index.d.ts index 5996675..11a118a 100644 --- a/cjs/useIntersectionObserver/index.d.ts +++ b/cjs/useIntersectionObserver/index.d.ts @@ -8,6 +8,7 @@ * @property rootMargin : Margin around the root. * @property threshold : 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}} An object containing a ref to the container element. */ export declare const useIntersectionObserver: (callback: (entries: IntersectionObserverEntry[]) => void, options: IntersectionObserverInit) => { containerRef: import("react").MutableRefObject; diff --git a/cjs/useIntersectionObserver/index.js b/cjs/useIntersectionObserver/index.js index 6ee0e12..5839284 100644 --- a/cjs/useIntersectionObserver/index.js +++ b/cjs/useIntersectionObserver/index.js @@ -12,6 +12,7 @@ const react_1 = require("react"); * @property rootMargin : Margin around the root. * @property threshold : 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}} An object containing a ref to the container element. */ const useIntersectionObserver = (callback, options) => { const containerRef = (0, react_1.useRef)(null); diff --git a/cjs/useInterval/index.d.ts b/cjs/useInterval/index.d.ts index de6ffc7..7f36727 100644 --- a/cjs/useInterval/index.d.ts +++ b/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; diff --git a/cjs/useInterval/index.js b/cjs/useInterval/index.js index 322d8a1..e34aa97 100644 --- a/cjs/useInterval/index.js +++ b/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)(); diff --git a/esm/useBooleanState/index.d.ts b/esm/useBooleanState/index.d.ts index f1d052c..7143c0f 100644 --- a/esm/useBooleanState/index.d.ts +++ b/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; diff --git a/esm/useBooleanState/index.js b/esm/useBooleanState/index.js index 1cdfc36..3f55612 100644 --- a/esm/useBooleanState/index.js +++ b/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 = () => { diff --git a/esm/useIntersectionObserver/index.d.ts b/esm/useIntersectionObserver/index.d.ts index 5996675..11a118a 100644 --- a/esm/useIntersectionObserver/index.d.ts +++ b/esm/useIntersectionObserver/index.d.ts @@ -8,6 +8,7 @@ * @property rootMargin : Margin around the root. * @property threshold : 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}} An object containing a ref to the container element. */ export declare const useIntersectionObserver: (callback: (entries: IntersectionObserverEntry[]) => void, options: IntersectionObserverInit) => { containerRef: import("react").MutableRefObject; diff --git a/esm/useIntersectionObserver/index.js b/esm/useIntersectionObserver/index.js index e900401..b067ee8 100644 --- a/esm/useIntersectionObserver/index.js +++ b/esm/useIntersectionObserver/index.js @@ -9,6 +9,7 @@ import { useEffect, useRef } from 'react'; * @property rootMargin : Margin around the root. * @property threshold : 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}} An object containing a ref to the container element. */ export const useIntersectionObserver = (callback, options) => { const containerRef = useRef(null); diff --git a/esm/useInterval/index.d.ts b/esm/useInterval/index.d.ts index de6ffc7..7f36727 100644 --- a/esm/useInterval/index.d.ts +++ b/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; diff --git a/esm/useInterval/index.js b/esm/useInterval/index.js index 25e22b8..58e47cf 100644 --- a/esm/useInterval/index.js +++ b/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(); diff --git a/src/useAsyncEffect/README.md b/src/useAsyncEffect/README.md new file mode 100644 index 0000000..5d5a568 --- /dev/null +++ b/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
Loading...
; + + // Render error state + if (error) return
Error: {error.message}
; + + // Render data + return ( +
+

Data:

+ 
{JSON.stringify(data, null, 2)}
+ +
+ ); +}; + +export default MyComponent; +``` \ No newline at end of file diff --git a/src/useBooleanState/README.md b/src/useBooleanState/README.md new file mode 100644 index 0000000..bf94b84 --- /dev/null +++ b/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 ( +
+

Current state: {value.toString()}

+ + + +
+ ); +}; + +export default MyComponent; +``` \ No newline at end of file diff --git a/src/useBooleanState/index.tsx b/src/useBooleanState/index.tsx index 03cc2b3..6efdec8 100644 --- a/src/useBooleanState/index.tsx +++ b/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); }; diff --git a/src/useEffectOnMount/README.md b/src/useEffectOnMount/README.md new file mode 100644 index 0000000..eaa0251 --- /dev/null +++ b/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
Loading...
; + + // Render error state + if (error) return
Error
; + + // Render data + return ( +
+

Data:

+ 
{JSON.stringify(data, null, 2)}
+
+ ); +}; + +export default MyComponent; +``` \ No newline at end of file diff --git a/src/useIntersectionObserver/README.md b/src/useIntersectionObserver/README.md new file mode 100644 index 0000000..c4b42c8 --- /dev/null +++ b/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 ( +
+ {/* Your component content */} +
+ ); +}; + +export default MyComponent; +``` \ No newline at end of file diff --git a/src/useIntersectionObserver/index.ts b/src/useIntersectionObserver/index.ts index 9cfcebc..039123a 100644 --- a/src/useIntersectionObserver/index.ts +++ b/src/useIntersectionObserver/index.ts @@ -10,6 +10,7 @@ import { useEffect, useRef } from 'react'; * @property rootMargin : Margin around the root. * @property threshold : 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}} An object containing a ref to the container element. */ export const useIntersectionObserver = ( callback: (entries: IntersectionObserverEntry[]) => void, diff --git a/src/useInterval/README.md b/src/useInterval/README.md new file mode 100644 index 0000000..d0cd53a --- /dev/null +++ b/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 ( +
+

Count: {count}

+
+ ); +}; + +export default MyComponent; +``` \ No newline at end of file diff --git a/src/useInterval/index.tsx b/src/useInterval/index.tsx index 6efbf72..e3e9ab0 100644 --- a/src/useInterval/index.tsx +++ b/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();