Skip to content

Commit

Permalink
chore(docs): documentation rewrite
Browse files Browse the repository at this point in the history
  • Loading branch information
antonioru committed Mar 13, 2023
1 parent cadce30 commit 83bb1bd
Show file tree
Hide file tree
Showing 88 changed files with 1,881 additions and 1,438 deletions.
16 changes: 13 additions & 3 deletions .eslintrc
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
{
Expand Down
52 changes: 26 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,14 @@ MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.or
<br />
<div>
<p align="center">
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.
</p>
</div>

<div>
<p align="center">
<a href="https://antonioru.github.io/beautiful-react-hooks/" target="_blank">
🌟 Live playground here 🌟
🌟 Hooks Playground 🌟
</a>
</p>
</div>
Expand All @@ -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.<br />
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. <br />
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.<br /><br />
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! --**

Expand All @@ -57,7 +56,7 @@ possible so that the it can be used and shared in bigger teams.
<div>
<p align="center">
<a href="https://antonioru.github.io/beautiful-react-hooks/" target="_blank">
🌟 Live playground here 🌟
🌟 Hooks Playground 🌟
</a>
</p>
</div>
Expand All @@ -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)
Expand Down Expand Up @@ -127,36 +134,29 @@ $ yarn add beautiful-react-hooks
<div>
<p align="center">
<a href="https://antonioru.github.io/beautiful-react-hooks/" target="_blank">
🌟 Live playground here 🌟
🌟 Hooks Playground 🌟
</a>
</p>
</div>

## 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)
30 changes: 21 additions & 9 deletions docs/Installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<T extends HTMLElement>`. For example:

```ts
```ts static
import { ref } from 'react';

const ref = useRef<HTMLDivElement>(null);
const myCustomHook = () => {
const ref = useRef<HTMLDivElement>(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.
35 changes: 17 additions & 18 deletions docs/Introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.<br />
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. <br />
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.<br /><br />
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.<br />
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. <br />
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.<br/>
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.
57 changes: 27 additions & 30 deletions docs/useAudio.md
Original file line number Diff line number Diff line change
@@ -1,52 +1,49 @@
# useAudio

Creates <audio> element, tracks its state and exposes playback controls.
Creates an `<audio>` element, monitors its state and provides access to playback controls.

### Why? 💡

- A quick way to use the `Audio` in your React components.
- A speedy approach to integrating the audio feature into your React component
- Enhances the readability of components involving the audio feature

### Basic Usage:

```jsx harmony
import { useRef, useState } from 'react';
import { Button } from 'beautiful-react-ui';
import { Button, Typography } from 'antd';
import { PlayCircleFilled, PauseCircleFilled } from '@ant-design/icons';

import useAudio from 'beautiful-react-hooks/useAudio';

const UseAudioComponent = () => {
const [state, controls] = useAudio("https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3", { autoPlay: true });
const code = JSON.stringify(state, null, '\t');

const Actions = [
<Button onClick={controls.play} shape="round" icon={<PlayCircleFilled />} />,
<Button onClick={controls.pause} shape="round" icon={<PauseCircleFilled />} />,
<Button onClick={controls.mute}>
Mute
</Button>,
<Button onClick={() => controls.setVolume(state.volume + 0.1)}>Vol +1</Button>,
<Button onClick={() => controls.setVolume(state.volume - 0.1)}>Vol -1</Button>,
<Button onClick={() => controls.seek(state.currentTime + 10)}>+10 secs</Button>,
<Button onClick={() => controls.seek(state.currentTime - 10)}>-10 secs</Button>
]

return (
<DisplayDemo>
{JSON.stringify(state, null, 2)}
<br />
<Button onClick={controls.play}>
Play
</Button>
<Button onClick={controls.pause}>
Pause
</Button>
<br />
<Button onClick={controls.mute}>
Mute
</Button>
<Button onClick={controls.unmute}>
Unmute
</Button>
<br />
<Button onClick={() => controls.setVolume(.1)}>Volume: 10%</Button>
<Button onClick={() => controls.setVolume(.5)}>Volume: 50%</Button>
<Button onClick={() => controls.setVolume(1)}>Volume: 100%</Button>
<br />
<Button onClick={() => controls.seek(state.currentTime + 10)}>
Jump 10 seconds
</Button>
<Button onClick={() => controls.seek(state.currentTime - 10)}>
Jump -10 seconds
</Button>
<DisplayDemo title="useAudio" actions={Actions}>
<Typography.Paragraph code>
<pre>
{code}
</pre>
</Typography.Paragraph>
</DisplayDemo>
);
};

<UseAudioComponent />
```

<!-- Types -->
Loading

0 comments on commit 83bb1bd

Please sign in to comment.