From e2973d4b2132e38571fea2e2fe3e29784153182f Mon Sep 17 00:00:00 2001 From: Marlon Marcello Date: Mon, 27 Nov 2023 21:14:30 -0800 Subject: [PATCH] wip: fixes readme --- README.md | 280 +----------------------------------------------------- 1 file changed, 1 insertion(+), 279 deletions(-) diff --git a/README.md b/README.md index ef1fae7..b1c7444 100644 --- a/README.md +++ b/README.md @@ -2,282 +2,4 @@ A collection of helpers for use in React projects. -Jump to a section: - -- [useAsync](#useAsync) -- [useInView](#useInView) -- [useLocalStorage](#useLocalStorage) -- [usePreventScroll](#usePreventScroll) -- [useUserPrefs](#useUserPrefs) - -## Installation - -Install from the NPM registry using your package manager of choice. - -```bash -npm install @wethegit/react-hooks -``` - -## Hooks - -### `useAsync` - -Manages the calling of an asynchronous JavaScript function, while providing the return data and the state of the function call. -`useAsync(asyncFn, [deferred])` - -#### Arguments - -| Arguments | Type | Description | -| --------- | -------- | ------------------------------------------------------------------------ | -| asyncFn | Function | A JavaScript function which returns a Promise. | -| deferred | Boolean | Optional. Whether to defer the execution of `asyncFn`. Default: `false`. | - -#### Return value - -`useAsync` returns an Object containing the following properties: - -| Property | Type | Description | -| -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| data | - | The data returned from the resolved Promise, as a result of calling `asyncFn`. | -| status | String | One of: `"idle"`, `"pending"`, `"success"`, or `"error"`. | -| error | String | The error, if applicable, as thrown by `asyncFn`. | -| run | Function | The function to invoke at a later time, which calls `asyncFn`. This will be null if the `deferred` argument was passed as `false`. | - -#### Usage - -Instant invocation of the provided async function: - -```jsx -import { useAsync } from "@wethegit/react-hooks" - -const MyComponent = () => { - const { data, status, error } = useAsync(() => - fetch("https://my-cool-api.com/some-endpoint") - ) - - console.log(data, status, error) -} -``` - -Deferred invocation of the provided async function: - -```jsx -import { useAsync } from "@wethegit/react-hooks" - -const MyComponent = () => { - const { run, data, status, error } = useAsync( - () => fetch("https://my-cool-api.com/some-endpoint"), - true - ) - - const getMyData = () => { - if (data) return - run() - } - - console.log(data, status, error) - - return -} -``` - -### `useInView` - -Detects whether a DOM element is in the viewport, using the `IntersectionObserver` API. -`useInView([threshold], [once], [setInViewIfScrolledPast])` - -#### Arguments - -| Arguments | Type | Description | -| ----------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| threshold | Float | Default: `0.3`. A value between 0 and 1, which maps to a percentage of the DOM element's height. Once this amount of the DOM element is within the viewport, the hook will consider the element "in view". This value is directly passed to an `IntersectionObserver`, so for more details on what this argument means, check out the [IntersectionObserver docs](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) on MDN. | -| once | Boolean | Default: `true`. Whether to detach the observer from the DOM element after the first intersection callback is invoked. | -| setInViewIfScrolledPast | Boolean | Default: `true`. Whether to consider the element already "in-view", if the top of it is already scrolled beyond the bounds of the viewport when this hook is called. | - -#### Return value - -`useInView` returns an Array containing the following values: - -| Return value | Type | Description | -| -------------- | --------- | ---------------------------------------------------------------------------------------- | -| setTargetRef | Function | Pass this function to the `ref` prop of the DOM element you want to track visibility of. | -| isIntersecting | Boolean | Whether the target DOM element is in view, based on the provided `threshold` argument. | -| targetRef | React Ref | The DOM node itself, once set by the `setTargetRef` function. | - -#### Usage - -Toggling a className on and off, based on whether a `
` is in view: - -```jsx -import { useInView } from "@wethegit/react-hooks" - -const IN_VIEW_CLASSNAME = "in-view" - -const MyComponent = () => { - const [setSectionRef, sectionInView, section] = useInView() - - return ( - <> -
-

Sit quis ut id sit anim. Enim qui est ut tempor sunt.

-
- - ) -} -``` - -### `useLocalStorage` - -Reads and writes a piece of state to the browser's local storage. -`useLocalStorage(key, [defaultValue])` - -#### Arguments - -| Arguments | Type | Description | -| ------------ | ------ | ---------------------------------------------------------------------------- | -| key | String | The name of the property you wish to save to `localStorage`. | -| defaultValue | String | Default: `""`. The default / initial value to set to the `localStorage` key. | - -#### Return Value - -`useLocalStorage` returns an Array containing the following values: - -| Arguments | Type | Description | -| --------- | -------- | ------------------------------------------------------------------------------ | -| state | String | The current value of the `localStorage` key in the browser. | -| setState | Function | State setter function, used to update the `localStorage` value in the browser. | - -#### Usage - -Setting a `localStorage` value for a user's favorite fruit, based on their selection: - -```jsx -import { useLocalStorage } from "@wethegit/react-hooks" - -const FRUITS = ["Apple", "Banana", "Orange"] - -const FruitSelector = () => { - const [fruit, setFruit] = useLocalStorage("fruit") - - return ( - <> -
-
- Select your favorite fruit -
    - {FRUITS.map((fruit) => ( -
  • - setFruit(fruit)} - /> - -
    • - ))} -
-
-
- - {fruit &&

Your favorite fruit is {fruit}

} - - ) -} -``` - -### `usePreventScroll` - -Toggles the `overflow: hidden` CSS declaration on the `` DOM element. -`usePreventScroll(state)` - -#### Arguments - -| Arguments | Type | Description | -| --------- | ------- | ----------------------------------------------------- | -| state | Boolean | Whether to prevent scrolling on the `` element. | - -#### Usage - -Toggling scrollability of the `` element, based on whether a modal window is displayed: - -```jsx -import { usePreventScroll } from "@wethegit/react-hooks" -import { useState } from "react" - -const MyComponent = () => { - const [modalIsOpen, setModalIsOpen] = useState(false) - - usePreventScroll(modalIsOpen) - - return ( - <> -