From 83bb1bd4d9c0d1bf1825b0d0ffe5ddca3fc5a2ef Mon Sep 17 00:00:00 2001 From: antonioru Date: Thu, 23 Feb 2023 21:43:12 +0100 Subject: [PATCH 1/2] chore(docs): documentation rewrite --- .eslintrc | 16 +++- README.md | 52 ++++++------- docs/Installation.md | 30 +++++--- docs/Introduction.md | 35 ++++----- docs/useAudio.md | 57 +++++++------- docs/useConditionalTimeout.md | 82 +++++++++++++------- docs/useCookie.md | 57 ++++++++------ docs/useDarkMode.md | 61 +++++++-------- docs/useDebouncedCallback.md | 74 ++++++++++++------ docs/useDefaultedState.md | 47 +++++++----- docs/useDidMount.md | 72 ++++++++--------- docs/useDrag.md | 17 ++-- docs/useDragEvents.md | 44 +++++------ docs/useDropZone.md | 29 ++++--- docs/useEvent.md | 38 ++++----- docs/useGeolocation.md | 57 ++++++++------ docs/useGeolocationEvents.md | 42 ++++++---- docs/useGeolocationState.md | 66 ++++++++-------- docs/useGlobalEvent.md | 44 +++++++---- docs/useInfiniteScroll.md | 58 ++++++++------ docs/useInterval.md | 44 +++++++---- docs/useIsFirstRender.md | 28 ++++--- docs/useLifecycle.md | 46 ++++++----- docs/useLocalStorage.md | 33 +++++--- docs/useMediaQuery.md | 31 ++++---- docs/useMouse.md | 76 +++++++++--------- docs/useMouseEvents.md | 80 ++++++++++--------- docs/useMouseState.md | 58 ++++++-------- docs/useMutationObserver.md | 39 ++++++---- docs/useObjectState.md | 45 +++++++---- docs/useObservable.md | 50 +++++++----- docs/useOnlineState.md | 27 +++++-- docs/usePreviousValue.md | 18 +++-- docs/useQueryParam.md | 20 +++-- docs/useQueryParams.md | 19 +++-- docs/useRenderInfo.md | 69 +++++++++-------- docs/useRequestAnimationFrame.md | 41 +++++----- docs/useResizeObserver.md | 96 ++++++++++++----------- docs/useSearchQuery.md | 17 ++-- docs/useSessionStorage.md | 35 ++++++--- docs/useSpeechSynthesis.md | 94 +++++++++++------------ docs/useSwipe.md | 26 ++++--- docs/useSwipeEvents.md | 27 +++---- docs/useSystemVoices.md | 46 ++++++----- docs/useThrottledCallback.md | 54 ++++++++----- docs/useTimeout.md | 39 ++++++---- docs/useToggle.md | 39 ++++++---- docs/useTouch.md | 79 ++++++++++--------- docs/useTouchEvents.md | 75 ++++++++++-------- docs/useTouchState.md | 66 ++++++++++------ docs/useURLSearchParams.md | 17 ++-- docs/useUpdateEffect.md | 30 +++----- docs/useValidatedState.md | 26 ++++--- docs/useValueHistory.md | 21 ++--- docs/useViewportSpy.md | 44 +++++++---- docs/useViewportState.md | 16 ++-- docs/useWillUnmount.md | 31 ++++---- docs/useWindowResize.md | 54 ++++++++----- docs/useWindowScroll.md | 36 ++++++--- docs/utils/_custom.css | 4 +- docs/utils/_setup.js | 18 ++--- docs/utils/_styleguidist.theme.js | 20 +++-- package.json | 8 +- scripts/generate-doc-append-types.js | 44 +++++++++++ src/factory/createStorageHook.ts | 5 +- src/index.ts | 65 ---------------- src/shared/noop.ts | 3 +- src/shared/types.ts | 2 +- src/useAudio.ts | 111 +++++++++++++++++---------- src/useConditionalTimeout.ts | 27 ++++--- src/useCookie.ts | 80 ++++++++++--------- src/useDarkMode.ts | 18 +++-- src/useDefaultedState.ts | 2 +- src/useDragEvents.ts | 14 +++- src/useDropZone.ts | 11 ++- src/useGeolocation.ts | 6 +- src/useGeolocationEvents.ts | 9 ++- src/useGeolocationState.ts | 12 ++- src/useSpeechSynthesis.ts | 23 ++++-- src/useSwipe.ts | 37 +++++---- src/useSwipeEvents.ts | 46 +++++++---- src/useSystemVoices.ts | 27 +------ src/useTouch.ts | 4 +- src/useTouchEvents.ts | 14 +++- src/useTouchState.ts | 6 +- src/useUpdateEffect.ts | 11 ++- src/useValidatedState.ts | 16 ++-- styleguide.config.js | 6 +- 88 files changed, 1881 insertions(+), 1438 deletions(-) create mode 100644 scripts/generate-doc-append-types.js delete mode 100644 src/index.ts diff --git a/.eslintrc b/.eslintrc index 0475b64f..7b18b303 100644 --- a/.eslintrc +++ b/.eslintrc @@ -17,12 +17,22 @@ "mocha": true }, "rules": { - "max-len": ["error", {"code": 140}], - "semi": [2, "never"], + "max-len": [ + "error", + { + "code": 140 + } + ], + "semi": [ + 2, + "never" + ], "@typescript-eslint/semi": "off", "linebreak-style": "off", "object-curly-newline": "off", - "react/jsx-filename-extension": "off" + "react/jsx-filename-extension": "off", + "import/no-named-as-default": "off", + "import/no-named-as-default-member": "off" }, "overrides": [ { diff --git a/README.md b/README.md index fc868935..bd70f93b 100644 --- a/README.md +++ b/README.md @@ -13,15 +13,14 @@ MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.or

- A collection of beautiful (and hopefully useful) React hooks to speed-up your - components and hooks development + A collection of tailor-made React hooks to enhance your development process and make it faster.

- 🌟 Live playground here 🌟 + 🌟 Hooks Playground 🌟

@@ -38,13 +37,13 @@ MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.or ## πŸ’‘ Why? -React custom hooks allow to abstract components' business logic into single reusable functions.
-So far, we've found that most of the hooks we've created and therefore shared between our internal projects have quite often a similar gist -that involves callback references, events and components' lifecycle.
-For this reason we've tried to sum up that gist into `beautiful-react-hooks`: a collection of (*hopefully*) useful React hooks to possibly -help other companies and professionals to speed up their development process.

-Furthermore, we created a concise yet concrete API having in mind the code readability, focusing to keep the learning curve as lower as -possible so that the it can be used and shared in bigger teams. +Custom React hooks allow developers to abstract the business logic of components into single, reusable functions.\ +I have noticed that many of the hooks I have created and shared across projects involve callbacks, references, events, and dealing with the +component lifecycle.\ +Therefore, I have created `beautiful-react-hooks`, a collection of useful [React hooks](https://beta.reactjs.org/reference/react) that may +help other developers speed up their development process.\ +Moreover, I have strived to create a concise and practical API that emphasizes code readability, while keeping the learning curve as low as +possible, making it suitable for larger teams to use and share **-- Please before using any hook, read its documentation! --** @@ -57,7 +56,7 @@ possible so that the it can be used and shared in bigger teams.

- 🌟 Live playground here 🌟 + 🌟 Hooks Playground 🌟

@@ -76,6 +75,14 @@ by using `yarn`: $ yarn add beautiful-react-hooks ``` +## Basic usage + +importing a hooks is as easy as the following straightforward line: + +```ts static +import useSomeHook from 'beautiful-react-hooks/useSomeHook' +``` + ## 🎨 Hooks * [useQueryParam](docs/useQueryParam.md) @@ -127,36 +134,29 @@ $ yarn add beautiful-react-hooks

- 🌟 Live playground here 🌟 + 🌟 Hooks Playground 🌟

## Peer dependencies -Some hooks are built on top of third-party libraries (rxjs, react-router-dom, redux), therefore you will notice those libraries listed as -peer dependencies. You don't have to install these dependencies unless you directly use those hooks. +Some hooks are built using third-party libraries (such as rxjs, react-router-dom, redux). As a result, you will see these libraries listed +as peer dependencies.\ +Unless you are using these hooks directly, you need not install these dependencies. ## Contributing Contributions are very welcome and wanted. -To submit your custom hook, please make sure your read our [CONTRIBUTING](./CONTRIBUTING.md) guidelines. +To submit your custom hook, make sure you have thoroughly read and understood the [CONTRIBUTING](./CONTRIBUTING.md) guidelines. -**Before submitting** a new merge request, please make sure: +**Prior to submitting your pull request**: please take note of the following 1. make sure to write tests for your code, run `npm test` and `npm build` before submitting your merge request. -2. in case you're creating a custom hook, make sure you've added the documentation (*you can possibly use +2. in case you're creating a custom hook, make sure you've added the documentation (*you may use the [HOOK_DOCUMENTATION_TEMPLATE](./HOOK_DOCUMENTATION_TEMPLATE.md) to document your custom hook*). -### Made with - -* [React](https://reactjs.org/) -* [Mocha](https://mochajs.org/) -* [Chai](https://www.chaijs.com/) -* [@testing-library/react](https://testing-library.com/docs/react-testing-library/intro) -* [@testing-library/react-hooks](https://react-hooks-testing-library.com/) - ---- +## Credits Icon made by [Freepik](https://www.flaticon.com/authors/freepik) from [www.flaticon.com](https://www.flaticon.com/free-icon/hook_1081812) diff --git a/docs/Installation.md b/docs/Installation.md index 5500f09e..bb46c36f 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -21,28 +21,40 @@ import useSomeHook from 'beautiful-react-hoks/useSomeHook' **Please note**: always import your hook from the library as a single module to avoid importing unnecessary hooks and therefore unnecessary dependencies +## Peer dependencies + +Some hooks are built on top of third-party libraries (rxjs, react-router-dom, redux), therefore you will notice those libraries listed as +peer dependencies. You don't have to install these dependencies unless you directly use those hooks. + ## Working with Refs in TypeScript The documentation of this module is written in JavaScript, so you will see a lot of this: -```javascript +```jsx static import { ref } from 'react'; -const ref = useRef() +const myCustomHook = () => { + const ref = useRef() + + /* your code */ + + return ref; +} ``` If you are in a TypeScript project, you should declare your ref as a `RefObject`. For example: -```ts +```ts static import { ref } from 'react'; -const ref = useRef(null); +const myCustomHook = () => { + const ref = useRef(null); + + /* your code */ + + return ref; +} ``` See [here](https://dev.to/wojciechmatuszewski/mutable-and-immutable-useref-semantics-with-react-typescript-30c9) for information on the difference between a `MutableRefObject` and a `RefObject`. - -## Peer dependencies - -Some hooks are built on top of third-party libraries (rxjs, react-router-dom, redux), therefore you will notice those libraries listed as -peer dependencies. You don't have to install these dependencies unless you directly use those hooks. diff --git a/docs/Introduction.md b/docs/Introduction.md index cf9cf30c..632a7329 100644 --- a/docs/Introduction.md +++ b/docs/Introduction.md @@ -5,36 +5,35 @@ ![npm](https://img.shields.io/npm/v/beautiful-react-hooks) ![GitHub stars](https://img.shields.io/github/stars/beautifulinteractions/beautiful-react-hooks?style=social) -Beautiful React Hooks is a collection of beautiful (and hopefully useful) React hooks to speed-up your components and hooks development. +`beautiful-react-hooks` is a collection of tailor-made [React hooks](https://beta.reactjs.org/reference/react) to enhance your development +process and make it faster. ## πŸ’‘ Why? -React custom hooks allow abstracting components' business logic into single reusable functions.
-So far, I've found that most of the hooks I've created and therefore shared between my projects have quite often a similar gist that -involves callback references, events and components' lifecycle.
-For this reason I've tried to sum up that gist into `beautiful-react-hooks`: a collection of (*hopefully*) useful React hooks to possibly -help other developers to speed up their development process.

-Furthermore, I've tried to create a concise yet concrete API having in mind the code readability, focusing to keep the learning curve as -lower as possible so that the it can be used and shared in bigger teams. +Custom React hooks allow developers to abstract the business logic of components into single, reusable functions.
+I have noticed that many of the hooks I have created and shared across projects involve callbacks, references, events, and dealing with the +component lifecycle.
+Therefore, I have created `beautiful-react-hooks`, a collection of useful [React hooks](https://beta.reactjs.org/reference/react) that may +help other developers speed up their development process.
+Moreover, I have strived to create a concise and practical API that emphasizes code readability, while keeping the learning curve as low as +possible, making it suitable for larger teams to use and share ## β˜•οΈ Features * Concise API * Small and lightweight * Easy to learn -* Functional approach -* Fully written in JS (although TS types are supported) -## Peer dependencies - -Some hooks are built on top of third-party libraries (rxjs, react-router-dom, redux), therefore you will notice those libraries listed as -peer dependencies. You don't have to install these dependencies unless you directly use those hooks. - -## Imports +## Basic usage -Despite having an `index.ts` file, it's recommended importing the hooks from the library in the following fashion to avoid importing -unnecessary hooks and therefore unnecessary dependencies +importing a hooks is as easy as the following straightforward line: ```ts static import useSomeHook from 'beautiful-react-hooks/useSomeHook' ``` + +## Peer dependencies + +Some hooks are built using third-party libraries (such as rxjs, react-router-dom, redux). As a result, you will see these libraries listed +as peer dependencies.\ +Unless you are using these hooks directly, you need not install these dependencies. diff --git a/docs/useAudio.md b/docs/useAudio.md index 01bbcec9..d9cd3a0c 100644 --- a/docs/useAudio.md +++ b/docs/useAudio.md @@ -1,52 +1,49 @@ # useAudio -Creates