Draggable item...
{isDragged &&
is being dragged }
@@ -112,14 +111,11 @@ const MyComponent = () => {
#### π What not to do
-- You can't use the returned handler setter asynchronously, it will not have any effect but changing the handler possibly leading to bugs in
- your code.
-- Absolutely avoid using `useDragEvents` handler setters to replace the standard drag handler props.
-- `useDragEvents` is meant to be used to abstract more complex hooks that need to control the drag n drop, for example:
- the drag-around hook.
-- Using `useDragEvents` handlers instead of the classic props approach it's just as bad as it sounds since you'll lose the React
- SyntheticEvent performance boost.
-- If you were doing something like the following, please keep doing it:
+- Using the returned callback setter asynchronously won't have any effect and could introduce bugs into your code, so it should be avoided.
+- Standard drag handler props (like `onDragStart`) should not be replaced with useDragEvents callback setters.
+- useDragEvents is designed to be used for more complex hooks that require control over drag and drop.
+- Replacing classic props with useDragEvents handlers can lead to a loss in performance due to the lack of React SyntheticEvent support.
+- If you were already using a method similar to the following, it is recommended to continue doing so:
```jsx harmony static noedit
const MyComponent = (props) => {
@@ -129,4 +125,33 @@ const MyComponent = (props) => {
);
};
-```
+```
+
+
+### Types
+
+```typescript static
+import { type RefObject } from 'react';
+import { type CallbackSetter } from './shared/types';
+export interface UseDragEventsResult {
+ onDrag: CallbackSetter
;
+ onDrop: CallbackSetter;
+ onDragEnter: CallbackSetter;
+ onDragEnd: CallbackSetter;
+ onDragExit: CallbackSetter;
+ onDragLeave: CallbackSetter;
+ onDragOver: CallbackSetter;
+ onDragStart: CallbackSetter;
+}
+/**
+ * Returns an object of callback setters to handle the drag-related events.
+ * It accepts a DOM ref representing the events target (where attach the events to).
+ *
+ * Returned callback setters: `onDrag`, `onDrop`, `onDragEnter`, `onDragEnd`, `onDragExit`, `onDragLeave`,
+ * `onDragOver`, `onDragStart`;
+ */
+declare const useDragEvents: (targetRef: RefObject, isDraggable?: boolean) => Readonly;
+export default useDragEvents;
+
+```
+
\ No newline at end of file
diff --git a/docs/useDropZone.md b/docs/useDropZone.md
index bd0e6794..8d16a6f6 100644
--- a/docs/useDropZone.md
+++ b/docs/useDropZone.md
@@ -1,12 +1,12 @@
# useDropZone
-Accepts an HTML Element ref then makes it a drop-zone receiving data from dragged object.
+A hook that receives an HTML Element ref and transforms it into a drop-zone capable of accepting data from a dragged object
### Why? π‘
-- takes care of adding the drop-related events listeners to the defined target
-- takes care of cleaning the listener when the component will unmount
-- allow to easily implement drop-related business logic
+- Handles the addition of drop-related event listeners to the specified target
+- Cleans up the listener upon component unmounting
+- Facilitates the implementation of drop-related business logic
### Basic Usage:
@@ -31,7 +31,7 @@ const MyComponent = () => {
});
return (
-
+
{!isDragged &&
Drag to send data }
{isDragged &&
is being dragged }
@@ -51,18 +51,15 @@ const MyComponent = () => {
#### β
When to use
-- When in need of implementing basic drop-related business logic such as file drop
+- If in need to abstract some drag-n-drop related logic into a custom hooks
#### π What not to do
-- You can't use the returned handler setter asynchronously, it will not have any effect but changing the handler possibly leading to bugs in
- your code.
-- Absolutely avoid using `onDrop` handler setters to replace the standard drop handler props.
-- `useDropZone` is meant to be used to abstract more complex hooks that need to control the drag n drop, for example:
- the drag-around hook.
-- Using `useDropZone` handlers instead of the classic props approach it's just as bad as it sounds since you'll lose the React
- SyntheticEvent performance boost.
-- If you were doing something like the following, please keep doing it:
+- Using the returned callback setter asynchronously won't have any effect and could introduce bugs into your code, so it should be avoided.
+- Standard drag handler props (like `onDragStart`) should not be replaced with useDragEvents callback setters.
+- useDragEvents is designed to be used for more complex hooks that require control over drag and drop.
+- Replacing classic props with useDragEvents handlers can lead to a loss in performance due to the lack of React SyntheticEvent support.
+- If you were already using a method similar to the following, it is recommended to continue doing so:
```jsx harmony static noedit
const MyComponent = (props) => {
@@ -72,4 +69,20 @@ const MyComponent = (props) => {
);
};
-```
+```
+
+
+### Types
+
+```typescript static
+import { type RefObject } from 'react';
+import { type CallbackSetter } from './shared/types';
+export interface UseDropZoneResult {
+ readonly isOver: boolean;
+ readonly onDrop: CallbackSetter
;
+}
+declare const useDropZone: (targetRef: RefObject) => Readonly;
+export default useDropZone;
+
+```
+
\ No newline at end of file
diff --git a/docs/useEvent.md b/docs/useEvent.md
index e0a92518..b7c528ec 100644
--- a/docs/useEvent.md
+++ b/docs/useEvent.md
@@ -1,18 +1,18 @@
# useEvent
-Accepts the reference to an HTML Element and an event name then performs the necessary operations to listen to the event when fired from
-that HTML Element.
+A hook that allows you to specify an HTML element and an event name. It sets up a listener so that when that event happens on that element,
+your code will be notified and can take action. Essentially, it lets you "listen" for events on a specific HTML element
### Why? π‘
-- takes care of adding a listener for the event to the provided target ref
-- takes care of clearing the listener when the component unmounts
+- Automatically adds the event listener to the element, so you don't have to do it manually
+- Automatically removes the event listener when the component unmounts
### Basic Usage:
-`useEvents` returns a handler setter for the defined event to be immediately invoked.
+`useEvents` returns a callback setter for the defined event to be immediately invoked.
-**Please note**: the handler setter is only meant to change the callback reference, it does not cause the component rerender unless
+**Please note**: the callback setter is only meant to change the callback reference, it does not cause the component rerender unless
differently specified in the function's body. It's not invoked asynchronously
```jsx harmony
@@ -29,11 +29,11 @@ const TestComponent = () => {
});
return (
-
-
- Click on this text to increase the number of clicks: {clicksNo}
-
-
+
+
+ Click on this text to increase the number of clicks: {clicksNo}
+
+
);
};
@@ -63,11 +63,11 @@ const TestComponent = () => {
});
return (
-
-
- Click on this text to increase the number of clicks: {clicksNo}
-
-
+
+
+ Click on this text to increase the number of clicks: {clicksNo}
+
+
);
};
@@ -84,5 +84,20 @@ const TestComponent = () => {
- When you can archive the same result by using a callback, **please remember listening/firing events directly to/from HTMLElement(s) in
React is considered an anti-pattern**
-- You can't use the returned handler setter asynchronously, it will not have any effect but changing the handler possibly leading to bugs in
- your code
+- You can't use the returned callback setter asynchronously, it will not have any effect but changing the handler possibly leading to bugs
+ in your code
+
+
+### Types
+
+```typescript static
+import { type RefObject } from 'react';
+/**
+ * Accepts the reference to an HTML Element and an event name then performs the necessary operations to listen to the event
+ * when fired from that HTML Element.
+ */
+declare const useEvent: (ref: RefObject, eventName: string, options?: AddEventListenerOptions) => import("./shared/types").CallbackSetter;
+export default useEvent;
+
+```
+
\ No newline at end of file
diff --git a/docs/useGeolocation.md b/docs/useGeolocation.md
index ab7a9d9e..34575a48 100644
--- a/docs/useGeolocation.md
+++ b/docs/useGeolocation.md
@@ -1,20 +1,24 @@
# useGeolocation
-Returns an array where the first item is the geolocation state from [useGeolocationState](./useGeolocationState.md)
-and the second one is an object of handler setters from the [useGeolocationEvents](./useGeolocationEvents.md).
+A hook that does the job of two - now that's efficiency! This nifty little function returns an array with two elements: the first being the
+geolocation state from our trusty [useGeolocationState](./useGeolocationState) hook, and the second being an object of callback setters
+from [useGeolocationEvents](./useGeolocationEvents).
It is intended as a shortcut to those hooks.
### Why? π‘
-- allow to easily access the [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API/Using_the_Geolocation_API)
-- takes care of adding the geolocation events listeners
-- takes care of cleaning the listener when the component will unmount
-- allow to perform abstractions on geolocation related events
+- facilitates streamlined access to
+ the [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API/Using_the_Geolocation_API), which allows for
+ geolocation tracking and position updates
+- manages the addition of geolocation event listeners, ensuring that events related to the user's location are properly handled.
+- automatically cleans up the event listener when the component is unmounted, preventing potential memory leaks and optimizing performance
+- enables the abstraction of geolocation-related events, allowing for more flexible and scalable code implementation
### Basic Usage:
```jsx harmony
+import { Typography } from 'antd';
import useGeolocation from 'beautiful-react-hooks/useGeolocation';
const PositionReporter = () => {
@@ -25,14 +29,14 @@ const PositionReporter = () => {
});
return (
-
- The current position is:
- {geoState.isRetrieving && (Retrieving position...
)}
- {geoState.isSupported && geoState.position && [
- Lat: {geoState.position.coords.latitude}
,
- Lng: {geoState.position.coords.longitude}
- ]}
-
+
+ The current position is:
+ {geoState.isRetrieving && (Retrieving position... )}
+ {geoState.isSupported && geoState.position && [
+ Lat: {geoState.position.coords.latitude} ,
+ Lng: {geoState.position.coords.longitude}
+ ]}
+
);
};
@@ -44,6 +48,7 @@ const PositionReporter = () => {
Before using, please read about the [geolocation options](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions)
```jsx harmony
+import { Typography } from 'antd';
import useGeolocation from 'beautiful-react-hooks/useGeolocation';
const PositionReporter = () => {
@@ -58,14 +63,14 @@ const PositionReporter = () => {
});
return (
-
- The current position is:
- {geoState.isRetrieving && (Retrieving position...
)}
- {geoState.isSupported && geoState.position && [
- Lat: {geoState.position.coords.latitude}
,
- Lng: {geoState.position.coords.longitude}
- ]}
-
+
+ The current position is:
+ {geoState.isRetrieving && (Retrieving position... )}
+ {geoState.isSupported && geoState.position && [
+ Lat: {geoState.position.coords.latitude} ,
+ Lng: {geoState.position.coords.longitude}
+ ]}
+
);
};
@@ -76,9 +81,26 @@ const PositionReporter = () => {
#### β
When to use
-- If in need to easily access the Geolocation API.
+- Use this hook when you require effortless access to the Geolocation API
#### π What not to do
-- Don't use this hook to try to guess the user's device capabilities
-- Don't access the geolocation state before checking the `isSupported` flag
+- Do not utilize this hook to speculate the user's device capabilities.
+- Prior to accessing the geolocation state, ensure to verify the isSupported flag.
+
+
+### Types
+
+```typescript static
+import { type UseGeolocationStateResult } from './useGeolocationState';
+import { type UseGeolocationEventsResult } from './useGeolocationEvents';
+/**
+ * Returns an array where the first item is the geolocation state from the `useGeolocationState` hook and the
+ * second one is the object of callback setters from the `useGeolocationEvents` hook.
+ * It is intended as a shortcut to those hooks.
+ */
+declare const useGeolocation: (options?: PositionOptions) => [UseGeolocationStateResult, UseGeolocationEventsResult];
+export default useGeolocation;
+
+```
+
\ No newline at end of file
diff --git a/docs/useGeolocationEvents.md b/docs/useGeolocationEvents.md
index b2a78646..01c1ab28 100644
--- a/docs/useGeolocationEvents.md
+++ b/docs/useGeolocationEvents.md
@@ -1,22 +1,28 @@
# useGeolocationEvents
-Returns an object of handler setters to handle the geolocation-related events. So far, the supported methods are: `onChange`, invoked when
-the position changes and `onError`, invoked when an error occur while retrieving the position.
- Geolocation supported: {isSupported ? 'yes' : 'no'}
- {!error && position && (
- lat: {position.coords.latitude}, lng: {position.coords.longitude}
- )}
-
+
+ Geolocation supported: {isSupported ? 'yes' : 'no'}
+ {!error && position && (
+ lat: {position.coords.latitude}, lng: {position.coords.longitude}
+ )}
+
);
};
@@ -45,9 +51,31 @@ const GeoReporter = () => {
#### β
When to use
-- If in need to abstract some geolocation related logic into a custom hooks
+- Use this hook when you need to abstract geolocation-related logic into a custom hook
#### π What not to do
-- You can't use the returned handler setter asynchronously, it will not have any effect but changing the handler possibly leading to bugs in
- your code.
+- Do not use the returned callback setter asynchronously. Doing so will have no effect and may cause bugs in your code. Instead, be sure to
+ invoke the callback setters immediately in the function component's body
+
+
+### Types
+
+```typescript static
+import { type BRHGeolocationPosition, type BRHGeolocationPositionError } from './shared/types';
+export interface UseGeolocationEventsResult {
+ isSupported: boolean;
+ onChange: (callback: (position: BRHGeolocationPosition) => void) => void;
+ onError: (callback: (error: BRHGeolocationPositionError) => void) => void;
+}
+/**
+ * Returns a frozen object of callback setters to handle the geolocation events.;
+export default useGeolocationEvents;
+
+```
+
\ No newline at end of file
diff --git a/docs/useGeolocationState.md b/docs/useGeolocationState.md
index cb112fce..05ae05da 100644
--- a/docs/useGeolocationState.md
+++ b/docs/useGeolocationState.md
@@ -1,23 +1,28 @@
# useGeolocationState
-Returns an object containing the `position` information, the `isSupported` boolean flag reporting whether the geolocation API is supported
-or not, the `isRetrieving` boolean flag reporting whether the hook is fetching the current position or not ans the `onError`, invoked when an error occur while retrieving the position.
+A hook that returns an object comprising information on the response from
+the [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API/Using_the_Geolocation_API). \
+This object properties are:
-The position is retrieved by using the
-[Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API/Using_the_Geolocation_API), when supported.
+- the `position` information, which is the actual response from the geolocation API
+- the `isSupported` boolean flag, indicating whether the geolocation API is supported or not
+- the `isRetrieving` boolean flag, indicating whether the hook is currently retrieving the position or not
+- the `onError` function, invoked when an error occurs while retrieving the position
-It possibly accepts an object of [geolocation options](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions)
-to be used as parameter when using the `Geolocation.getCurrentPosition()` method.
+It also accepts a [geolocation options object](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions) to be utilized as a
+parameter while utilizing the `Geolocation.getCurrentPosition()` method.
### Why? π‘
-- allow to easily access the [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API/Using_the_Geolocation_API)
-- takes care of cleaning the listener when the component will unmount
-- allow to perform abstractions on geolocation related events
+- facilitates streamlined access to
+ the [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API/Using_the_Geolocation_API), which allows for
+ geolocation tracking and position updates
+- enables the abstraction of geolocation-related events, allowing for more flexible and scalable code implementation
### Basic Usage:
```jsx harmony
+import { Typography } from 'antd';
import useGeolocationState from 'beautiful-react-hooks/useGeolocationState';
const PositionReporter = () => {
@@ -28,14 +33,14 @@ const PositionReporter = () => {
});
return (
-
- The current position is:
- {isRetrieving && (Retrieving position...
)}
- {isSupported && position && [
- Lat: {position.coords.latitude}
,
- Lng: {position.coords.longitude}
- ]}
-
+
+ The current position is:
+ {geoState.isRetrieving && (Retrieving position... )}
+ {geoState.isSupported && geoState.position && [
+ Lat: {geoState.position.coords.latitude} ,
+ Lng: {geoState.position.coords.longitude}
+ ]}
+
);
};
@@ -44,7 +49,7 @@ const PositionReporter = () => {
### Options:
-Before using, please read about the [geolocation options](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions)
+Read more on the [geolocation options documentation](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions)
```jsx harmony
import useGeolocationState from 'beautiful-react-hooks/useGeolocationState';
@@ -61,14 +66,14 @@ const PositionReporter = () => {
});
return (
-
- The current high accuracy position is:
- {isRetrieving && (Retrieving position...
)}
- {isSupported && position && [
- Lat: {position.coords.latitude}
,
- Lng: {position.coords.longitude}
- ]}
-
+
+ The current position is:
+ {geoState.isRetrieving && (Retrieving position... )}
+ {geoState.isSupported && geoState.position && [
+ Lat: {geoState.position.coords.latitude} ,
+ Lng: {geoState.position.coords.longitude}
+ ]}
+
);
};
@@ -79,10 +84,39 @@ const PositionReporter = () => {
#### β
When to use
-- If in need to easily access the Geolocation API
-- If in need to abstract some geolocation related logic into a custom hooks
+- Use this hook when you require effortless access to the Geolocation API
#### π What not to do
-- Don't use this hook to try to guess the user's device capabilities
-- Don't access the geolocation state before checking hte `isSupported` flag
+- Do not utilize this hook to speculate the user's device capabilities.
+- Prior to accessing the geolocation state, ensure to verify the isSupported flag.
+
+
+### Types
+
+```typescript static
+import { type BRHGeolocationPosition, type BRHGeolocationPositionError, type SomeCallback } from './shared/types';
+export interface GeolocationState {
+ readonly isSupported: boolean;
+ readonly isRetrieving: boolean;
+ readonly position: BRHGeolocationPosition;
+}
+export interface UseGeolocationStateResult extends GeolocationState {
+ onError: (callback: SomeCallback) => void;
+}
+/**
+ * Returns a frozen object containing the `position` object, the `isSupported` boolean flag, reporting whether the
+ * geolocation API is supported or not and the `isRetrieving` boolean flag reporting whether the hook is fetching the
+ * current position.
+ * The position is retrieved by using the
+ * [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API/Using_the_Geolocation_API),
+ * when supported.;
+export default useGeolocationState;
+
+```
+
\ No newline at end of file
diff --git a/docs/useGlobalEvent.md b/docs/useGlobalEvent.md
index d8b4c614..18112850 100644
--- a/docs/useGlobalEvent.md
+++ b/docs/useGlobalEvent.md
@@ -1,21 +1,19 @@
# useGlobalEvent
-Accepts an event name to be attached to the window global object, then returns a handler setter for that event.
+A hook that streamlines event handling in your application, ensuring that event listeners are added and removed at the appropriate times,
+without requiring you to manage them manually.\
+Simply provide the name of the event you want to attach to the `window` object, and the hook will take care of the rest.
### Why? π‘
-- takes care of adding a listener for a given event to the window object
-- takes care of removing the listener when the component will unmount
+- Simplifies the process of adding a listener for a specific event to the `window` object.
+- Automates the removal of the listener when the component is unmounted.
### Basic Usage:
-`useGlobalEvent` returns a handler setter for the defined event to be immediately invoked.
-
-**Please note**: the handler setter is only meant to change the callback reference, it does not cause the component rerender unless
-differently specified in the function's body. It's not invoked asynchronously
-
```jsx harmony
import { useState } from 'react';
+import { Typography, Alert, Tag, Space } from 'antd';
import useGlobalEvent from 'beautiful-react-hooks/useGlobalEvent';
const TestComponent = () => {
@@ -27,8 +25,14 @@ const TestComponent = () => {
});
return (
-
- Current window width: {windowWidth}
+
+
+
+ window width: {windowWidth}
+
);
};
@@ -43,6 +47,7 @@ under the hood, it's possible to specify the listener characteristics by passing
```jsx harmony
import { useState } from 'react';
+import { Typography, Alert, Tag, Space } from 'antd';
import useGlobalEvent from 'beautiful-react-hooks/useGlobalEvent';
const TestComponent = () => {
@@ -55,8 +60,14 @@ const TestComponent = () => {
});
return (
-
- Current window width: {windowWidth}
+
+
+
+ window width: {windowWidth}
+
);
};
@@ -68,11 +79,22 @@ const TestComponent = () => {
#### β
When to use
-- When in need of listening to a specific event from the window global object
+- To capture a specific event from the `window` global object.
#### π What not to do
-- When you can archive the same result by using a callback, **please remember listening/firing events directly to/from HTMLElement(s) in
- React is considered an anti-pattern**
-- You can't use the returned handler setter asynchronously, it will not have any effect but changing the handler possibly leading to bugs in
- your code
+- Avoid using the returned callback setter asynchronously, as it will only change the handler and may cause bugs in your code.
+
+
+### Types
+
+```typescript static
+import { type CallbackSetter } from './shared/types';
+/**
+ * Accepts an event name then returns a callback setter for a function to be performed when the event triggers.
+ */
+declare const useGlobalEvent: (eventName: keyof WindowEventMap, opts?: AddEventListenerOptions) => CallbackSetter;
+export default useGlobalEvent;
+
+```
+
\ No newline at end of file
diff --git a/docs/useInfiniteScroll.md b/docs/useInfiniteScroll.md
index a1b234fc..0b1f209c 100644
--- a/docs/useInfiniteScroll.md
+++ b/docs/useInfiniteScroll.md
@@ -1,12 +1,12 @@
# useInfiniteScroll
-Accepts an HTML Element ref, then returns a function that allows you to handle the infinite scroll for that specific element.
+A hook that accepts an HTML Element reference and returns a function that facilitates handling infinite scroll for that specific element.
### Why? π‘
-- takes care of adding the infinite scroll-related events listeners to the defined target
-- takes care of cleaning the listener when the component will unmount
-- allow to easily implement infinite scroll business logic
+- adds the required event listeners for infinite scrolling to the defined target
+- takes care of cleaning up the event listener when the component is unmounted, reducing the risk of memory leaks in your application
+- simplifies the implementation of infinite scroll business logic by providing an intuitive and easy-to-use interface
### Basic Usage:
@@ -14,6 +14,7 @@ Provide a DOM ref as first parameter to `useInfiniteScroll`
```jsx harmony
import { useState, useRef } from 'react';
+import { Alert, List, Typography } from 'antd';
import useInfiniteScroll from 'beautiful-react-hooks/useInfiniteScroll';
const generateRandomNo = () => Math.floor(Math.random() * 11)
@@ -47,29 +48,33 @@ const TestComponent = () => {
setIsFetching(true)
fetchMock()
- .then((next) => setData([...data, ...next]))
- .finally(() => setIsFetching(false))
+ .then((next) => setData([...data, ...next]))
+ .finally(() => setIsFetching(false))
}
})
return (
-
-
-
-
Scroll to "load" more contents…
-
- {data.map((item) => (
- mock item no: {item}
- ))}
-
- {isFetching && (
-
- Loading next data...
+
+
+
+
+
(
+
+ mock item no: {item}
+
+ )}
+ />
+ {isFetching && (
+
+ Loading next data...
+
+ )}
+
-
-
+
);
};
@@ -80,9 +85,25 @@ const TestComponent = () => {
#### β
When to use
-- When in need of abstracting your own infinite scroll business logic
+- Use this hook to abstract your own infinite scroll business logic and streamline the implementation of this functionality in your
+ application
#### π What not to do
-- Don't rely on this hook to debounce/throttling your functions, if you're implementing a pagination-like infinite scroll you should
- debounce/throttle your own functions
+- Avoid using this hook to debounce or throttle your functions. If you're implementing a pagination-like infinite scroll, it's best to
+ handle this debounce/throttle functionality yourself, to ensure that your application behaves exactly as you intend.
+
+
+### Types
+
+```typescript static
+import { type RefObject } from 'react';
+/**
+ * Accepts an HTML Element ref, then returns a function that allows you to handle the infinite
+ * scroll for that specific element.
+ */
+declare const useInfiniteScroll:
(ref: RefObject, delay?: number) => import("./shared/types").CallbackSetter;
+export default useInfiniteScroll;
+
+```
+
\ No newline at end of file
diff --git a/docs/useInterval.md b/docs/useInterval.md
index 822bf3ea..b8323ef3 100644
--- a/docs/useInterval.md
+++ b/docs/useInterval.md
@@ -1,19 +1,22 @@
# useInterval
-An async-utility hook that accepts a callback `function` and a `delay time` (*in milliseconds*), then repeat the execution of the given
-function by the defined time.
+A hook that facilitates the utilization of the `setInterval` function in React function components. This hook receives a callback function
+and a delay duration as inputs, and subsequently, executes the given function at regular intervals with the specified delay time between
+each invocation
### Why? π‘
-- takes care of performing the given callback regardless the component re-renders;
-- cancels the interval when the component unmount (or not, depends by the defined options);
-- returns the interval state (cleared/not cleared)
-- returns a method to possibly cancel the set interval (cause the component re-render)
+- Ensures that the given callback is executed reliably, even when the component re-renders;
+- Automatically cancels the interval when the component unmounts (although this behavior can be modified by adjusting the options);
+- Provides information about the current state of the interval (whether it has been cleared or not);
+- Offers a method to cancel the set interval, which can trigger a re-render of the component if desired.
### Basic Usage:
```jsx harmony
import { useState } from 'react';
+import { Tag, Typography } from 'antd';
+
import useInterval from 'beautiful-react-hooks/useInterval';
const DelayedContentComponent = () => {
@@ -25,8 +28,8 @@ const DelayedContentComponent = () => {
}, 1000);
return (
-
- Rendering since {seconds} seconds
+
+ Rendering since {seconds} seconds
);
};
@@ -36,12 +39,14 @@ const DelayedContentComponent = () => {
### State & clear method:
-The hook returns the state of the timeout (a boolean, cleared/not cleared) and a method to possibly clear it.
+The hook returns information about the timeout's state (whether it has been cleared or not, represented by a boolean flag), and also offers
+a method to potentially clear it.
-**Note:** programmatically clearing the timeout will cause the component re-render.
+**Note**: Invoking this method to programmatically clear the timeout may trigger the component re-rendering.
```jsx harmony
import { useState } from 'react';
+import { Tag, Typography, Button } from 'antd';
import useInterval from 'beautiful-react-hooks/useInterval';
const DelayedContentComponent = () => {
@@ -52,9 +57,9 @@ const DelayedContentComponent = () => {
return (
- Rendering since {seconds} seconds
- {!isCleared && Stop it! }
- {isCleared && Interval cleared!
}
+ Rendering since {seconds} seconds
+ {!isCleared && Stop the counter }
+ {isCleared && Interval cleared! }
);
};
@@ -64,7 +69,7 @@ const DelayedContentComponent = () => {
### Options:
-`useInterval` might accept a options object provided as eventual parameter.
+It is possible to provide an options object as the last parameter of the hook.
#### cancelOnUnmount:
@@ -74,6 +79,7 @@ Defines whether the timeout should be cleared on unmount.
```jsx harmony
import { useState } from 'react';
+import { Tag, Typography, Button } from 'antd';
import useInterval from 'beautiful-react-hooks/useInterval';
const DelayedContentComponent = () => {
@@ -84,7 +90,8 @@ const DelayedContentComponent = () => {
return (
- Content rendering since {seconds} but will not be cleared on unmount
+ Rendering since {seconds} seconds
+ It won't be cleared at unmount
);
};
@@ -96,8 +103,27 @@ const DelayedContentComponent = () => {
#### β
When to use
-- If in need to perform a function every x number of milliseconds regardless the component re-renders
+- When you need to perform a function on a regular interval (e.g., every x number of milliseconds), regardless of whether the component
+ re-renders.
#### π When not to use
-- You can't use it asynchronously since this will break the [rules of hooks](https://reactjs.org/docs/hooks-rules.html)
+- When attempting to use it asynchronously, since doing so would violate the [rules of hooks](https://reactjs.org/docs/hooks-rules.html)
+
+
+### Types
+
+```typescript static
+import { type GenericFunction } from './shared/types';
+export interface UseIntervalOptions {
+ cancelOnUnmount?: boolean;
+}
+/**
+ * An async-utility hook that accepts a callback function and a delay time (in milliseconds), then repeats the
+ * execution of the given function by the defined milliseconds.
+ */
+declare const useInterval: (fn: TCallback, milliseconds: number, options?: UseIntervalOptions) => [boolean, () => void];
+export default useInterval;
+
+```
+
\ No newline at end of file
diff --git a/docs/useIsFirstRender.md b/docs/useIsFirstRender.md
index 444f7c6d..6405f1a5 100644
--- a/docs/useIsFirstRender.md
+++ b/docs/useIsFirstRender.md
@@ -1,17 +1,20 @@
# useIsFirstRender
--- This hook return a boolean set to true at the mount time and then always false --
+A hook that returns a boolean value indicating whether it's the first render or not.
+
+This hook can be used to conditionally execute logic or render components based on whether it's the first time the component is being
+rendered or if it's being re-rendered due to a state or prop change.
### π‘ Why?
-- Give information about if it's first render
+- A useful tool for managing component rendering behavior and enables you to write more efficient and flexible code
### Basic Usage:
```jsx harmony
import { useState, useCallback } from 'react';
-import { Pill, Paragraph, Icon } from 'beautiful-react-ui';
-import useIsFirstRender from 'beautiful-react-hooks/useIsFirstRender';
+import { Button, Typography } from 'antd';
+import useIsFirstRender from 'beautiful-react-hooks/useIsFirstRender';
const UseIsFirstRenderExample = () => {
const [data, setData] = useState(0)
@@ -20,13 +23,12 @@ const UseIsFirstRenderExample = () => {
const setNewDate = useCallback(() => setData(Date.now()), []);
return (
-
- Click on the button to update isFirstRender flag
- isFirstRender: {isFirstRender ? 'yes' : 'no'}
-
-
+ Click on the button to update isFirstRender flag
+ isFirstRender: {isFirstRender ? 'yes' : 'no'}
+
Update data
-
+
);
};
@@ -34,8 +36,12 @@ const UseIsFirstRenderExample = () => {
- Check the javascript console
+
+
);
};
@@ -41,13 +46,15 @@ const LifeCycleComponent = () => {
### Callback setter syntax:
-if no parameters are provided, the returned object of handler setters can be used to set the `useDidMount` and `useWillUnmount` handlers, as
-long as they are immediately invoked.
+If you don't provide any parameters, you can use the returned callback setters to set the `useDidMount` and `useWillUnmount` handlers.
+However, you must immediately invoke them to make it work.
-**Please note**: the returned handler setters are meant to change the value of the callback reference only, they do not cause the component
-rerender nor should not be invoked asynchronously.
+**Note**: It's important to keep in mind that the callback setters are intended to modify the value of the callback reference only. They do
+not cause the component to rerender, and you should not invoke them asynchronously. This ensures that the behavior of your code remains
+predictable and that your project runs smoothly.
```jsx harmony
+import { Alert } from 'antd';
import useLifecycle from 'beautiful-react-hooks/useLifecycle';
const ComponentDidMount = () => {
@@ -62,8 +69,8 @@ const ComponentDidMount = () => {
});
return (
-
- Check the javascript console
+
+
);
};
@@ -75,9 +82,6 @@ const ComponentDidMount = () => {
When using a React function component you should not really think of it in terms of "lifecycle".
-The `useLifecycle` hook is indeed intended as a shortcut to `useEffect(onMount, [])` and
-`useEffect(() => () => willUnmount, [])`.
-
To deep understanding `useEffect`, what it is and how it should be properly used, please read
"[A complete guide to useEffect](https://overreacted.io/a-complete-guide-to-useeffect/)"
by [Dan Abramov](https://twitter.com/dan_abramov)
@@ -86,11 +90,29 @@ by [Dan Abramov](https://twitter.com/dan_abramov)
#### β
When to use
-- When in need of performing a function after the component did mount
-- When in need of performing a function right before the component unmounts
-- When in need of a shortcut to the component lifecycle
+- When you need to execute a function after the component has mounted
+- When you need to execute a function immediately before the component unmounts
+- When you require a shortcut to the component lifecycle
#### π When not to use
-- You can't use it asynchronously since this will break the [rules of hooks](https://reactjs.org/docs/hooks-rules.html)
-- If using the handler setters, they should not be used asynchronously but immediately invoked.
+- If you need to use it asynchronously, as this violates the [rules of hooks](https://reactjs.org/docs/hooks-rules.html)
+- If you're using the callback setters, you must not use them asynchronously, but instead, immediately invoke them.
+
+
+### Types
+
+```typescript static
+import { type GenericFunction } from './shared/types';
+/**
+ * Returns an object wrapping lifecycle hooks such as `useDidMount` or `useWillUnmount`.
+ * It is intended as a shortcut to those hooks.
+ */
+declare const useLifecycle: (mount?: TMount | undefined, unmount?: TUnmount | undefined) => {
+ onDidMount: import("./shared/types").CallbackSetter;
+ onWillUnmount: import("./shared/types").CallbackSetter;
+};
+export default useLifecycle;
+
+```
+
\ No newline at end of file
diff --git a/docs/useLocalStorage.md b/docs/useLocalStorage.md
index 313543c2..18c5aa84 100644
--- a/docs/useLocalStorage.md
+++ b/docs/useLocalStorage.md
@@ -1,16 +1,17 @@
# useLocalStorage
-A hook for storing values into [Local Storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage).
+A hook that enables effortless storage and retrieval of values in the
+browser's [Local Storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage).
### π‘ Why?
-- A quick way to use the `localStorage` in your React components.
+- A fast and efficient method to implement the `localStorage` functionality in your React components
### Basic Usage:
```jsx harmony
import React, { useCallback } from 'react';
-import { Pill, Paragraph, Icon } from 'beautiful-react-ui';
+import { Button, Tag, Typography } from 'antd';
import useLocalStorage from 'beautiful-react-hooks/useLocalStorage';
const NotificationBadgeExample = ({ notifications }) => {
@@ -20,13 +21,17 @@ const NotificationBadgeExample = ({ notifications }) => {
setNotificationCount(0);
}, [notificationCount]);
+ const Actions = [
+
+ You've got {notificationCount} new messages
+
+ ]
+
return (
-
- Click on the badge to clear from the local storage
-
-
+
+
+ Click on the following button to clear data from the demo-notification-count local storage key.
+
)
};
@@ -34,6 +39,14 @@ const NotificationBadgeExample = ({ notifications }) => {
= (value: TValue | ((previousValue: TValue) => TValue)) => void
+
+declare const useLocalStorage: (storageKey: string, defaultValue?: any) => [TValue, SetValue]
+```
+
### Mastering the hooks
#### β
When to use
@@ -43,3 +56,16 @@ const NotificationBadgeExample = ({ notifications }) => {
#### π When not to use
- Do not use this hook as a state manager, the `localStorage` is meant to be used for small pieces of data
+
+
+### Types
+
+```typescript static
+/**
+ * Save a value on local storage
+ */
+declare const useLocalStorage: (storageKey: string, defaultValue?: any) => [TValue | null, (value: TValue | ((previousValue: TValue) => TValue)) => void];
+export default useLocalStorage;
+
+```
+
\ No newline at end of file
diff --git a/docs/useMediaQuery.md b/docs/useMediaQuery.md
index 93b698a9..98a84e2c 100644
--- a/docs/useMediaQuery.md
+++ b/docs/useMediaQuery.md
@@ -1,18 +1,14 @@
# useMediaQuery
-Accepts a media query string then uses the [matchMedia](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia)
-API to determine if it matches with the current document.
+A hook that takes in a media query string and utilizes the [matchMedia](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia)
+API to check whether it corresponds to the present document.
-It also monitor the document changes to detect when it stops matching the given media query.
+Additionally, it tracks changes in the document to detect when it no longer corresponds to the provided media query.
-Returns the validity state of the given media query.
-
-### Why? π‘
-
-- takes care of re-rendering the component when the given media query changes
-- get rid of the listener when the component will unmount
+The hook returns the validity status of the media query provided.
```jsx harmony
+import { Tag, Typography, Space, Alert } from 'antd';
import useMediaQuery from 'beautiful-react-hooks/useMediaQuery';
const MediaQueryReporter = () => {
@@ -20,9 +16,12 @@ const MediaQueryReporter = () => {
const isLarge = useMediaQuery('(min-width: 48rem)');
return (
-
- Small view? {isSmall ? 'yes' : 'no'}
- Large view? {isLarge ? 'yes' : 'no'}
+
+
+ Small view? {isSmall ? 'yes' : 'no'}
+ Large view? {isLarge ? 'yes' : 'no'}
+
);
};
@@ -34,9 +33,27 @@ const MediaQueryReporter = () => {
#### β
When to use
-- When a component should have a different layout/behaviour on different medias
-- Mount/Unmount sub-components according to a defined media-query
+- If a component needs to display a different layout or behavior on various media types
+- Conditionally render sub-components based on a specified media query
#### π When not to use
-- Do not use this hook to define the user device
+- Avoid using this hook to identify the user's device, use agent detection instead
+
+
+### Types
+
+```typescript static
+/**
+ * Accepts a media query string then uses the
+ * [window.matchMedia](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia) API to determine if it
+ * matches with the current document.
-
- Move the mouse over this text to get its current coordinates:
- {showCoords && (
-
{position.clientX}, {position.clientY}
- )}
-
+
+
+
+ ClientX: {position.clientX}
+ ClientY: {position.clientY}
+
+
);
};
@@ -49,6 +51,7 @@ If no ref is provided to `useMouse` it will use the window global object assign
```jsx harmony
import { useState } from 'react';
+import { Tag, Space, Alert } from 'antd';
import useMouse from 'beautiful-react-hooks/useMouse';
const MouseReporter = () => {
@@ -59,16 +62,13 @@ const MouseReporter = () => {
onMouseUp(() => setMouseDown(false));
return (
-
-
- The current mouse global coordinates are: {position.clientX}, {position.clientY}
- {mouseDown && (
-
- Holding click
-
- )}
-
+
+
+ ClientX: {position.clientX}
+ ClientY: {position.clientY}
+
+
);
};
@@ -79,25 +79,52 @@ const MouseReporter = () => {
#### β
When to use
-- If in need to get the mouse current position
-- If in need to abstract some mouse related logic into a custom hooks
+- use `useMouse` to obtain the current mouse position.
+- use `useMouse` to abstract custom mouse-related logic into a hook.
#### π What not to do
-- You can't use the returned handler setter asynchronously, it will not have any effect but changing the handler possibly leading to bugs in
- your code.
-- Absolutely avoid using `useMouse` handler setters to replace the standard mouse handler props.
-- `useMouse` is meant to be used to abstract more complex hooks that need to control the mouse, for example: a drag n drop hook.
-- Using `useMouse` handlers instead of the classic props approach it's just as bad as it sounds since you'll lose the React SyntheticEvent
- performance boost.
+
);
};
-```
+```
+
+
+### Types
+
+```typescript static
+import { type RefObject } from 'react';
+/**
+ * Returns an array where the first item is the mouse state from the `useMouseState` hook and the second item
+ * is the object of callback setters from the `useMouseEvents` hook.
+ * It is intended as a shortcut to those hooks.
+ */
+declare const useMouse: (targetRef?: RefObject | undefined) => ({
+ clientX: number;
+ clientY: number;
+ screenX: number;
+ screenY: number;
+} | Readonly<{
+ onMouseDown: import("./shared/types").CallbackSetter;
+ onMouseEnter: import("./shared/types").CallbackSetter;
+ onMouseLeave: import("./shared/types").CallbackSetter;
+ onMouseMove: import("./shared/types").CallbackSetter;
+ onMouseOut: import("./shared/types").CallbackSetter;
+ onMouseOver: import("./shared/types").CallbackSetter;
+ onMouseUp: import("./shared/types").CallbackSetter;
+}>)[];
+export default useMouse;
+
+```
+
\ No newline at end of file
diff --git a/docs/useMouseEvents.md b/docs/useMouseEvents.md
index 3722bdb3..202ecd02 100644
--- a/docs/useMouseEvents.md
+++ b/docs/useMouseEvents.md
@@ -1,19 +1,19 @@
-# useMouseEvents
+# useMouseEvents
-Returns a set of handler setters to control mouse events.
-
- Move mouse over me to get its current coordinates.
- {coordinates &&
Coordinates x:{coordinates[0]} y:{coordinates[1]}
}
-
+
+
+
+ ClientX: {coordinates[0]}
+ ClientY: {coordinates[1]}
+
+
);
};
@@ -52,11 +56,12 @@ const MyComponent = () => {
### Global events
-Avoid providing any argument to `useMouseEvents` to attach the events globally
+If no ref is provided to `useMouseEvents` it will use the window global object assign the events to
```jsx harmony
import { useState } from 'react';
-import useMouseEvents from 'beautiful-react-hooks/useMouseEvents';
+import { Tag, Space, Alert } from 'antd';
+import useMouseEvents from 'beautiful-react-hooks/useMouseEvents';
const MyComponent = () => {
const [coordinates, setCoordinates] = useState([0, 0]);
@@ -68,10 +73,13 @@ const MyComponent = () => {
});
return (
-
- The current mouse coordinates are:
- x:{coordinates[0]} y:{coordinates[1]}
-
+
+
+ ClientX: {coordinates[0]}
+ ClientY: {coordinates[1]}
+
+
);
};
@@ -82,24 +90,55 @@ const MyComponent = () => {
#### β
When to use
-- When need to abstract touch related logics into custom hooks(s)
+- When you need to abstract mouse-related logics into custom hooks(s)
#### π What not to do
-- You can't use the returned handler setter asynchronously, it will not have any effect but changing the handler
- possibly leading to bugs in your code.
-- Absolutely avoid using `useMouseEvents` handler setters to replace the standard mouse handler props.
-- `useMouseEvents` is meant to be used to abstract more complex hooks that need to control the mouse, for example: a drag n drop hook.
-- Using `useMouseEvents` handlers instead of the classic props approach it's just as bad as it sounds since you'll
-lose the React SyntheticEvent performance boost.
+
);
};
-```
+```
+
+
+### Types
+
+```typescript static
+import { type RefObject } from 'react';
+/**
+ * Returns a frozen object of callback setters to handle the mouse events.(targetRef?: RefObject | undefined, passive?: boolean) => Readonly<{
+ onMouseDown: import("./shared/types").CallbackSetter;
+ onMouseEnter: import("./shared/types").CallbackSetter;
+ onMouseLeave: import("./shared/types").CallbackSetter;
+ onMouseMove: import("./shared/types").CallbackSetter;
+ onMouseOut: import("./shared/types").CallbackSetter;
+ onMouseOver: import("./shared/types").CallbackSetter;
+ onMouseUp: import("./shared/types").CallbackSetter;
+}>;
+export default useMouseEvents;
+
+```
+
\ No newline at end of file
diff --git a/docs/useMouseState.md b/docs/useMouseState.md
index 776777fa..e2eabb07 100644
--- a/docs/useMouseState.md
+++ b/docs/useMouseState.md
@@ -1,15 +1,14 @@
# useMouseState
-Returns a summary of the mouse current position properties (such as clientX, clientY). It accepts a DOM ref representing the events target (
-where attach the events to).
-
-If a target is not provided the events will be globally attached to the `document` object.
+A hook that returns relevant properties from the current mouse position, such as clientX and clientY. To ensure that events are attached to
+the intended target, please provide a DOM reference to the hook. If no target is specified, the events will be attached to the
+the `document` object globally.
### Why? π‘
-- allow to easily inspect the mouse position
-- takes care of adding the mouse events listeners globally or to a defined target
-- takes care of cleaning the listener when the component unmounts
+- Allows to quickly get the mouse position
+- Manages the addition of mouse event listeners either globally or to a defined target
+- Ensures the listener is cleaned up when the component unmounts
### Basic Usage:
@@ -17,6 +16,7 @@ Provide a DOM ref as first parameter to `useMouseState`
```jsx harmony
import { useRef } from 'react';
+import { Tag, Space, Alert } from 'antd';
import useMouseState from 'beautiful-react-hooks/useMouseState';
const MouseReporter = () => {
@@ -24,10 +24,13 @@ const MouseReporter = () => {
const { clientX, clientY } = useMouseState(ref);
return (
-
+
- Move mouse over me to get its current coordinates:
- {clientX}, {clientY}
+
+ ClientX: {clientX}
+ ClientY: {clientY}
+
);
@@ -38,18 +41,22 @@ const MouseReporter = () => {
### Global events
-Avoid providing any argument to `useMouseState`
+Attach the mouse events globally by simply not providing any dom reference to the `useMouseState` hook
```jsx harmony
+import { Tag, Space, Alert } from 'antd';
import useMouseState from 'beautiful-react-hooks/useMouseState';
const MouseReporter = () => {
const { clientX, clientY } = useMouseState();
return (
-
- The current mouse coordinates are:
- {clientX}, {clientY}
+
+
+ ClientX: {clientX}
+ ClientY: {clientY}
+
);
};
@@ -61,24 +68,26 @@ const MouseReporter = () => {
#### β
When to use
-- When need to abstract touch related logics into custom hooks(s)
-
-#### π What not to do
-
-- You can't use the returned handler setter asynchronously, it will not have any effect but changing the handler possibly leading to bugs in
- your code.
-- Absolutely avoid using `useMouseEvents` handler setters to replace the standard mouse handler props.
-- `useMouseEvents` is meant to be used to abstract more complex hooks that need to control the mouse, for example: a drag n drop hook.
-- Using `useMouseEvents` handlers instead of the classic props approach it's just as bad as it sounds since you'll lose the React
- SyntheticEvent performance boost.
- );
+- When you need to abstract mouse-related logics into custom hooks(s)
+- When you need to quickly get the current mouse position
+
+
+### Types
+
+```typescript static
+import { type RefObject } from 'react';
+/**
+ * Returns the current state (position) of the mouse pointer.
+ * It possibly accepts a DOM ref representing the mouse target.
+ * If a target is not provided the state will be caught globally.
+ */
+declare const useMouseState: (targetRef?: RefObject | undefined) => {
+ clientX: number;
+ clientY: number;
+ screenX: number;
+ screenY: number;
};
-```
+export default useMouseState;
+
+```
+
\ No newline at end of file
diff --git a/docs/useMutationObserver.md b/docs/useMutationObserver.md
index 9000ad79..b623d713 100644
--- a/docs/useMutationObserver.md
+++ b/docs/useMutationObserver.md
@@ -1,17 +1,23 @@
# useMutationObserver
-Uses the [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) API to watch for changes being made to the DOM tree
+A hook that employs the [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) API to monitor changes made to
+the Document Object Model (DOM) tree.
+
+This hook enables asynchronous observation of changes to a specified HTML Element. It automatically handles the clean-up of the observation
+process when the associated component is unmounted.
### Why? π‘
-- Asynchronously observes changes of the given HTML Element.
-- Takes care of cleaning the observable once the component is dismount.
+- allows for real-time monitoring of changes to the DOM, without requiring constant polling or manual inspection of the element.
+- provides more granular control over the types of changes being observed, allowing developers to selectively listen for specific events
+ such as attribute modifications, node insertions or removals, and so on.
### Basic Usage:
```jsx harmony
-import { useRef, useState } from 'react';
-import useMutationObserver from 'beautiful-react-hooks/useMutationObserver';
+import { useRef, useState } from 'react';
+import { Tag, Typography } from 'antd';
+import useMutationObserver from 'beautiful-react-hooks/useMutationObserver';
const UseMutationObserverExample = () => {
const ref = useRef();
@@ -23,29 +29,39 @@ const UseMutationObserverExample = () => {
useMutationObserver(ref, incrementMutationCount);
- return (
-
-
+ return (
+
+
-
-
Mutation count: {mutationCount}
-
+ Mutations: {mutationCount}
- );
+ );
};
```
+
+
+### Types
+
+```typescript static
+import { type RefObject } from 'react';
+declare const useMutationObserver:
(ref: RefObject, callback: MutationCallback, options?: MutationObserverInit) => void;
+export default useMutationObserver;
+
+```
+
\ No newline at end of file
diff --git a/docs/useObjectState.md b/docs/useObjectState.md
index fa031632..0a5b97c7 100644
--- a/docs/useObjectState.md
+++ b/docs/useObjectState.md
@@ -1,16 +1,20 @@
# useObjectState
-React state hook that creates setState method which works similar to how useState works, merges object changes into the current state.
+A hook has been developed to emulate the behavior of the now deprecated class Component.setState method. This hook aims to facilitate the
+migration process of legacy class components to the new function components paradigm.
### Why? π‘
-- takes care of automatically destruct the previous state and override this with a new one,
+- Automates the process of destructing the previous state and replacing it with a new one, alleviating the burden of manually handling these
+ operations in function components
+- Allow developers to seamlessly transition their codebase from class components to function components without needing to restructure the
+ existing codebase
### Basic Usage:
```jsx harmony
import { useState, useRef } from 'react';
-import { Button } from 'beautiful-react-ui';
+import { Button, Typography } from 'antd';
import useObjectState from 'beautiful-react-hooks/useObjectState';
const UseObjectStateComponent = () => {
@@ -22,19 +26,22 @@ const UseObjectStateComponent = () => {
const decrement = () => setState({ count: state.count - 1 })
+ const Actions = [
+
+ Increment counter
+ ,
+
+ Decrement counter
+ ,
+
+ Reset counter
+
+ ]
+
return (
-
- State:
- {JSON.stringify(state, null, 2)}
-
- Increment counter
-
-
- Decrement counter
-
-
- Reset counter
-
+
+ State:
+ {JSON.stringify(state, null, '\t')}
);
};
@@ -46,4 +53,18 @@ const UseObjectStateComponent = () => {
#### β
When to use
-- When in need of manage the state which is an object,
+- When required to migrate legacy class components to the new function components paradigm
+
+#### π What not to do
+
+- Don't use this hook in place of `useReducer`.
+
+
+### Types
+
+```typescript static
+declare const useObjectState: (initialState: TState) => [TState, (state: Partial) => void];
+export default useObjectState;
+
+```
+
\ No newline at end of file
diff --git a/docs/useObservable.md b/docs/useObservable.md
index 4b8747f1..5e2b1363 100644
--- a/docs/useObservable.md
+++ b/docs/useObservable.md
@@ -1,18 +1,20 @@
# useObservable
-Make your components reactive with `rxjs`
+A hook that enables reactivity in your components through the utilization of `RxJs` library.
### Why? π‘
-- you can change your data in pipes with default rxjs operators
-- combine data, pipes and create structured code
+- Modify your data using default `RxJs` operators within pipes, providing a cleaner and more concise way of handling asynchronous data
+- Combine data from multiple sources into a single observable stream using various `RxJs` operators, allowing you to create more structured
+ and organized code
### Basic Usage:
-##### Using as [useInterval](./useInterval.md)
+Mimics the behaviour of [useInterval](./useInterval.md) with `RxJs`
```jsx harmony
import { useState } from 'react';
+import { Tag, Typography } from 'antd';
import { interval } from 'rxjs';
import useObservable from 'beautiful-react-hooks/useObservable';
@@ -24,8 +26,8 @@ const ObservableInterval = () => {
useObservable(interval$, setSeconds);
return (
-
- Rendering since {seconds} seconds
+
+ Rendering since {seconds} seconds
);
};
@@ -33,11 +35,12 @@ const ObservableInterval = () => {
- Current position:
- lat: {coords && coords.latitude}
- long: {coords && coords.longitude}
+
+ Current position:
+ {position.coords && [
+ Lat: {position.coords.latitude} ,
+ Lng: {position.coords.longitude}
+ ]}
);
};
@@ -74,6 +79,7 @@ const ObservableGeolocation = () => {
```jsx harmony
import { useState } from 'react';
import { fromEvent } from 'rxjs';
+import { Typography, Tag } from 'antd';
import useObservable from 'beautiful-react-hooks/useObservable';
const resize$ = fromEvent(window, 'resize');
@@ -85,10 +91,14 @@ const ObservableResize = () => {
const { target } = event;
return (
-
- Resize your window
- Width: {target && target.innerWidth || 0}
- Height: {target && target.innerHeight || 0}
+
+ Resize your window
+
+ width: {target && target.innerWidth || 0}
+
+
+ height: {target && target.innerHeight || 0}
+
);
};
@@ -100,9 +110,23 @@ const ObservableResize = () => {
#### β
When to use
-- If you want to present some data like tables and work with them through the pipes (filter, sort, map etc.)
-- use events wisely
+- when you need to display and manipulate data using reactive programming techniques. `RxJs` pipes can be used for filtering, sorting,
+ mapping, and other transformations.
#### π When not to use
-- When you can do something w/o rx
+- Don't use this hook as a state manager
+
+
+### Types
+
+```typescript static
+import { type Observable, type Observer } from 'rxjs';
+/**
+ * Hook, which helps you combine rxjs flow and setState in your component
+ */
+declare const useObservable: > | ((value: T) => void)>(observable: Observable, setter: F) => void;
+export default useObservable;
+
+```
+
\ No newline at end of file
diff --git a/docs/useOnlineState.md b/docs/useOnlineState.md
index 1fbe80f1..3d6c1966 100644
--- a/docs/useOnlineState.md
+++ b/docs/useOnlineState.md
@@ -1,28 +1,51 @@
# useOnlineState
-Uses the [Navigator online API](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorOnLine/onLine) to define whether the browser is
-connected or not.
+A hook is available in this library that utilizes
+the [Navigator online API](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorOnLine/onLine) to determine the connectivity status of
+the user's browser.
-Returns a `boolean` value that if is true indicates the browser is connected.
+This hook returns a boolean value which indicates whether the browser is currently online or offline.
+
+The primary use case for this hook is to facilitate re-rendering of a component when the browser's connectivity status changes. By using
+this hook, your component can respond dynamically to changes in connectivity and update its behavior accordingly
### Why? π‘
-- You want to your component to re-render ether when the connection goes online or offline.
+- Your component requires network connectivity to function correctly and should behave differently when offline
+- You need to trigger some functionality when the user's connectivity status changes, such as syncing data with a server when the user comes
+ back online
### Basic Usage:
```jsx harmony
+import { Tag, Typography } from 'antd';
import useOnlineState from 'beautiful-react-hooks/useOnlineState';
const ConnectionTest = () => {
const isOnline = useOnlineState();
-
+
return (
-
- Connection status: {isOnline ? 'online' : 'offline'}
-
+
+
+ Connection status: {isOnline ? 'online' : 'offline'}
+
+
);
};
- {seconds}s
- The previous value of the state 'seconds' was: {prevSeconds}
+
+
+ {seconds}s
+
+
+ The previous value of the state 'seconds' was: {prevSeconds}
+
);
};
(value?: TValue | undefined) => TValue | undefined;
+export default usePreviousValue;
+
+```
+
\ No newline at end of file
diff --git a/docs/useQueryParam.md b/docs/useQueryParam.md
index b4305641..8c9752c0 100644
--- a/docs/useQueryParam.md
+++ b/docs/useQueryParam.md
@@ -1,17 +1,19 @@
# useQueryParam
+A hook built on top of React Router v5 that facilitate access and manipulation of query parameters.
+
### Why? π‘
-- to ease the process of modify the query string in the URL for the current location.
-- Works similar to the useState hook
-- it's NOT built on top of version 6 of react-router-dom's useSearchParams, it is therefore compatible with older version
+- Facilitates editing the query string in the URL for the current location
+- Functions similarly to the useState hook
+- Does not rely on version 6 of the useSearchParams function from react-router-dom, ensuring compatibility with older versions
### Basic Usage:
```jsx harmony
import { useState, useRef } from 'react';
import { HashRouter as Router } from 'react-router-dom'
-import { Input } from 'beautiful-react-ui'
+import { Typography, Tag, Input } from 'antd';
import useQueryParam from 'beautiful-react-hooks/useQueryParam';
const ExampleComponent = () => {
@@ -22,9 +24,11 @@ const ExampleComponent = () => {
})
return (
-
- Current value of 'foo' param is '{param}'
-
+
+ Current value of 'foo' param is {param} <
+ /Typography.Paragraph>
+
);
};
@@ -33,3 +37,20 @@ const ExampleComponent = () => {
{
+ initialValue?: TValue;
+ replaceState?: boolean;
+}
+/**
+ * Ease the process of modify the query string in the URL for the current location.
+ */
+declare const useQueryParam: (key: string, options?: UseQueryParamOptions) => [TValue, (nextValue?: TValue | undefined) => void];
+export default useQueryParam;
+
+```
+
\ No newline at end of file
diff --git a/docs/useQueryParams.md b/docs/useQueryParams.md
index 2beac863..09f79d4b 100644
--- a/docs/useQueryParams.md
+++ b/docs/useQueryParams.md
@@ -13,7 +13,7 @@ Very similar to `useQueryParam` (mind the final 's'), it eases the process of ma
```jsx harmony
import { useState, useRef } from 'react';
import { HashRouter as Router } from 'react-router-dom'
-import { Button, Input } from 'beautiful-react-ui'
+import { Button, Typography, Input } from 'antd'
import useQueryParams from 'beautiful-react-hooks/useQueryParams';
const ExampleComponent = () => {
@@ -25,12 +25,17 @@ const ExampleComponent = () => {
const onClick = () => setFoos([4, 5, 6])
+ const Actions = [
+
+ Change to param to [4,5,6]
+
+ ]
+
return (
-
- Current value of 'foo[]' param is '{foos.join(',')}'
-
- Change to param to [4,5,6]
-
+
+
+ Current value of 'foo[]' param is '{foos.join(',')}'
+
);
};
@@ -39,3 +44,20 @@ const ExampleComponent = () => {
{
+ initialValue?: TValue;
+ replaceState?: boolean;
+}
+/**
+ * Very similar to `useQueryParams`, it eases the process of manipulate a query string that handles multiple values
+ */
+declare const useQueryParams: (key: string, options?: UseQueryParamsOptions) => [TValue, (nextValue?: TValue | undefined) => void];
+export default useQueryParams;
+
+```
+
\ No newline at end of file
diff --git a/docs/useRenderInfo.md b/docs/useRenderInfo.md
index d3dee6a3..4445bc13 100644
--- a/docs/useRenderInfo.md
+++ b/docs/useRenderInfo.md
@@ -1,7 +1,7 @@
# useRenderInfo
-Takes a component name and prints information on how many time the component renders, at what time and how many seconds
-has passed since the last render.
+A hook that prints the number of renders for a given component, along with a timestamp of the most recent render and the time elapsed since
+the last render.
### Why? π‘
@@ -10,26 +10,25 @@ has passed since the last render.
### Basic Usage:
```jsx harmony
-import useInterval from 'beautiful-react-hooks/useInterval';
-import useRenderInfo from 'beautiful-react-hooks/useRenderInfo';
-
+import { Typography } from 'antd';
+import useInterval from 'beautiful-react-hooks/useInterval';
+import useRenderInfo from 'beautiful-react-hooks/useRenderInfo';
const RenderInfo = () => {
- const [seconds, setSeconds] = React.useState(0);
-
- // repeat the function each 1000ms
- useInterval(() => {
- setSeconds(1 + seconds);
- }, 1000);
+ const [seconds, setSeconds] = React.useState(0);
+ // repeat the function each 1000ms
+ useInterval(() => {
+ setSeconds(1 + seconds);
+ }, 1000);
- useRenderInfo('Module');
+ useRenderInfo('Module');
- return (
-
- Check the console!
-
- );
+ return (
+
+ Check the console!
+
+ );
};
- I'm not using the console, {info.sinceLast} seconds passed from the last render!
-
- );
+ const [seconds, setSeconds] = React.useState(0);
+ const info = useRenderInfo();
+
+ // repeat the function each 1000ms
+ useInterval(() => {
+ setSeconds(1 + seconds);
+ }, 1000);
+
+ return (
+
+ {info.sinceLast} seconds passed from the last render!
+
+ );
};
+
);
@@ -42,13 +45,13 @@ const AnimationExample = () => {
### Options
-An object of options can be used as second argument to control the animation.
+The animation can be fine-tuned using an options object as the second argument.
-**Please note**: options.finishAt = -1 will cause an infinite animation
+Please note that setting `options.finishAt` to a value of `-1` will result in an infinite animation.
```jsx harmony
import { useRef } from 'react';
-import { Alert } from 'beautiful-react-ui';
+import { Alert } from 'antd';
import useRequestAnimationFrame from 'beautiful-react-hooks/useRequestAnimationFrame';
const AnimationExample = () => {
@@ -61,9 +64,9 @@ const AnimationExample = () => {
}, options);
return (
-
+
);
@@ -78,7 +81,7 @@ The hook returns an function to possibly set a callback when the animation finis
```jsx harmony
import { useRef, useState } from 'react';
-import { Alert, Paragraph } from 'beautiful-react-ui';
+import { Alert, Typography } from 'antd';
import useRequestAnimationFrame from 'beautiful-react-hooks/useRequestAnimationFrame';
const AnimationExample = () => {
@@ -92,11 +95,11 @@ const AnimationExample = () => {
onFinish(() => setIsFinished(true));
return (
-
+
- {isFinished && Animation completed! }
+ {isFinished && Animation completed! }
);
};
@@ -113,3 +116,22 @@ Control the speed of your animation by changing the increment value
#### β
When to use
- When in need to perform requestAnimationFrame without re-rendering the component on each frame
+
+
+### Types
+
+```typescript static
+import { type CallbackSetter, type GenericFunction } from './shared/types';
+export interface UseRequestAnimationFrameOpts {
+ increment?: number;
+ startAt?: number;
+ finishAt?: number;
+}
+/**
+ * Takes care of running an animating function, provided as the first argument, while keeping track of its progress.
+ */
+declare const useRequestAnimationFrame: (func: T, options?: UseRequestAnimationFrameOpts) => CallbackSetter;
+export default useRequestAnimationFrame;
+
+```
+
\ No newline at end of file
diff --git a/docs/useResizeObserver.md b/docs/useResizeObserver.md
index 3e386aa3..e9bbd91c 100644
--- a/docs/useResizeObserver.md
+++ b/docs/useResizeObserver.md
@@ -1,37 +1,41 @@
# useResizeObserver
-Uses the [ResizeObserver](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) API to observe changes to the size of the provided element and returns DOMRect data
+A hook that utilizes the [ResizeObserver](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) to monitor changes in the size
+of the supplied element and yields DOMRect data.
### Why? π‘
-- Asynchronously observes changes in the DOM Rect of the given HTML Element.
-- Takes care of cleaning the observable once the component is dismount.
+- Monitors variations asynchronously in the DOM Rect of the specified HTML Element.
+- Automatically disposes of the observer once the component unmounts.
### Basic Usage:
```jsx harmony
-import { useRef } from 'react';
-import useResizeObserver from 'beautiful-react-hooks/useResizeObserver';
+import { useRef } from 'react';
+import { Input } from 'antd';
+import useResizeObserver from 'beautiful-react-hooks/useResizeObserver';
const ResizeObserverExample = () => {
- const ref = useRef();
- const DOMRect = useResizeObserver(ref);
-
- return (
-
-
- {DOMRect && (
-
- Box width: {DOMRect.width}
- Box height: {DOMRect.height}
- Box left: {DOMRect.left}
- Box right: {DOMRect.right}
- Box top: {DOMRect.top}
- Box bottom: {DOMRect.bottom}
-
- )}
-
- );
+ const ref = useRef();
+ const DOMRect = useResizeObserver(ref);
+
+ return (
+
+
+
+ {DOMRect && (
+
+ Box width: {DOMRect.width}
+ Box height: {DOMRect.height}
+ Box left: {DOMRect.left}
+ Box right: {DOMRect.right}
+ Box top: {DOMRect.top}
+ Box bottom: {DOMRect.bottom}
+
+ )}
+
+ );
};
-
- {DOMRect && (
-
- Box width: {DOMRect.width}
- Box height: {DOMRect.height}
- Box left: {DOMRect.left}
- Box right: {DOMRect.right}
- Box top: {DOMRect.top}
- Box bottom: {DOMRect.bottom}
-
- )}
-
- );
+ const ref = useRef();
+ const DOMRect = useResizeObserver(ref, 1000);
+
+ return (
+
+
+
+ {DOMRect && (
+
+ Box width: {DOMRect.width}
+ Box height: {DOMRect.height}
+ Box left: {DOMRect.left}
+ Box right: {DOMRect.right}
+ Box top: {DOMRect.top}
+ Box bottom: {DOMRect.bottom}
+
+ )}
+
+ );
};
;
+/**
+ * Uses the ResizeObserver API to observe changes within the given HTML Element DOM Rect.
+ * @param elementRef
+ * @param debounceTimeout
+ * @returns {undefined}
+ */
+declare const useResizeObserver: (elementRef: RefObject, debounceTimeout?: number) => DOMRectValues | undefined;
+export default useResizeObserver;
+
+```
+
\ No newline at end of file
diff --git a/docs/useSearchQuery.md b/docs/useSearchQuery.md
index 553f08be..8a882e39 100644
--- a/docs/useSearchQuery.md
+++ b/docs/useSearchQuery.md
@@ -1,25 +1,28 @@
# useSearchQuery
+A hook built on top of React Router v5 that facilitate access and manipulation of the 'search' query parameter.
+
### Why? π‘
-- to ease the process of modify the 'search' query string in the URL for the current location.
-- Works similar to useState hook
-- built on top of useQueryParam
+- Facilitates editing the 'search' query string in the URL for the current location
+- Functions similarly to the useState hook
### Basic Usage:
```jsx harmony
import { useState, useRef } from 'react';
import { HashRouter as Router } from 'react-router-dom'
-import { Input } from 'beautiful-react-ui'
+import { Input, Typography, Tag } from 'antd'
import useSearchQuery from 'beautiful-react-hooks/useSearchQuery';
const ExampleComponent = () => {
const [searchValue, setSearch] = useSearchQuery('initial-value')
return (
-
- Current value of search param is '{searchValue}'
+
+
+ Current value of search param is {searchValue}
+
);
@@ -29,3 +32,17 @@ const ExampleComponent = () => {
(initialValue?: TSearchKey | undefined, replaceState?: boolean) => [TSearchKey, (nextValue?: TSearchKey | undefined) => void];
+export default useSearchQuery;
+
+```
+
\ No newline at end of file
diff --git a/docs/useSessionStorage.md b/docs/useSessionStorage.md
index 6bc29e9f..1e52f6a9 100644
--- a/docs/useSessionStorage.md
+++ b/docs/useSessionStorage.md
@@ -1,32 +1,37 @@
# useSessionStorage
-A hook for storing values into [Session Storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage).
+A hook that enables effortless storage and retrieval of values in the
+browser's [Session Storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage).
### π‘ Why?
-- A quick way to use the `sessionStorage` in your React components.
+- A fast and efficient method to implement the `sessionStorage` functionality in your React components
### Basic Usage:
```jsx harmony
import React, { useCallback } from 'react';
-import { Pill, Paragraph, Icon } from 'beautiful-react-ui';
+import { Pill, Paragraph, Icon } from 'antd';
import useSessionStorage from 'beautiful-react-hooks/useSessionStorage';
const NotificationBadgeExample = ({ notifications }) => {
const [notificationCount, setNotificationCount] = useSessionStorage('demo-notification-count', notifications);
-
+
const clearNotifications = useCallback(() => {
setNotificationCount(0);
}, [notificationCount]);
+ const Actions = [
+
+ You've got {notificationCount} new messages
+
+ ]
+
return (
-
- Click on the badge to clear from the session storage
-
-
+
+
+ Click on the following button to clear data from the demo-notification-count session storage key.
+
)
};
@@ -34,6 +39,14 @@ const NotificationBadgeExample = ({ notifications }) => {
= (value: TValue | ((previousValue: TValue) => TValue)) => void
+
+declare const useSessionStorage: (storageKey: string, defaultValue?: any) => [TValue, SetValue]
+```
+
### Mastering the hooks
#### β
When to use
@@ -43,3 +56,16 @@ const NotificationBadgeExample = ({ notifications }) => {
#### π When not to use
- Do not use this hook as a state manager, the `sessionStorage` is meant to be used for small pieces of data
+
+
+### Types
+
+```typescript static
+/**
+ * Save a value on session storage
+ */
+declare const useSessionStorage: (storageKey: string, defaultValue?: any) => [TValue | null, (value: TValue | ((previousValue: TValue) => TValue)) => void];
+export default useSessionStorage;
+
+```
+
\ No newline at end of file
diff --git a/docs/useSpeechSynthesis.md b/docs/useSpeechSynthesis.md
index 8c310daf..fec1dd8d 100644
--- a/docs/useSpeechSynthesis.md
+++ b/docs/useSpeechSynthesis.md
@@ -1,30 +1,29 @@
# useSpeechSynthesis
-
- [This is still an experimental feature](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental)
-
-
-Enables the possibility to perform a text-to-speach (with different voices) operation in your React component by using the [Web_Speech_API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API).
+A hook that allows you to integrate text-to-speech functionality (with varying voices) within your React component by leveraging
+the [Web_Speech_API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API).
### Why? π‘
-- wraps the business logic of handling the Web Speech API into a single function
+- Abstracts the implementation details of the Web Speech API into a single reusable function.
### Basic Usage:
```jsx harmony
-import { Button, Input } from 'beautiful-react-ui';
-import useSpeechSynthesis from 'beautiful-react-hooks/useSpeechSynthesis';
+import { Button, Space, Input } from 'antd';
+import useSpeechSynthesis from 'beautiful-react-hooks/useSpeechSynthesis';
const SpeechSynthesisDemo = () => {
const [name, setName] = React.useState('Antonio');
- const { speak } = useSpeechSynthesis(`Hello, ${name}`);
-
+ const { speak } = useSpeechSynthesis(`Hello, ${name}`);
+
return (
-
- Greet!
-
+
+
+ Say hello...
+
+
);
};
@@ -36,38 +35,37 @@ const SpeechSynthesisDemo = () => {
`useSpeechSynthesis` receives an optional options object as second parameter to possibly define a custom voice.
```jsx harmony
-import { Button, Input, Select } from 'beautiful-react-ui';
-import useSystemVoices from 'beautiful-react-hooks/useSystemVoices';
-import useSpeechSynthesis from 'beautiful-react-hooks/useSpeechSynthesis';
+import { Button, Input, Space, Select } from 'antd';
+import useSystemVoices from 'beautiful-react-hooks/useSystemVoices';
+import useSpeechSynthesis from 'beautiful-react-hooks/useSpeechSynthesis';
const VoiceSelector = ({ onVoiceChange }) => {
- const [current, setVoice] = React.useState(0);
- const voices = useSystemVoices();
- const options = voices.map(({ name }, index) => ({ label: name, value: index }));
+ const [current, setVoice] = React.useState(0);
+ const voices = useSystemVoices();
+ const options = voices.map(({ name }, index) => ({ label: name, value: index }));
- React.useEffect(() => {
+ React.useEffect(() => {
onVoiceChange(voices[current]);
- }, [current]);
+ }, [current]);
- return (
-
-
-
- Greet!
-
+
+
+ Greet!
+
+
);
};
@@ -79,18 +77,20 @@ const SpeechSynthesisDemo = () => {
`useSpeechSynthesis` receives an optional options object as second parameter to possibly define a custom `rate` and `pitch`
```jsx harmony
-import { Button, Input } from 'beautiful-react-ui';
-import useSpeechSynthesis from 'beautiful-react-hooks/useSpeechSynthesis';
+import { Button, Input, Space } from 'antd';
+import useSpeechSynthesis from 'beautiful-react-hooks/useSpeechSynthesis';
const SpeechSynthesisDemo = () => {
const [name, setName] = React.useState('Antonio');
- const { speak } = useSpeechSynthesis(`Hello, ${name}`, { rate: 10, pitch: 15, volume: 2 });
-
+ const { speak } = useSpeechSynthesis(`Hello, ${name}`, { rate: 1.2, pitch: 1.2, volume: 1.2 });
+
return (
-
- Greet!
-
+
+
+ Greet!
+
+
);
};
@@ -100,10 +100,37 @@ const SpeechSynthesisDemo = () => {
### Mastering the hook
#### β
When to use
-
-- When in need of a text-to-speech functionality using the [Web_Speech_API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API).
+- When you want to incorporate text-to-speech functionality in your React application by utilizing
+ the [Web_Speech_API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API)
+
+
+### Types
+
+```typescript static
+/**
+ * The options that can be passed to the hook
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesisUtterance
+ */
+export interface UseSpeechSynthesisOptions {
+ rate?: number;
+ pitch?: number;
+ volume?: number;
+ voice?: SpeechSynthesisVoice;
+}
+/**
+ * The result of the hook
+ */
+export interface SpeechSynthesisResult {
+ readonly speak: () => void;
+ readonly speechSynthUtterance: SpeechSynthesisUtterance;
+}
+/**
+ * Enables the possibility to perform a text-to-speech (with different voices) operation in your
+ * React component by using the Web_Speech_API
+ */
+declare const useSpeechSynthesis: (text: string, options?: UseSpeechSynthesisOptions) => Readonly;
+export default useSpeechSynthesis;
-#### π When not to use
-
-- In production...yet. This is still an **experimental feature**
+```
+
\ No newline at end of file
diff --git a/docs/useSwipe.md b/docs/useSwipe.md
index 0a6eaf80..aab79253 100644
--- a/docs/useSwipe.md
+++ b/docs/useSwipe.md
@@ -1,13 +1,13 @@
# useSwipe
-Returns the state of the swipe gesture both on mobile or desktop.
-
+
+
Swipe me!
{showDetail && (
@@ -45,7 +45,7 @@ const SwipeReporter = () => {
### Global events
-Avoid providing any argument to `useSwipe`
+To register global listeners, simply invoke the hook without passing any arguments
```jsx harmony
import { useRef, useState } from 'react';
@@ -56,8 +56,8 @@ const SwipeReporter = () => {
const showDetail = swipeState.count > 0 || swipeState.swiping;
return (
-
-
+
+
Swipe everywehere you want!
{showDetail && (
@@ -93,8 +93,8 @@ const SwipeReporter = () => {
const showDetail = swipeState.count > 0 || swipeState.swiping;
return (
-
-
+
+
Swipe me, horizontally...
{showDetail && (
@@ -112,3 +112,37 @@ const SwipeReporter = () => {
```
+
+
+### Types
+
+```typescript static
+import { type RefObject } from 'react';
+import { type Direction } from './shared/swipeUtils';
+/**
+ * The options that can be passed to the hook
+ */
+export interface UseSwipeOptions {
+ direction?: 'both' | 'horizontal' | 'vertical';
+ threshold?: number;
+ preventDefault?: boolean;
+ passive?: boolean;
+}
+/**
+ * The result of the hook
+ */
+export interface SwipeState {
+ swiping: boolean;
+ direction?: Direction;
+ alphaX: number;
+ alphaY: number;
+ count: number;
+}
+/**
+ * useSwipe hook
+ */
+declare const useSwipe:
(targetRef?: RefObject | undefined, options?: UseSwipeOptions) => SwipeState;
+export default useSwipe;
+
+```
+
\ No newline at end of file
diff --git a/docs/useSwipeEvents.md b/docs/useSwipeEvents.md
index 172d9004..d350d6a5 100644
--- a/docs/useSwipeEvents.md
+++ b/docs/useSwipeEvents.md
@@ -1,16 +1,16 @@
# useSwipeEvents
-Returns a set of handler setters to control swipe events.
+
Swipe me!
@@ -66,7 +66,7 @@ const SwipeReporter = () => {
onSwipeDown(setLastSwipeInfo);
return (
-
+
Swipe around!
@@ -81,7 +81,6 @@ const SwipeReporter = () => {
+
Swipe me!
@@ -117,3 +116,47 @@ const SwipeReporter = () => {
;
+ onSwipeRight: CallbackSetter;
+ onSwipeUp: CallbackSetter;
+ onSwipeDown: CallbackSetter;
+ onSwipeMove: CallbackSetter;
+ onSwipeStart: CallbackSetter;
+ onSwipeEnd: CallbackSetter;
+}
+export interface UseSwipeEventsOpts {
+ threshold?: number;
+ preventDefault?: boolean;
+ passive?: boolean;
+}
+/**
+ * useSwipeEvents
+ * @param ref
+ * @param options
+ */
+declare const useSwipeEvents: (ref?: RefObject | undefined, options?: UseSwipeEventsOpts) => Readonly;
+export default useSwipeEvents;
+
+```
+
\ No newline at end of file
diff --git a/docs/useSystemVoices.md b/docs/useSystemVoices.md
index 0cff92cd..4815a6e3 100644
--- a/docs/useSystemVoices.md
+++ b/docs/useSystemVoices.md
@@ -1,45 +1,56 @@
# useSystemVoices
-
- [This is still an experimental feature](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental)
-
+A hook that returns all the available voices on the system.
-A side effect to retrieve all the available system voices using the [Web_Speech_API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API).
+**Note:** it's important to note that the purpose of this hook is to maintain backward compatibility with a previous version of the library
+that utilized a non-stable version of the Web Speech API. In that version, voices were returned asynchronously.
+
+If you are currently using a version of the library that does not require this hook, you can simply run:
+
+```typescript static
+const voices = window.speechSynthesis.getVoices()
+```
### Why? π‘
- At the moment, the `window.speechSynthesis.getVoices` function returns all the available system voices, but since
-it does it asynchronously [the returning value is an empty array until a second call is performed](https://w3c.github.io/speech-api/speechapi-errata.html).
-This hook manage the side-effect of correctly retrieve all the available system voices.
+ it does it
+ asynchronously [the returning value is an empty array until a second call is performed](https://w3c.github.io/speech-api/speechapi-errata.html)
+ this hook manage the side-effect of correctly retrieve all the available system voices.
### Basic Usage:
```jsx harmony
-import { List, Title } from 'beautiful-react-ui';
-import useSystemVoices from 'beautiful-react-hooks/useSystemVoices';
+import { List, Typography } from 'antd';
+import useSystemVoices from 'beautiful-react-hooks/useSystemVoices';
const SpeechSynthesisDemo = () => {
- const voices = useSystemVoices();
+ const voices = useSystemVoices();
return (
-
- System voices
-
- {voices.map(({ name, lang }) => {name} - {lang} )}
-
-
+
+ System voices
+
+ {voices.map(({ name, lang }) => {name} - {lang} )}
+
+
);
};
- window width: {width}
- window height: {height}
+
+
+
+ window width: {width} {height}
+
+
);
};
@@ -52,6 +59,7 @@ under the hood, you can possibly define the callback dependencies.
```jsx harmony
import { useState } from 'react';
+import { Space, Alert, Typography, Tag } from 'antd';
import useThrottledCallback from 'beautiful-react-hooks/useThrottledCallback';
import useWindowResize from 'beautiful-react-hooks/useWindowResize';
@@ -86,6 +94,7 @@ A custom throttled time can be easily defined as follows (500ms)
```jsx harmony
import { useState } from 'react';
+import { Space, Alert, Typography, Tag } from 'antd';
import useThrottledCallback from 'beautiful-react-hooks/useThrottledCallback';
import useWindowResize from 'beautiful-react-hooks/useWindowResize';
@@ -104,9 +113,15 @@ const ThrottledFnComponent = (props) => {
onWindowResize(onWindowResizeHandler);
return (
-
- window width: {width}
- window height: {height}
+
+
+
+ window width: {width} {height}
+
+
);
};
@@ -121,6 +136,7 @@ under the hood, you can possibly define few options to customise its behaviour.
```jsx harmony
import { useState } from 'react';
+import { Space, Alert, Typography, Tag } from 'antd';
import useThrottledCallback from 'beautiful-react-hooks/useThrottledCallback';
import useWindowResize from 'beautiful-react-hooks/useWindowResize';
@@ -143,9 +159,15 @@ const ThrottledFnComponent = () => {
onWindowResize(onWindowResizeHandler);
return (
-
- window width: {width}
- window height: {height}
+
+
+
+ window width: {width} {height}
+
+
);
};
@@ -155,12 +177,28 @@ const ThrottledFnComponent = () => {
#### β
Pro tip:
-To deep understanding the differences between `throttle` and `debounce`, what they are and when to use this functions please
+To deep understanding the differences between `throttle` and `debounce`, what they are and when to use them please
read "[Debouncing and Throttling Explained Through Examples](https://css-tricks.com/debouncing-throttling-explained-examples/)"
by [David Corbacho](https://twitter.com/dcorbacho)
-### Mastering the hook
+
+### Types
+
+```typescript static
+/// (fn: TCallback, dependencies?: DependencyList, wait?: number, options?: ThrottleSettings) => import("lodash").DebouncedFunc;
+export default useThrottledCallback;
-#### β
When to use
-
-- The classic example would be an infinite scroll over a paginated API call
+```
+
\ No newline at end of file
diff --git a/docs/useTimeout.md b/docs/useTimeout.md
index 093f3469..1a233ac6 100644
--- a/docs/useTimeout.md
+++ b/docs/useTimeout.md
@@ -1,19 +1,20 @@
# useTimeout
-An async-utility hook that accepts a callback `function` and a `delay time` (*in milliseconds*), then delays the execution of the given
-function by the defined time.
+A hook that facilitates the utilization of the `setTimeout` function in React function components. This hook receives a callback function
+and a delay duration as inputs, and subsequently, executes the given function at after the specified delay time.
### π‘ Why?
-- takes care of performing the given callback regardless the component re-renders;
-- cancels the timeout when component unmount (or not, depends by the defined options);
-- returns the timeout state (cleared/not cleared)
-- returns a method to possibly cancel the set timeout (cause the component re-render)
+- Ensures that the given callback is executed reliably, even when the component re-renders;
+- Automatically cancels the timeout when the component unmounts (although this behavior can be modified by adjusting the options);
+- Provides information about the current state of the timeout (whether it has been cleared or not);
+- Offers a method to cancel the timeout, which can trigger a re-render of the component if desired.
### Basic Usage:
```jsx harmony
import { useState } from 'react';
+import { Typography } from 'antd'
import useTimeout from 'beautiful-react-hooks/useTimeout';
const DelayedContentComponent = () => {
@@ -25,8 +26,8 @@ const DelayedContentComponent = () => {
}, 2000);
return (
-
- Content will show in 2 seconds...
+
+ Content will show in 2 seconds...
{showContent && π°
}
);
@@ -43,6 +44,7 @@ The hook returns the state of the timeout (a boolean, cleared/not cleared) and a
```jsx harmony
import { useState } from 'react';
+import { Typography, Button } from 'antd'
import useTimeout from 'beautiful-react-hooks/useTimeout';
const DelayedContentComponent = () => {
@@ -52,11 +54,11 @@ const DelayedContentComponent = () => {
}, 5000);
return (
-
- Content will show in 5 seconds...
+
+ Content will show in 5 seconds...
{showContent && π°
}
- {!isCleared && Press here to cancel timeout }
- {isCleared && Cleared
}
+ {!isCleared && Press here to cancel timeout }
+ {isCleared && Cleared }
);
};
@@ -66,7 +68,7 @@ const DelayedContentComponent = () => {
### Options:
-`useTimeout` might accept a options object provided as eventual parameter.
+`useTimeout` might accept an options object provided as eventual parameter.
#### cancelOnUnmount:
@@ -76,6 +78,7 @@ Defines whether the timeout should be cleared on unmount.
```jsx harmony
import { useState } from 'react';
+import { Typography } from 'antd';
import useTimeout from 'beautiful-react-hooks/useTimeout';
const DelayedContentComponent = () => {
@@ -85,8 +88,8 @@ const DelayedContentComponent = () => {
useTimeout(() => setShowContent(true), 3000, options);
return (
-
- Content will show in 3 seconds but not be cleared on unmount
+
+ Content will show in 3 seconds but not be cleared on unmount
{showContent && π°
}
);
@@ -99,8 +102,26 @@ const DelayedContentComponent = () => {
#### β
When to use
-- If in need to perform a function after a specified number of milliseconds regardless the component re-renders
+- when there is a requirement to execute a function after a specific number of milliseconds, without being affected by component re-renders
#### π When not to use
-- You can't use it asynchronously since this will break the [rules of hooks](https://reactjs.org/docs/hooks-rules.html)
+- Avoid using this hook for asynchronous operations since it violates the [rules of hooks](https://reactjs.org/docs/hooks-rules.html)
+
+
+### Types
+
+```typescript static
+import { type GenericFunction } from './shared/types';
+export interface UseTimeoutOptions {
+ cancelOnUnmount?: boolean;
+}
+/**
+ * An async-utility hook that accepts a callback function and a delay time (in milliseconds), then delays the
+ * execution of the given function by the defined time.
+ */
+declare const useTimeout: (fn: TCallback, milliseconds: number, options?: UseTimeoutOptions) => [boolean, () => void];
+export default useTimeout;
+
+```
+
\ No newline at end of file
diff --git a/docs/useToggle.md b/docs/useToggle.md
index c3fb6a71..5022259d 100644
--- a/docs/useToggle.md
+++ b/docs/useToggle.md
@@ -1,25 +1,31 @@
# useToggle
-A quick and safe utility for boolean states
+A hook that encapsulates the business logic of dealing with boolean values.
+
+Provides a higher-level interface for dealing with boolean logic in React function component.
### Why? π‘
-- frequent boolean states causes code duplication, this hook wraps-up the business logic of implementing a single boolean state
+- Having multiple boolean states in an application often leads to code redundancy. This hook consolidates the implementation details of a
+ singular boolean state, promoting code reusability and reducing code bloat.
### Basic Usage:
```jsx harmony
-import useToggle from 'beautiful-react-hooks/useToggle';
-import { Button } from 'beautiful-react-ui'
+import { Typography, Tag, Button } from 'antd'
+import useToggle from 'beautiful-react-hooks/useToggle'
const ComponentWillUnmount = () => {
const [value, toggleValue] = useToggle()
+ const tagColor = value ? 'green' : 'red'
return (
-
- Toggle is {value ? 'on' : 'off'}
- toggle value
-
+
+
+ Toggle is {value ? 'on' : 'off'}
+
+ toggle value
+
);
};
@@ -29,19 +35,35 @@ const ComponentWillUnmount = () => {
### Initial state
```jsx harmony
-import useToggle from 'beautiful-react-hooks/useToggle';
-import { Button } from 'beautiful-react-ui'
+import { Button, Typography, Tag } from 'antd'
+import useToggle from 'beautiful-react-hooks/useToggle'
const ComponentWillUnmount = () => {
const [value, toggleValue] = useToggle(true)
+ const tagColor = value ? 'green' : 'red'
return (
-
- Toggle is {value ? 'on' : 'off'}
- toggle value
-
+
+
+ Toggle is {value ? 'on' : 'off'}
+
+ toggle value
+
);
};
-
- Move mouse over me to get its current coordinates:
- {showCoords && touches[0] && (
-
{touches[0].clientX}, {touches[0].clientY}
- )}
-
+
+
+
+ Touch X: {touches[0].clientX} ,
+ Touch Y: {touches[0].clientY}
+ ])}
+
+
);
};
@@ -45,10 +49,11 @@ const TouchReporter = () => {
### Global events
-Avoid providing any argument to `useTouch`
+If no ref is provided to `useTouch` it will use the window global object assign the events to
```jsx harmony
import { useRef, useState } from 'react';
+import { Tag, Space, Alert } from 'antd';
import useTouch from 'beautiful-react-hooks/useTouch';
const TouchReporter = () => {
@@ -57,16 +62,17 @@ const TouchReporter = () => {
onTouchStart(() => setShowCoords(true));
onTouchEnd(() => setShowCoords(false));
-
+
return (
-
-
- Move mouse over me to get its current coordinates:
- {showCoords && touches[0] && (
-
{touches[0].clientX}, {touches[0].clientY}
- )}
-
+
+
+ Touch X: {touches[0].clientX} ,
+ Touch Y: {touches[0].clientY}
+ ])}
+
+
);
};
@@ -77,25 +83,39 @@ const TouchReporter = () => {
#### β
When to use
-- If in need to get the mouse current position
-- If in need to abstract some mouse related logic into a custom hooks
+- When you need to abstract touch-related logics into custom hooks(s)
#### π What not to do
-- You can't use the returned handler setter asynchronously, it will not have any effect but changing the handler possibly leading to bugs in
- your code.
-- Absolutely avoid using `useTouch` handler setters to replace the standard mouse handler props.
-- `useTouch` is meant to be used to abstract more complex hooks that need to control the mouse, for example: a drag n drop hook.
-- Using `useTouch` handlers instead of the classic props approach it's just as bad as it sounds since you'll lose the React SyntheticEvent
- performance boost.
+
);
};
-```
+```
+
+
+### Types
+
+```typescript static
+import { type RefObject } from 'react';
+import { type UseTouchEventsReturn } from './useTouchEvents';
+/**
+ * Returns an array where the first item is the touch state from the `useTouchState` hook and the second item
+ * is the object of callback setters from the `useTouchEvents` hook.
+ * It is intended as a shortcut to those hooks.
+ */
+declare const useTouch: (targetRef?: RefObject | undefined) => [TouchList, Readonly];
+export default useTouch;
+
+```
+
\ No newline at end of file
diff --git a/docs/useTouchEvents.md b/docs/useTouchEvents.md
index 1643a355..0c6263cd 100644
--- a/docs/useTouchEvents.md
+++ b/docs/useTouchEvents.md
@@ -1,19 +1,19 @@
# useTouchEvents
-Returns a set of handler setters to control touch events (*onTouchStart, onTouchMove, onTouchEnd*).
-
- Touch here! touching?: {touching ? 'yes' : 'no'}
- {touching && (
-
Coordinates: { coordinates[0] }, { coordinates[1] }
- )}
-
+
+
+
+ Is touching: {touching ? 'no' : 'yes'}
+ Touch X: {coordinates[0]}
+ Touch Y: {coordinates[1]}
+
+
);
};
@@ -62,10 +65,11 @@ const MyComponent = () => {
### Global events
-Avoid providing any argument to `useTouchEvents` to attach the events globally
+If no ref is provided to `useTouchEvents` it will use the window global object assign the events to
```jsx harmony
import { useState } from 'react';
+import { Tag, Space, Alert } from 'antd';
import useTouchEvents from 'beautiful-react-hooks/useTouchEvents';
const MyComponent = () => {
@@ -79,10 +83,13 @@ const MyComponent = () => {
});
return (
-
- The current touch coordinates are:
- x:{coordinates[0]} y:{coordinates[1]}
-
+
+
+ Touch X: {coordinates[0]}
+ Touch Y: {coordinates[1]}
+
+
);
};
@@ -93,24 +100,58 @@ const MyComponent = () => {
#### β
When to use
-- When need to abstract touch related logics into custom hooks(s)
+- When you need to abstract touch-related logics into custom hooks(s)
#### π What not to do
-- You can't use the returned handler setter asynchronously, it will not have any result but changing the handler possibly leading to bugs in
- your code.
-- Absolutely avoid using `useTouchEvents` handler setters to replace the standard touch handler props.
-- `useTouchEvents` is meant to be used to abstract more complex hooks that need to control the mouse, for example: a drag n drop hook.
-- Using `useTouchEvents` handlers instead of the classic props approach it's just as bad as it sounds since you'll lose the React
- SyntheticEvent performance boost.
+
);
};
-```
+```
+
+
+### Types
+
+```typescript static
+import { type RefObject } from 'react';
+import { type CallbackSetter } from './shared/types';
+/**
+ * Returns a frozen object of callback setters to handle the touch events.(targetRef?: RefObject | undefined, passive?: boolean) => Readonly;
+/**
+ * The return object of the `useTouchEvents` hook.
+ */
+export interface UseTouchEventsReturn {
+ onTouchStart: CallbackSetter;
+ onTouchEnd: CallbackSetter;
+ onTouchCancel: CallbackSetter;
+ onTouchMove: CallbackSetter;
+}
+export default useTouchEvents;
+
+```
+
\ No newline at end of file
diff --git a/docs/useTouchState.md b/docs/useTouchState.md
index 0019cc51..333dc1cb 100644
--- a/docs/useTouchState.md
+++ b/docs/useTouchState.md
@@ -1,14 +1,14 @@
# useTouchState
-Returns the touch objects from the current touch events. It accepts a DOM ref representing the events target (where attach the events to).
-
-If a target is not provided the events will be globally attached to the `document` object.
+A hook that returns relevant properties from the last touch event, such as clientX and clientY. To ensure that events are attached to the
+intended target, please provide a DOM reference to the hook. If no target is specified, the events will be attached to the the `document`
+object globally.
### Why? π‘
-- allow to easily get the touch state
-- takes care of adding the mouse events listeners globally or to a defined target
-- takes care of cleaning the listener when the component unmounts
+- Allows to quickly get relevant information on the last touch event
+- Manages the addition of event listeners either globally or to a defined target
+- Ensures the listener is cleaned up when the component unmounts
### Basic Usage:
@@ -16,19 +16,29 @@ Provide a DOM ref as first parameter to `useTouchState`
```jsx harmony
import { useRef } from 'react';
+import { Tag, Space, Alert } from 'antd';
import useTouchState from 'beautiful-react-hooks/useTouchState';
const TouchReporter = () => {
const ref = useRef();
const touches = useTouchState(ref);
+ const lastTouch = touches[0];
return (
-
+
- Touch over me to get its current coordinates:
- {touches && touches[0] && (
-
x: {touches[0].clientX}, y: {touches[0].clientY}
- )}
+
+ Touch X: {lastTouch.clientX}
+ Touch Y: {lastTouch.clientY}
+
+ )}
+ {touches.length === 0 && (
+
);
@@ -39,30 +49,56 @@ const TouchReporter = () => {
### Global events
-Avoid providing any argument to `useTouchState`
+Attach the touch events globally by simply not providing any dom reference to the `useTouchState` hook
```jsx harmony
-import useTouchState from 'beautiful-react-hooks/useTouchState';
+import useTouchState from 'beautiful-react-hooks/useTouchState';
+import { Tag, Space, Alert } from 'antd';
const TouchReporter = () => {
const touches = useTouchState();
-
+ const lastTouch = touches[0];
+
return (
-
- The current touch coordinates are:
- {touches && touches[0] && (
- x: {touches[0].clientX}, y: {touches[0].clientY}
- )}
-
+
+
+ Touch X: {lastTouch.clientX}
+ Touch Y: {lastTouch.clientY}
+
+ )}
+ {touches.length === 0 && (
+
+
);
};
(targetRef?: RefObject | undefined) => TouchList;
+export default useTouchState;
+
+```
+
\ No newline at end of file
diff --git a/docs/useURLSearchParams.md b/docs/useURLSearchParams.md
index 70b6f3b0..f8143b47 100644
--- a/docs/useURLSearchParams.md
+++ b/docs/useURLSearchParams.md
@@ -1,19 +1,20 @@
-# useQueryParams
+# useURLSearchParams
-Very similar to `useQueryParam` (mind the final 's'), it eases the process of manipulate a query string with multiple values.
+A hook that encapsulates the functionality of retrieving an always updated URLSearchParams object.
### Why? π‘
-- Ease the process of use an always updated instance of URLSearchParams
-- it's NOT built on top of version 6 of react-router-dom's useSearchParams, it is therefore compatible with older version
+- simplify the process of obtaining an always up-to-date instance of the URLSearchParams object
+- This hook is not based on the useSearchParams hook from version **6** of the `react-router-dom` library. Therefore, it is compatible with
+ earlier versions of `react-router-dom`
### Basic Usage:
```jsx harmony
import { useState, useRef } from 'react';
import { HashRouter as Router, useHistory } from 'react-router-dom'
-import { Button, Input } from 'beautiful-react-ui'
-import useURLSearchParams from 'beautiful-react-hooks/useURLSearchParams';
+import { Button, Input } from 'antd'
+import useURLSearchParams from 'beautiful-react-hooks/useURLSearchParams'
import useDidMount from 'beautiful-react-hooks/useDidMount'
const ExampleComponent = () => {
@@ -30,7 +31,7 @@ const ExampleComponent = () => {
})
return (
-
+
Current value of 'foo' param is '{params.get('foo')}'
Change the value of the foo param to see how this hook works
@@ -41,3 +42,16 @@ const ExampleComponent = () => {
- Open a console to see result and try to click update date button
-
-
+
+
+
+ Update data
+
+
);
};
@@ -40,8 +38,18 @@ const UseUpdateEffectExample = () => {
-
+
+
+ {validation.valid ? 'Password is valid' : 'Password is too short'}
+
+
);
};
@@ -41,3 +43,21 @@ const ValidatedField = () => {
#### β
good to know:
- useValidatedState does not re-render your component twice to save the validation state.
+
+
+### Types
+
+```typescript static
+/**
+ * Returns a state that changes only if the next value pass its validator
+ */
+declare const useValidatedState: >(validator: TValidator, initialValue?: TValue | undefined) => [TValue, (nextValue: TValue) => void, ValidationResult];
+export type Validator = (value: TValue) => boolean;
+export interface ValidationResult {
+ changed: boolean;
+ valid?: boolean;
+}
+export default useValidatedState;
+
+```
+
\ No newline at end of file
diff --git a/docs/useValueHistory.md b/docs/useValueHistory.md
index fd0ad953..eceed668 100644
--- a/docs/useValueHistory.md
+++ b/docs/useValueHistory.md
@@ -1,15 +1,16 @@
# useValueHistory
-Accepts a variable (*possibly a prop or a state*) and returns its history (changes through updates).
+A hook that takes a variable, which can be a prop or a state, and returns an array of its previous values. This hook is useful for tracking
+changes in a variable across multiple renders and allows developers to compare the current value with its previous values.
-### Why? π‘
-
-- You want to keep track of the history of a value
+Overall, the "usePrevious" hook is a helpful tool for debugging and improving the performance of React components that rely on the history
+of a specific variable
### Basic Usage:
```jsx harmony
import { useState } from 'react';
+import { Tag, Typography } from 'antd';
import useValueHistory from 'beautiful-react-hooks/useValueHistory';
import useInterval from 'beautiful-react-hooks/useInterval';
@@ -20,15 +21,28 @@ const TestComponent = () => {
useInterval(() => setCount(1 + count), 500);
return (
-
- Count: {count}
- The history of the `count` state is:
-
+
+ Count: {count}
+ The history of the `count` state is:
+
{countHistory.join(', ')}
-
+
);
};
(value: TValue, distinct?: boolean) => TValue[];
+export default useValueHistory;
+
+```
+
\ No newline at end of file
diff --git a/docs/useViewportSpy.md b/docs/useViewportSpy.md
index 07c7ab16..7340cdba 100644
--- a/docs/useViewportSpy.md
+++ b/docs/useViewportSpy.md
@@ -1,17 +1,18 @@
# useViewportSpy
-Uses the [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver) API to tell whether the given DOM
-Element (from useRef) is visible within the viewport.
+A hook that uses the [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver) API to tell whether the
+provided DOM Element is visible within the viewport.
### Why? π‘
- Asynchronously observes changes in the intersection of the given element with the document
-- Can be used to perform animation when the component appear within the viewport
+- Can be used to perform animation when the component appear into the viewport
### Basic Usage:
```jsx harmony
import { useRef } from 'react';
+import { Space, Typography, Tag } from 'antd';
import useViewportSpy from 'beautiful-react-hooks/useViewportSpy';
const ViewportSpyComponent = () => {
@@ -20,12 +21,15 @@ const ViewportSpyComponent = () => {
return (
-
- Observed element
-
-
- is the observed element in viewport? {isVisible ? 'yes' : 'no'}
-
+
+
+ Observed element
+
+
+ is the observed element in viewport?
+ {isVisible ? 'yes' : 'no'}
+
+
);
};
@@ -35,11 +39,12 @@ const ViewportSpyComponent = () => {
### Options
-The second argument could possibly be an object
-of [IntersectionObserver options](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver)
+Pass [IntersectionObserver options](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver) as second
+parameter to customize the behavior of the hook
```jsx harmony
import { useRef } from 'react';
+import { Space, Typography, Tag } from 'antd';
import useViewportSpy from 'beautiful-react-hooks/useViewportSpy';
const ViewportSpyComponent = () => {
@@ -48,12 +53,15 @@ const ViewportSpyComponent = () => {
return (
-
- Observed element
-
-
- is the observed element in viewport? {isVisible ? 'yes' : 'no'}
-
+
+
+ Observed element
+
+
+ is the observed element in viewport?
+ {isVisible ? 'yes' : 'no'}
+
+
);
};
@@ -66,3 +74,18 @@ const ViewportSpyComponent = () => {
This hook can be used to perform animations when a component/element enters or exit the viewport. To deeply
understand [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver)
please read [Using the Intersection Observer API to Trigger Animations and Transitions](https://alligator.io/js/intersection-observer)
+
+
+### Types
+
+```typescript static
+import { type RefObject } from 'react';
+/**
+ * Uses the IntersectionObserverMock API to tell whether the given DOM Element (from useRef) is visible within the
+ * viewport.
+ */
+declare const useViewportSpy: (ref: RefObject, options?: IntersectionObserverInit) => boolean | undefined;
+export default useViewportSpy;
+
+```
+
\ No newline at end of file
diff --git a/docs/useViewportState.md b/docs/useViewportState.md
index cba817f9..998b2373 100644
--- a/docs/useViewportState.md
+++ b/docs/useViewportState.md
@@ -1,6 +1,6 @@
# useViewportState
-Returns information on the current viewport state
+A hook that returns relevant information on the current viewport state.
It's built on top of [useWindowResize](./useWindowResize.md) and [useWindowScroll](./useWindowScroll.md).
@@ -13,17 +13,19 @@ It's built on top of [useWindowResize](./useWindowResize.md) and [useWindowScrol
```jsx harmony
import { useState } from 'react';
+import { Typography, Tag } from 'antd';
import useViewportState from 'beautiful-react-hooks/useViewportState';
const WindowSizeReporter = () => {
const { width, height, scrollX, scrollY } = useViewportState();
return (
-
- window width: {width}
- window height: {height}
- window scrollX: {scrollX}
- window scrollY: {scrollY}
+
+ Window current properties
+ width: {width}
+ height: {height}
+ horizontal scroll: {scrollX}
+ vertical scroll: {scrollY}
);
};
@@ -36,3 +38,22 @@ const WindowSizeReporter = () => {
#### β
When to use
- When in need of reading common information about the current viewport
+
+
+### Types
+
+```typescript static
+export interface ViewportState {
+ width: number;
+ height: number;
+ scrollX: number;
+ scrollY: number;
+}
+/**
+ * Returns updated information on the current viewport state
+ */
+declare const useViewportState: (debounceBy?: number) => ViewportState;
+export default useViewportState;
+
+```
+
\ No newline at end of file
diff --git a/docs/useWillUnmount.md b/docs/useWillUnmount.md
index e00447f8..2084f14c 100644
--- a/docs/useWillUnmount.md
+++ b/docs/useWillUnmount.md
@@ -1,15 +1,15 @@
# useWillUnmount
-Accepts a function to be performed right before the component unmounts.
+A hook that takes in a function to execute right before the component unmounts.
### Why? π‘
-- takes care of performing a callback right before the component unmounts
-- It's as a shortcut to `useEffect(() => () => willUnmount, [])`;
+- takes care of performing a callback when the component unmounts
### Basic Usage:
```jsx harmony
+import { Typography } from 'antd';
import useWillUnmount from 'beautiful-react-hooks/useWillUnmount';
const ComponentWillUnmount = () => {
@@ -18,8 +18,8 @@ const ComponentWillUnmount = () => {
});
return (
-
- Check the javascript console after moving from this page
+
+ Check the javascript console after moving from this page
);
};
@@ -29,13 +29,14 @@ const ComponentWillUnmount = () => {
### Callback setter syntax:
-if the first parameter is not provided, the returned function (*a handler setter*) can be used to set the `useWillUnmount` handler, as long
-as it is immediately invoked.
+If the first parameter is omitted, you can use the returned function (a callback setter) to set the useWillUnmount handler. However, you
+must immediately invoke the callback setter.
-**Please note**: the returned handler setter is meant to change the value of the callback reference only, it does not cause the component
-rerender nor should not be invoked asynchronously.
+Important: The callback setter only changes the value of the callback reference and does not trigger a component rerender. Also, avoid
+invoking it asynchronously
```jsx harmony
+import { Typography } from 'antd';
import useWillUnmount from 'beautiful-react-hooks/useWillUnmount';
const ComponentWillUnmount = () => {
@@ -46,8 +47,8 @@ const ComponentWillUnmount = () => {
});
return (
-
- Check the javascript console after moving from this page
+
+ Check the javascript console after moving from this page
);
};
@@ -69,9 +70,23 @@ by [Dan Abramov](https://twitter.com/dan_abramov)
#### β
When to use
-- When in need of performing a function after the component did mount
+- When you need to perform a function after the component has mounted
#### π When not to use
-- You can't use it asynchronously since this will break the [rules of hooks](https://reactjs.org/docs/hooks-rules.html)
-- If using the handler setter, it should not be used asynchronously but immediately invoked
+- Avoid using this hook asynchronously since it would violate the [rules of hooks](https://reactjs.org/docs/hooks-rules.html)
+- If you're using the callback setter, make sure to invoke it immediately instead of asynchronously
+
+
+### Types
+
+```typescript static
+import { type GenericFunction } from './shared/types';
+/**
+ * Returns a callback setter for a callback to be performed when the component will unmount.
+ */
+declare const useWillUnmount: (callback?: TCallback | undefined) => import("./shared/types").CallbackSetter;
+export default useWillUnmount;
+
+```
+
\ No newline at end of file
diff --git a/docs/useWindowResize.md b/docs/useWindowResize.md
index 57a3e76c..1a3e4b06 100644
--- a/docs/useWindowResize.md
+++ b/docs/useWindowResize.md
@@ -1,18 +1,19 @@
# useWindowResize
-Accepts a function to be performed during the window resize event.
+A hook that receives a callback function to execute on the window's resize event.
It's built on top of [useGlobalEvent](./useGlobalEvent.md).
### Why? π‘
-- takes care of adding the listener for the window resize event.
-- takes care of removing the listener when the component will unmount
+- Simplifies the process of adding a listener for a specific event to the `window` object.
+- Automates the removal of the listener when the component is unmounted.
### Basic Usage:
```jsx harmony
import { useState } from 'react';
+import { Typography, Tag } from 'antd';
import useWindowResize from 'beautiful-react-hooks/useWindowResize';
const WindowSizeReporter = () => {
@@ -25,9 +26,13 @@ const WindowSizeReporter = () => {
});
return (
-
- window width: {width}
- window height: {height}
+
+
+ current window width: {width}
+
+
+ current window height: {height}
+
);
};
@@ -37,14 +42,15 @@ const WindowSizeReporter = () => {
### Callback setter syntax:
-if the first parameter is not provided, the returned function (*a handler setter*) can be used to set the `useWindowResize` handler, as long
-as it is immediately invoked.
+if the first parameter is not provided, the returned function (*a callback setter*) can be used to set the `useWindowResize` handler, as
+long as it is immediately invoked.
-**Please note**: the returned handler setter is meant to change the value of the callback reference only, it does not cause the component
+**Please note**: the returned callback setter is meant to change the value of the callback reference only, it does not cause the component
rerender nor should not be invoked asynchronously.
```jsx harmony
import { useState } from 'react';
+import { Typography, Tag } from 'antd';
import useWindowResize from 'beautiful-react-hooks/useWindowResize';
const WindowSizeReporter = () => {
@@ -58,9 +64,13 @@ const WindowSizeReporter = () => {
});
return (
-
- window width: {width}
- window height: {height}
+
+
+ current window width: {width}
+
+
+ current window height: {height}
+
);
};
@@ -76,7 +86,9 @@ preventing too many useless renders, please take into account using
```jsx harmony
import { useState } from 'react';
-import { useWindowResize, useThrottledCallback } from 'beautiful-react-hooks';
+import { Typography, Tag } from 'antd';
+import useThrottledCallback from 'beautiful-react-hooks/useThrottledCallback';
+import useWindowResize from 'beautiful-react-hooks/useWindowResize';
const WindowSizeReporter = () => {
const [width, setWidth] = useState(window.innerWidth);
@@ -89,9 +101,13 @@ const WindowSizeReporter = () => {
}));
return (
-
- window width: {width}
- window height: {height}
+
+
+ current window width: {width}
+
+
+ current window height: {height}
+
);
};
@@ -107,5 +123,18 @@ const WindowSizeReporter = () => {
#### π When not to use
-- You can't use it asynchronously since this will break the [rules of hooks](https://reactjs.org/docs/hooks-rules.html)
-- If using the handler setter, it should not be used asynchronously but immediately invoked
+- Avoid using this hook asynchronously since it would violate the [rules of hooks](https://reactjs.org/docs/hooks-rules.html)
+- If you're using the callback setter, make sure to invoke it immediately instead of asynchronously
+
+
+### Types
+
+```typescript static
+/**
+ * Returns a function that accepts a callback to be performed when the window resize.
+ */
+declare const useWindowResize: () => import("./shared/types").CallbackSetter;
+export default useWindowResize;
+
+```
+
\ No newline at end of file
diff --git a/docs/useWindowScroll.md b/docs/useWindowScroll.md
index 041237c9..35651597 100644
--- a/docs/useWindowScroll.md
+++ b/docs/useWindowScroll.md
@@ -1,18 +1,19 @@
# useWindowScroll
-Accepts a function to be performed during the window scroll event.
+A hook that receives a callback function to execute on the window's scroll event.
It's built on top of [useGlobalEvent](./useGlobalEvent.md).
### Why? π‘
-- takes care of adding the listener for the window scroll event.
-- takes care of removing the listener when the component will unmount
+- Simplifies the process of adding a listener for a specific event to the `window` object.
+- Automates the removal of the listener when the component is unmounted.
### Basic usage:
```jsx harmony
import { useState } from 'react';
+import { Typography, Tag } from 'antd';
import useWindowScroll from 'beautiful-react-hooks/useWindowScroll';
const WindowScrollReporter = () => {
@@ -25,7 +26,9 @@ const WindowScrollReporter = () => {
return (
- window y-scroll: {scrollY}
+
+ current window vertical scroll: {scrollY}
+
);
};
@@ -35,14 +38,15 @@ const WindowScrollReporter = () => {
### Callback setter syntax:
-if the first parameter is not provided, the returned function (*a handler setter*) can be used to set the `useWindowScroll` handler, as long
-as it is immediately invoked.
+if the first parameter is not provided, the returned function (*a callback setter*) can be used to set the `useWindowScroll` handler, as
+long as it is immediately invoked.
-**Please note**: the returned handler setter is meant to change the value of the callback reference only, it does not cause the component
+**Please note**: the returned callback setter is meant to change the value of the callback reference only, it does not cause the component
rerender nor should not be invoked asynchronously.
```jsx harmony
import { useState } from 'react';
+import { Typography, Tag } from 'antd';
import useWindowScroll from 'beautiful-react-hooks/useWindowScroll';
const WindowScrollReporter = () => {
@@ -55,7 +59,9 @@ const WindowScrollReporter = () => {
return (
- window y-scroll: {scrollY}
+
+ current window vertical scroll: {scrollY}
+
);
};
@@ -71,7 +77,9 @@ preventing too many useless renders, please take into account using
```jsx harmony
import { useState } from 'react';
-import { useWindowScroll, useThrottledCallback } from 'beautiful-react-hooks';
+import { Typography, Tag } from 'antd';
+import useThrottledCallback from 'beautiful-react-hooks/useThrottledCallback'
+import useWindowScroll from 'beautiful-react-hooks/useWindowScroll';
const WindowScrollReporter = () => {
const [scrollY, setScrollY] = useState(window.scrollY);
@@ -83,7 +91,9 @@ const WindowScrollReporter = () => {
return (
- window y-scroll: {scrollY}
+
+ current window vertical scroll: {scrollY}
+
);
};
@@ -99,5 +109,18 @@ const WindowScrollReporter = () => {
#### π When not to use
-- You can't use it asynchronously since this will break the [rules of hooks](https://reactjs.org/docs/hooks-rules.html)
-- If using the handler setter, it should not be used asynchronously but immediately invoked
+- Avoid using this hook asynchronously since it would violate the [rules of hooks](https://reactjs.org/docs/hooks-rules.html)
+- If you're using the callback setter, make sure to invoke it immediately instead of asynchronously
+
+
+### Types
+
+```typescript static
+/**
+ * Returns a function that accepts a callback to be performed when the window scrolls.
+ */
+declare const useWindowScroll: () => import("./shared/types").CallbackSetter;
+export default useWindowScroll;
+
+```
+
\ No newline at end of file
diff --git a/docs/utils/_custom.css b/docs/utils/_custom.css
index 8519eff9..01602667 100644
--- a/docs/utils/_custom.css
+++ b/docs/utils/_custom.css
@@ -1,6 +1,6 @@
@import url('https://fonts.googleapis.com/css?family=Ubuntu:300,300i,400,400i,500,500i,700,700i&display=swap');
-@import "~beautiful-react-ui/beautiful-react-ui.css";
+@import '~antd/dist/reset.css';
body {
- font-family: 'Ubuntu', sans-serif;
+ font-family: 'Ubuntu', sans-serif;
}
diff --git a/docs/utils/_setup.js b/docs/utils/_setup.js
index 1360ca46..13896243 100644
--- a/docs/utils/_setup.js
+++ b/docs/utils/_setup.js
@@ -1,14 +1,6 @@
-const React = require('react');
+const React = require('react')
+const { Card } = require('antd')
-const defaultStyle = {
- background: '#FDFEFD',
- width: '250px',
- padding: '20px',
- textAlign: 'center',
- boxShadow: '0 0 10px rgba(20, 20, 20, .1)',
- margin: '10px auto',
-};
-
-const DisplayDemo = window.DisplayDemo = ({ style, ...props }) => (
- React.createElement('div', { style: { ...defaultStyle, ...style } }, props.children)
-);
+const DisplayDemo = window.DisplayDemo = (props) => (
+ React.createElement(Card, { bordered: true, hoverable: true, ...props }, props.children)
+)
diff --git a/docs/utils/_styleguidist.theme.js b/docs/utils/_styleguidist.theme.js
index f0897d5e..3bab7bc7 100644
--- a/docs/utils/_styleguidist.theme.js
+++ b/docs/utils/_styleguidist.theme.js
@@ -2,19 +2,16 @@ module.exports = {
// https://github.com/styleguidist/react-styleguidist/blob/master/src/client/styles/theme.ts
theme: {
color: {
- base: '#606f7b',
- text: '#606f7b',
+ base: '#2D3142',
+ text: '#2D3142',
link: '#1D6C8B',
linkHover: '#317995'
},
- baseColor: '#606f7b',
+ baseColor: '#2D3142',
fontFamily: {
base: '"Ubuntu", "sans-serif", light',
},
},
- template: {
- favicon: 'https://beautifulinteractions.com/favicons/bi-favicon.ico',
- },
styles: {
SectionHeading: {
wrapper: {
@@ -54,11 +51,12 @@ module.exports = {
},
Playground: {
preview: {
- border: '2px solid rgba(0, 0, 0, .05)',
- background: 'white',
- borderRadius: '5px',
- boxShadow: '0 0px 10px 0 rgba(93, 100, 148, 0.05)',
+ padding: 0,
+ border: 'none',
+ background: 'transparent',
+ //borderRadius: '6px',
+ // boxShadow: '0 0px 10px 0 rgba(93, 100, 148, 0.05)',
},
},
},
-};
+}
diff --git a/package.json b/package.json
index ad9ed560..a8eaba65 100644
--- a/package.json
+++ b/package.json
@@ -10,7 +10,7 @@
"build-cjs": "tsc --project ./tsconfig.cjs.json",
"build-esm": "tsc --project ./tsconfig.esm.json",
"build": "npx del-cli dist && npm run build-cjs && npm run build-esm && npm run build-types && echo 'Successfully built'",
- "build-doc": "npx del-cli dist-ghpages && npx styleguidist build",
+ "build-doc": "npx del-cli dist-ghpages && node scripts/generate-doc-append-types.js && npx styleguidist build",
"test": "nyc mocha --recursive --exit \"./test/**/*.spec.+(js|jsx)\"",
"test:watch": "npm run test -- --watch",
"start": "npx styleguidist server",
@@ -44,67 +44,62 @@
"lodash.throttle": "^4.1.1"
},
"peerDependencies": {
- "react": ">=16.0.0",
- "react-dom": ">=16.0.0",
- "react-router-dom": ">=5.0.0",
+ "react": "18.2.0",
+ "react-dom": "18.2.0",
+ "react-router-dom": ">=5.0.0 <=6.0.0",
"rxjs": ">=7.0.0"
},
"devDependencies": {
- "@babel/core": "7.18.2",
- "@babel/polyfill": "^7.10.4",
- "@babel/preset-env": "7.18.2",
- "@babel/preset-react": "7.17.12",
- "@babel/register": "^7.17.7",
- "@semantic-release/changelog": "6.0.1",
+ "@ant-design/icons": "5.0.1",
+ "@babel/core": "7.21.0",
+ "@babel/preset-env": "7.20.2",
+ "@babel/preset-react": "7.18.6",
+ "@babel/register": "^7.21.0",
+ "@semantic-release/changelog": "6.0.2",
"@semantic-release/commit-analyzer": "9.0.2",
"@semantic-release/exec": "6.0.3",
"@semantic-release/git": "10.0.1",
- "@semantic-release/github": "8.0.4",
- "@semantic-release/npm": "9.0.1",
- "@testing-library/react": "13.3.0",
- "@testing-library/react-hooks": "8.0.1",
+ "@semantic-release/github": "8.0.7",
+ "@semantic-release/npm": "9.0.2",
+ "@testing-library/react": "14.0.0",
+ "@testing-library/react-hooks": "6.0.0",
"@types/lodash.debounce": "4.0.7",
"@types/lodash.throttle": "4.1.7",
"@types/react-router-dom": "5.3.3",
- "@typescript-eslint/eslint-plugin": "5.27.1",
- "@typescript-eslint/parser": "5.27.1",
- "babel-eslint": "^10.1.0",
- "babel-loader": "^8.2.5",
+ "antd": "5.3.1",
+ "babel-loader": "^9.1.2",
"babel-plugin-istanbul": "^6.1.1",
"babel-plugin-transform-require-ignore": "^0.1.1",
- "beautiful-react-ui": "0.57.1",
- "chai": "^4.3.6",
- "css-loader": "^6.7.1",
- "eslint": "8.21.0",
- "eslint-config-airbnb-base": "4.0.2",
- "eslint-config-airbnb-typescript": "16.1.1",
- "eslint-plugin-chai-expect": "^3.0.0",
- "eslint-plugin-import": "1.11.0",
- "eslint-plugin-jsx-a11y": "6.6.1",
- "eslint-plugin-react": "7.30.1",
- "eslint-plugin-react-hooks": "4.5.0",
- "glob": "^8.0.3",
- "husky": "^8.0.1",
- "jsdoc-to-markdown": "^7.1.1",
- "jsdom": "^19.0.0",
+ "chai": "^4.3.7",
+ "css-loader": "^6.7.3",
+ "eslint": "8.36.0",
+ "eslint-config-standard-with-typescript": "34.0.0",
+ "eslint-plugin-import": "2.27.5",
+ "eslint-plugin-n": "15.6.1",
+ "eslint-plugin-promise": "6.1.1",
+ "eslint-plugin-react": "7.32.2",
+ "glob": "^9.2.1",
+ "husky": "^8.0.3",
+ "jsdoc-to-markdown": "^8.0.0",
+ "jsdom": "^21.1.1",
"jsdom-global": "^3.0.2",
- "mocha": "10.0.0",
+ "mocha": "10.2.0",
"mock-local-storage": "1.1.23",
"mutation-observer": "1.0.3",
"nyc": "^15.1.0",
- "react": "18.1.0",
- "react-dom": "18.1.0",
- "react-router-dom": "5.3.3",
- "react-styleguidist": "13.0.0",
- "regenerator-runtime": "0.13.9",
- "rxjs": "7.5.5",
- "semantic-release": "^19.0.3",
- "sinon": "^14.0.0",
+ "react": "18.2.0",
+ "react-dom": "18.2.0",
+ "react-router-dom": "5.3.4",
+ "react-styleguidist": "13.1.1",
+ "regenerator-runtime": "0.13.11",
+ "rxjs": "7.8.0",
+ "semantic-release": "^20.1.1",
+ "sinon": "^15.0.2",
"style-loader": "^3.3.1",
- "ts-loader": "9.3.0",
- "typescript": "4.7.3",
+ "ts-loader": "9.4.2",
+ "typescript": "4.9.5",
"url-loader": "^4.1.1",
- "webpack": "5.74.0"
+ "webpack": "5.76.1"
},
"exports": {
".": {
@@ -340,4 +335,4 @@
"require": "./useWindowScroll.js"
}
}
-}
\ No newline at end of file
+}
diff --git a/scripts/generate-doc-append-types.js b/scripts/generate-doc-append-types.js
new file mode 100644
index 00000000..08af1adb
--- /dev/null
+++ b/scripts/generate-doc-append-types.js
@@ -0,0 +1,44 @@
+const fs = require('fs/promises')
+const path = require('path')
+const { globSync } = require('glob')
+
+const docsPath = path.join(__dirname, '..', 'docs')
+const distPath = path.join(__dirname, '..', 'dist')
+const docFiles = globSync(`${docsPath}/*.md`)
+ .map((file) => file.replace(`${docsPath}/`, '').replace('.md', ''))
+ .filter((file) => file.startsWith('use'))
+
+docFiles.forEach(async (hook) => {
+ const docPath = path.join(docsPath, `${hook}.md`)
+ const typeFile = path.join(distPath, `${hook}.d.ts`)
+
+ const declarations = await fs.readFile(typeFile, { encoding: 'utf8' })
+ const document = await fs.readFile(docPath, { encoding: 'utf8' })
+
+ if (document.match(//g)) {
+ const cleared = emptyOldTypes(document).trim()
+ const nextDocument = cleared.replace('', template(declarations)).trim()
+
+ fs.writeFile(docPath, nextDocument, { encoding: 'utf8' }).then(() => {
+ console.log(`Updated "${hook}" types`)
+ })
+ }
+})
+
+const template = (content) => `
+### Types
+
+\`\`\`typescript static
+${content}
+\`\`\`
+
+`
+
+const emptyOldTypes = (content) => {
+ const regex = /[\s\S]*/g
+
+ return `${content.replace(regex, '\n').replace(//g, '').trim()}
+
+
+`
+}
diff --git a/scripts/generate-exports.js b/scripts/generate-exports.js
index 2a4fb696..bfef671c 100644
--- a/scripts/generate-exports.js
+++ b/scripts/generate-exports.js
@@ -2,14 +2,14 @@
const fs = require('fs')
const path = require('path')
-const glob = require('glob')
+const { globSync } = require('glob')
const srcPath = path.join(__dirname, '..', 'src')
const pkgPath = path.join(__dirname, '..', 'package.json')
-const srcFiles = glob.sync(`${srcPath}/*.ts`)
- .map((file) => file.replace(`${srcPath}/`, '').replace('.ts', ''))
- .filter((file) => file !== 'index')
+const srcFiles = globSync(`${srcPath}/*.ts`)
+ .map((file) => file.replace(`${srcPath}/`, '').replace('.ts', ''))
+ .filter((file) => file !== 'index')
const defaultExports = {
'.': {
@@ -22,7 +22,7 @@ const exportsObj = srcFiles.reduce((acc, file) => ({
...acc,
[`./${file}`]: {
import: `./esm/${file}.js`,
- require: `./${file}.js`,
+ require: `./${file}.js`
}
}), defaultExports)
diff --git a/src/factory/createHandlerSetter.ts b/src/factory/createHandlerSetter.ts
index 15f70b91..5cb1a5cb 100644
--- a/src/factory/createHandlerSetter.ts
+++ b/src/factory/createHandlerSetter.ts
@@ -1,5 +1,5 @@
-import { RefObject, useRef } from 'react'
-import { CallbackSetter, SomeCallback } from '../shared/types'
+import { type RefObject, useRef } from 'react'
+import { type CallbackSetter, type SomeCallback } from '../shared/types'
/**
* Returns an array where the first item is the [ref](https://reactjs.org/docs/hooks-reference.html#useref) to a
diff --git a/src/factory/createStorageHook.ts b/src/factory/createStorageHook.ts
index b12c9957..842cbc38 100644
--- a/src/factory/createStorageHook.ts
+++ b/src/factory/createStorageHook.ts
@@ -7,7 +7,7 @@ import noop from '../shared/noop'
import warnOnce from '../shared/warnOnce'
/**
- * An utility to quickly create hooks to access both Session Storage and Local Storage
+ * A utility to quickly create hooks to access both Session Storage and Local Storage
*/
const createStorageHook = (type: 'session' | 'local') => {
type SetValue = (value: TValue | ((previousValue: TValue) => TValue)) => void
@@ -20,10 +20,7 @@ const createStorageHook = (type: 'session' | 'local') => {
/**
* the hook
*/
- return function useStorageCreatedHook(
- storageKey: string,
- defaultValue?: any,
- ): [TValue, SetValue] {
+ return function useStorageCreatedHook (storageKey: string, defaultValue?: any): [TValue | null, SetValue] {
if (!isClient) {
if (isDevelopment) {
warnOnce(`Please be aware that ${storageName} could not be available during SSR`)
@@ -40,18 +37,18 @@ const createStorageHook = (type: 'session' | 'local') => {
}
}, [storage, storageKey])
- const [storedValue, setStoredValue] = useState(
+ const [storedValue, setStoredValue] = useState(
() => {
let valueToStore: string
try {
- valueToStore = storage.getItem(storageKey) || JSON.stringify(defaultValue)
+ valueToStore = storage.getItem(storageKey) ?? JSON.stringify(defaultValue)
} catch (e) {
valueToStore = JSON.stringify(defaultValue)
}
safelySetStorage(valueToStore)
return safelyParseJson(valueToStore)
- },
+ }
)
const setValue: SetValue = useCallback(
diff --git a/src/index.ts b/src/index.ts
deleted file mode 100644
index 4c36911b..00000000
--- a/src/index.ts
+++ /dev/null
@@ -1,65 +0,0 @@
-/**
- * This file is kept for compatibility reasons.
- * You should avoid importing hooks directly from this file.
- *
- * Avoid importing hooks like this:
- *
- * ```js
- * import { useSomething } from 'beautiful-react-hooks';
- * ```
- *
- * in favour of this:
- *
- * ```js
- * import useSomething from 'beautiful-react-hooks/useSomething';
- * ```
- */
-export { default as useDidMount } from './useDidMount'
-export { default as useWillUnmount } from './useWillUnmount'
-export { default as useLifecycle } from './useLifecycle'
-export { default as useWindowResize } from './useWindowResize'
-export { default as useWindowScroll } from './useWindowScroll'
-export { default as useDebouncedCallback } from './useDebouncedCallback'
-export { default as useThrottledCallback } from './useThrottledCallback'
-export { default as useMouse } from './useMouse'
-export { default as useMouseEvents } from './useMouseEvents'
-export { default as useMouseState } from './useMouseState'
-export { default as useTimeout } from './useTimeout'
-export { default as useInterval } from './useInterval'
-export { default as useGlobalEvent } from './useGlobalEvent'
-export { default as usePreviousValue } from './usePreviousValue'
-export { default as useGeolocation } from './useGeolocation'
-export { default as useGeolocationEvents } from './useGeolocationEvents'
-export { default as useGeolocationState } from './useGeolocationState'
-export { default as useMediaQuery } from './useMediaQuery'
-export { default as useValueHistory } from './useValueHistory'
-export { default as useOnlineState } from './useOnlineState'
-export { default as useViewportSpy } from './useViewportSpy'
-export { default as useValidatedState } from './useValidatedState'
-export { default as useDragEvents } from './useDragEvents'
-export { default as useDrag } from './useDrag'
-export { default as useDropZone } from './useDropZone'
-export { default as useRequestAnimationFrame } from './useRequestAnimationFrame'
-export { default as useLocalStorage } from './useLocalStorage'
-export { default as useSessionStorage } from './useSessionStorage'
-export { default as useResizeObserver } from './useResizeObserver'
-export { default as useDefaultedState } from './useDefaultedState'
-export { default as useObservable } from './useObservable'
-export { default as useSpeechSynthesis } from './useSpeechSynthesis'
-export { default as useSystemVoices } from './useSystemVoices'
-export { default as useRenderInfo } from './useRenderInfo'
-export { default as useSwipe } from './useSwipe'
-export { default as useHorizontalSwipe } from './useHorizontalSwipe'
-export { default as useVerticalSwipe } from './useVerticalSwipe'
-export { default as useSwipeEvents } from './useSwipeEvents'
-export { default as useConditionalTimeout } from './useConditionalTimeout'
-export { default as useInfiniteScroll } from './useInfiniteScroll'
-export { default as useQueryParam } from './useQueryParam'
-export { default as useQueryParams } from './useQueryParams'
-export { default as useSearchQuery } from './useSearchQuery'
-export { default as useEvent } from './useEvent'
-export { default as useViewportState } from './useViewportState'
-export { default as useToggle } from './useToggle'
-
-// keep it just for compatibility issues
-export { default as useStorage } from './factory/createStorageHook'
diff --git a/src/shared/geolocationUtils.ts b/src/shared/geolocationUtils.ts
index d770b449..b58f3bff 100644
--- a/src/shared/geolocationUtils.ts
+++ b/src/shared/geolocationUtils.ts
@@ -1,9 +1,9 @@
-import { BRHGeolocationPosition } from './types'
+import { type BRHGeolocationPosition } from './types'
export const geoStandardOptions: PositionOptions = Object.freeze({
enableHighAccuracy: false,
timeout: 0xFFFFFFFF,
- maximumAge: 0,
+ maximumAge: 0
})
/**
@@ -14,28 +14,30 @@ export const isSamePosition = (current: BRHGeolocationPosition, next: BRHGeoloca
if (current.timestamp && next.timestamp && current.timestamp !== next.timestamp) return false
return (
- (current.coords.latitude === next.coords.latitude)
- && (current.coords.longitude === next.coords.longitude)
- && (current.coords.altitude === next.coords.altitude)
- && (current.coords.accuracy === next.coords.accuracy)
- && (current.coords.altitudeAccuracy === next.coords.altitudeAccuracy)
- && (current.coords.heading === next.coords.heading)
- && (current.coords.speed === next.coords.speed)
+ (current.coords.latitude === next.coords.latitude) &&
+ (current.coords.longitude === next.coords.longitude) &&
+ (current.coords.altitude === next.coords.altitude) &&
+ (current.coords.accuracy === next.coords.accuracy) &&
+ (current.coords.altitudeAccuracy === next.coords.altitudeAccuracy) &&
+ (current.coords.heading === next.coords.heading) &&
+ (current.coords.speed === next.coords.speed)
)
}
/**
* Given a position object returns only its properties
*/
-export const makePositionObj = (position: BRHGeolocationPosition): BRHGeolocationPosition | null => (!position ? null : ({
- timestamp: position.timestamp,
- coords: {
- latitude: position.coords.latitude,
- longitude: position.coords.longitude,
- altitude: position.coords.altitude,
- accuracy: position.coords.accuracy,
- altitudeAccuracy: position.coords.altitudeAccuracy,
- heading: position.coords.heading,
- speed: position.coords.speed,
- },
-}))
+export const makePositionObj = (position: BRHGeolocationPosition) => (!position
+ ? null
+ : ({
+ timestamp: position.timestamp,
+ coords: {
+ latitude: position.coords.latitude,
+ longitude: position.coords.longitude,
+ altitude: position.coords.altitude,
+ accuracy: position.coords.accuracy,
+ altitudeAccuracy: position.coords.altitudeAccuracy,
+ heading: position.coords.heading,
+ speed: position.coords.speed
+ }
+ }))
diff --git a/src/shared/isFunction.ts b/src/shared/isFunction.ts
index 751cb3b8..3f83e4d7 100644
--- a/src/shared/isFunction.ts
+++ b/src/shared/isFunction.ts
@@ -1,8 +1,10 @@
-const isFunction = (functionToCheck: unknown): functionToCheck is Function => !!(
- typeof functionToCheck === 'function'
- && !!functionToCheck.constructor
- && !!functionToCheck.call
- && !!functionToCheck.apply
+type SomeFunction = (...args: any[]) => any
+
+const isFunction = (functionToCheck: unknown): functionToCheck is SomeFunction => (
+ typeof functionToCheck === 'function' &&
+ !!functionToCheck.constructor &&
+ !!functionToCheck.call &&
+ !!functionToCheck.apply
)
export default isFunction
diff --git a/src/shared/noop.ts b/src/shared/noop.ts
index b741fc6d..ce4480a9 100644
--- a/src/shared/noop.ts
+++ b/src/shared/noop.ts
@@ -1,6 +1,7 @@
-import { Noop } from './types'
+import { type Noop } from './types'
-const noop: Noop = () => undefined
+/* eslint-disable-next-line @typescript-eslint/no-unused-vars */
+const noop: Noop = (...args: any[]) => undefined
noop.noop = true
diff --git a/src/shared/safelyParseJson.ts b/src/shared/safelyParseJson.ts
index 12794b7e..d7d2c72d 100644
--- a/src/shared/safelyParseJson.ts
+++ b/src/shared/safelyParseJson.ts
@@ -1,4 +1,8 @@
-const safelyParseJson = (parseString: string): T => {
+/**
+ * Safely parse JSON string to object or null
+ * @param parseString
+ */
+const safelyParseJson = (parseString: string): T | null => {
try {
return JSON.parse(parseString)
} catch (e) {
diff --git a/src/shared/types.ts b/src/shared/types.ts
index edbce239..047a7999 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1,48 +1,42 @@
export interface Noop {
- noop: true,
+ noop: true
- (): void,
+ (...args: any[]): any
}
/**
* Represent a generic function.
* Used internally to improve code readability
*/
-export interface GenericFunction {
- (...args: any[]): any
-}
+export type GenericFunction = (...args: any[]) => any
/**
* Typed generic callback function, used mostly internally
* to defined callback setters
*/
-export interface SomeCallback {
- (...args: TArgs[]): TResult
-}
+export type SomeCallback = (...args: TArgs[]) => TResult
/**
* A callback setter is generally used to set the value of
* a callback that will be used to perform updates
*/
-export interface CallbackSetter {
- (nextCallback: SomeCallback): void
-}
+export type CallbackSetter = (nextCallback: SomeCallback) => void
/**
* This type is used internally to avoid using directly GeolocationPosition
* as that type is not always compatible with all typescript versions
*/
export interface BRHGeolocationPosition {
- readonly timestamp: number;
+ readonly timestamp: number
readonly coords: {
- readonly accuracy: number;
- readonly altitude: number | null;
- readonly altitudeAccuracy: number | null;
- readonly heading: number | null;
- readonly latitude: number;
- readonly longitude: number;
- readonly speed: number | null;
- };
+ readonly accuracy: number
+ readonly altitude: number | null
+ readonly altitudeAccuracy: number | null
+ readonly heading: number | null
+ readonly latitude: number
+ readonly longitude: number
+ readonly speed: number | null
+ }
}
/**
@@ -50,9 +44,9 @@ export interface BRHGeolocationPosition {
* as that type is not always compatible with all typescript versions
*/
export interface BRHGeolocationPositionError {
- readonly code: number;
- readonly message: string;
- readonly PERMISSION_DENIED: number;
- readonly POSITION_UNAVAILABLE: number;
- readonly TIMEOUT: number;
+ readonly code: number
+ readonly message: string
+ readonly PERMISSION_DENIED: number
+ readonly POSITION_UNAVAILABLE: number
+ readonly TIMEOUT: number
}
diff --git a/src/useAudio.ts b/src/useAudio.ts
index da582faf..c6d45fcd 100644
--- a/src/useAudio.ts
+++ b/src/useAudio.ts
@@ -1,4 +1,4 @@
-import { MutableRefObject, useCallback, useEffect, useRef } from 'react'
+import { type MutableRefObject, useCallback, useEffect, useRef } from 'react'
import noop from './shared/noop'
import isClient from './shared/isClient'
import useObjectState from './useObjectState'
@@ -7,74 +7,58 @@ import isAPISupported from './shared/isAPISupported'
import createHandlerSetter from './factory/createHandlerSetter'
import warnOnce from './shared/warnOnce'
-type UseAudioPreloadType = 'auto' | 'metadata' | 'none';
-
-export interface UseAudioOptions {
- loop?: boolean;
- muted?: boolean;
- volume?: number;
- autoPlay?: boolean;
- preload?: UseAudioPreloadType;
- playbackRate?: number;
-}
-
-interface LocalState {
- loop: boolean;
- muted: boolean;
- volume: number;
- duration: number;
- autoPlay: boolean;
- isPlaying: boolean;
- preload?: UseAudioPreloadType;
- currentTime: number;
- playbackRate: number;
- isSrcLoading: boolean | undefined;
-}
-
-interface Controls {
- play: () => void;
- mute: () => void;
- pause: () => void;
- unmute: () => void;
- seek: (time: number) => void;
- onError: (onError: ((error: Error) => void)) => void;
- setVolume: (volume: number) => void;
-}
-
+/**
+ * The default options for the useAudio hook
+ */
const defaultOptions: Required = {
volume: 1,
loop: false,
muted: false,
playbackRate: 1,
autoPlay: false,
- preload: 'auto',
+ preload: 'auto'
}
-const defaultState: LocalState = {
+/**
+ * The default state for the useAudio hook
+ */
+const defaultState: AudioState = {
duration: 0,
currentTime: 0,
isPlaying: false,
isSrcLoading: undefined,
- ...defaultOptions,
+ ...defaultOptions
}
+/**
+ * The error event code to message mapper
+ */
const errorEventCodeToMessageMapper: Record = {
3: 'MEDIA_ERR_DECODE - error occurred when decoding',
4: 'MEDIA_ERR_SRC_NOT_SUPPORTED - audio not supported',
2: 'MEDIA_ERR_NETWORK - error occurred when downloading',
1: 'MEDIA_ERR_ABORTED - fetching process aborted by user',
+ 0: 'UNKNOWN_ERROR - unknown error'
}
-const hookNotSupportedControls: Controls = Object.freeze({
+/**
+ * The hook not supported controls
+ */
+const hookNotSupportedControls: AudioControls = Object.freeze({
seek: noop,
play: noop,
mute: noop,
pause: noop,
unmute: noop,
onError: noop,
- setVolume: noop,
+ setVolume: noop
})
+/**
+ * Checks if the ref element exists and calls the callback with it
+ * @param ref
+ * @param callback
+ */
const checkIfRefElementExists = (ref: MutableRefObject, callback: (element: TElement) => unknown) => () => {
const element = ref.current
@@ -85,11 +69,14 @@ const checkIfRefElementExists = (ref: MutableRefObject, call
return callback(element)
}
+/**
+ * The useAudio hook wraps the Audio API and provides a set of controls to manage the audio
+ */
export const useAudio = (src: string, options?: UseAudioOptions) => {
const hookNotSupportedResponse = [
defaultState,
hookNotSupportedControls,
- useRef(null),
+ useRef(null)
]
if (!isClient) {
@@ -97,36 +84,38 @@ export const useAudio = (src: string, options?: UseAudioOptions) => {
warnOnce('Please be aware that useAudio hook could not be available during SSR')
}
- return hookNotSupportedResponse as [LocalState, Readonly, MutableRefObject]
+ return hookNotSupportedResponse as [AudioState, Readonly, MutableRefObject]
}
if (!isAPISupported('Audio')) {
warnOnce('The current device does not support the \'Audio\' API, you should avoid using useAudio hook')
- return hookNotSupportedResponse as [LocalState, Readonly, MutableRefObject