https://github.com/galiprandi/react-tools
A set of simple and intuitive utilities for developing React applications.
https://github.com/galiprandi/react-tools
component library react typescript
Last synced: about 1 year ago
JSON representation
A set of simple and intuitive utilities for developing React applications.
- Host: GitHub
- URL: https://github.com/galiprandi/react-tools
- Owner: galiprandi
- Created: 2024-05-10T01:48:25.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-23T01:33:26.000Z (about 2 years ago)
- Last Synced: 2024-05-23T01:33:55.172Z (about 2 years ago)
- Topics: component, library, react, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@galiprandi/react-tools
- Size: 197 KB
- Stars: 2
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
#### Welcome to `@galiprandi/react-tools`, a set of simple and intuitive utilities for developing React applications. This package includes key tools that can streamline your development process, all while being dependency-free.
### Playground
Try out the components in the playground: [@galiprandi/react-tools Playground](https://stackblitz.com/edit/ga-react-tools?file=index.html)
### Installation
To install use one of the following commands:
```bash
npm i @galiprandi/react-tools
```
```bash
pnpm i @galiprandi/react-tools
```
```bash
yarn add @galiprandi/react-tools
```
## Components:
- ``: A component that wraps the form HTML tag and provides a simple way to create forms in your React application.
[Example](#form-component)
- ``: A reusable input component that provides a consistent user experience.
[Example](#input-component)
- ``: A reusable input component with `type="datetime-local"` that use dates in RFC 3339 format. [Example](#datetime-component)
- ``: A component that wraps the dialog HTML tag and provides a simple way to create accessibility dialogs and modals in your React application. [Example](#dialog-component)
- ``: A component allows you to track when an element enters or exits the viewport. This is useful for lazy loading images, infinite scrolling, and more. [Example](#observer-component)
## Hooks:
- `useDebounce()`: A hook that takes two arguments, value and delay, and return a debounced value. [Example](#usedebounce-hook)
## Components
### Form component
A component that wraps the `form` HTML tag and provides a simple way to create forms in your React application.
#### Adicional Props:
- `onSubmitValues:` Callback function that is called when the form is submitted and recibe a object with the form values.
- `filterEmptyValues:` Boolean, defines if the empty values are filtered from the object passed to the `onSubmitValues` callback. (Default: false)
#### Example:
```js
import { Form, Input } from '@galiprandi/react-tools'
import { useState } from 'react'
export const FormExample = () => {
const [values, setValues] = useState()
return (
Form
onSubmitValues={setValues}
filterEmptyValues={true}
>
Form Example
Login
onChangeISOValue: {JSON.stringify(values)}
)
}
type MyFormValues = {
username: string
password: string
}
```
### Input component
A simple wrapper around the native `input` element. It accepts all the same props as the native input element and adds a few additional props for convenience.
#### Adicional Props:
- `label`: A label for the input element. If provided, we add a label element with the provided text.
- `onChangeValue`: A callback function that is called when the input value changes
- `onChangeDebounce`: A callback function that is called when the input value changes after the debounce delay.
- `debounceDelay`: The delay in milliseconds for the debounce.
- `className`: A class name to apply to the input element. If a label is provided, the class name is applied to the label and input elements.
- `transform`: The type of transformation to apply to the input value. Options include "toUpperCase", "toLowerCase", "capitalize", "titleCase", "snakeCase", "onlyNumbers", "onlyLetters", "onlyEmail" and "onlyAlphanumeric"
- `transformFn`: A custom function to apply to the input value. This function takes a string as input and returns a string as output. If both transform and transformFn are provided, the transformFn function will take precedence.
- `datalist`: An array of strings to use as options in a datalist element.
#### Example:
```js
import { useState } from "react";
import { Input, type InputProps } from '@galiprandi/react-tools';
export const InputExample = () => {
const [value, setValue] = useState();
const [valueDebounced, setValueDebounced] = useState();
return (
Input
Transformed value: {value}
Debounced value (1s): {valueDebounced}
);
};
```
### DateTime component
A simple wrapper around the native `input` element with `type="datetime-local"`. It accepts all the same props as the native input element and adds a few additional props for convenience.
#### Adicional Props:
- `label`: A label for the input element. If provided, we add a label element with the provided text.
- `className`: A class name to apply to the input element. If a label is provided, the class name is applied to the label and input elements.
- `onChangeValue`: A callback function that is called when the input value changes.
- `onChangeISOValue`: A callback function that is called when the input value changes and returns the date in RFC 3339 format.
- `isoValue`: The date in RFC 3339 format.
- Any other prop that the our `Input` component accepts (like `onChangeDebounce`, `transform` and `transformFn`).
#### Example:
```js
import { useState } from 'react';
import { DateTime, type DateTimeProps } from '@galiprandi/react-tools';
export const DateTimeExample = () => {
const now = new Date().toISOString();
const [isoValue, setIsoValue] = useState(now);
return (
DateTime
onChangeISOValue: {isoValue}
);
};
```
### Dialog component
A component that wraps the `dialog` HTML tag and provides a simple way to create accessibility dialogs and modals in your React application.
#### Adicional Props:
- `isOpen:` Boolean, defines if the dialog is open or closed. (Optional)
- `behavior:` 'dialog' | 'modal', defines the behavior of the dialog. (Default: 'modal')
- `onOpen:` Callback function executed when the dialog is opened. (Optional)
- `onClose:` Callback function executed when the dialog is closed. (Optional)
- `children:` ReactNode, the content of the dialog. (Optional)
- `opener:` ReactNode, the element that opens the dialog. (Optional)
#### Example:
```js
import { Dialog } from '@galiprandi/react-tools'
export const DialogExample = () => {
return (
Dialog
Toggle Dialog}
onOpen={() => console.info('Dialog opened')}
onClose={() => console.info('Dialog closed')}
>
Hello there 👋
This is a dialog example.
For information on how to use html dialogs, or styling them,
{' '}
check documentation on MDN website
)
}
```
### Observer component
A component that allows you to track when an element enters or exits the viewport. This is useful for lazy loading images, infinite scrolling, and more.
#### Adicional Props:
- `children:` ReactNode, the content of the observer.
- `onAppear:` Callback function executed when the element enters the viewport. (Optional)
- `onDisappear` Callback function executed when the element exits the viewport. (Optional)
- `wrapper:` HTMLElement, the element that is used as wrapper of children. (Default: 'div')
- `root:` HTMLElement, the element that is used as the viewport for checking visibility of the target. (Optional)
- `rootMargin` Margin around the root. Can have values similar to the CSS margin property, e.g. "10px 20px 30px 40px" (top, right, bottom, left). The values can be percentages. (Optional)
- `threshold` Number, a number between 0 and 1 indicating the percentage of the target's visibility the observer's callback should be executed. (Default: 0)
#### Example:
```js
import { Observer } from '@galiprandi/react-tools'
import { useState } from 'react'
export const ObserveExample = () => {
const [inScreen, setInScreen] = useState([])
const images = Array.from({ length: 5 }, (_, i) => i + 1)
return (
Observer
A component that allows you to track when an element enters
or exits the viewport. This is useful for lazy loading
images, infinite scrolling, and more.
Images in screen: {inScreen.join(' | ')}
{images.map((i) => (
setInScreen((prev) => Array.from(new Set([...prev, i])))
}
onDisappear={() =>
setInScreen((prev) => prev.filter((item) => item !== i))
}
threshold={0.5}
>
<>
>
))}
)
}
```
## Hooks
### useDebounce hook
A simple hook that takes two arguments, value and delay, and returns a debounced value. Its used internally by some components, but you can use it in your custom hooks or components.
#### Example:
```js
import { useDebounce } from '@galiprandi/react-tools'
import { useState } from 'react'
export const DebounceExample = () => {
const [value, setValue] = useState()
const debouncedValue = useDebounce(value, 1000)
return (
useDebounce
setValue(e.target.value)}
/>
Value: {value}
Debounced value (1s): {debouncedValue}
)
}
```
## Contribution
Contributions are welcome! To contribute:
1. Fork this repository.
2. Create a branch with a meaningful description.
3. Make the desired changes.
4. Update the **documentation** if necessary.
5. Open a Pull Request to the main branch.
If you find an issue or have a suggestion to improve the project, feel free to [open an issue](https://github.com/galiprandi/react-tools/issues).
## License
This project is licensed under the MIT License.