# Material UI integrated components for Reevolve

this package provides a comprehensive set of customizable and reusable Material UI integrated components for Reevolve.

## Overview

- **Material-UI Integration**: All components are fully compatible with MUI theme, allowing for consistent styling across your application.
- **Localization Support**: A built-in localization system enables easy integration with custom translation systems, helping to localize your app without adding additional dependencies.
- **TypeScript:** type definitions come built-in in the package
- **Accessibility Support**: Built with accessibility in mind, adhering to MUI's best practices.
- **Fully responsive UI**
- **Customizable and Extendable**
- **RTL Support**

## Installation

To use the components in your project, you can install the package using npm or yarn:

```bash
npm install @reevolve/components
```

### Peer Dependencies

```bash
npm install @mui/material @emotion/react @emotion/styled
```

## Table of Contents

- [Basic Usage](#basic-usage)
- [Localization](#localization)
  - [useLocalization](#uselocalization)
  - [LocaleText](#localetext)
- [Customization](#customization)
- [Hooks](#hooks)
  - [useDefaultProps](#usedefaultprops)
- [Utilities](#utilities)
  - [fData](#fdata)
  - [isRtlText](#isrtltext)
  - [isReactRef](#isreactref)
  - [propsMerge](#propsmerge)
- [React Hook Form Components](#react-hook-form-components)
  - [RHFForm](#rhfform)
  - [RHFTextField](#rhftextfield)
  - [RHFNumberField](#rhfnumberfield)
  - [RHFPassword](#rhfpassword)
  - [RHFCheckbox](#rhfcheckbox)
  - [RHFSwitch](#rhfswitch)
  - [RHFRadioGroup](#rhfradiogroup)
  - [RHFDatePicker](#rhfdatepicker)
  - [RHFTimePicker](#rhftimepicker)
  - [RHFDateTimePicker](#rhfdatetimepicker)
  - [RHFAutocomplete](#rhfautocomplete)
  - [RHFSelect](#rhfselect)
  - [RHFMultiSelect](#rhfmultiselect)
  - [RHFLocationPicker](#rhflocationpicker)
  - [RHFUpload](#rhfupload)
  - [RHFCodeField](#rhfcodefield)
- [TextField](#textfield)
- [Password](#password)
- [Checkbox](#checkbox)
- [Switch](#switch)
- [Select](#select)
- [MultiSelect](#multiselect)
- [Date Pickers](#date-pickers)
  - [DatePicker](#datepicker)
  - [TimePicker](#timepicker)
  - [DateTimePicker](#datetimepicker)
  - [PickersLocalizationProvider](#pickerslocalizationprovider)
- [Spin](#spin)
- [LocationPicker](#locationpicker)
- [LocationView](#locationview)
- [Upload](#upload)
- [CodeField](#codefield)
- [Image](#image)
- [NumberField](#numberfield)
- [FileThumbnail](#filethumbnail)

## Basic Usage

This example demonstrates how to build a simple form using the `@reevolve/components`. The form leverages the LocalizationProvider for localized validation messages and the RHFForm components for seamless integration with React Hook Form. It also integrates with Material-UI's theming capabilities for consistent styling.

```tsx
import React from 'react';
import { RHFForm, RHFTextField, LocalizationProvider } from '@reevolve/components';
import { Button, ThemeProvider } from '@mui/material';
import { useForm } from 'react-hook-form';

function App() {
	const methods = useForm();

	const onSubmit = methods.handleSubmit((data) => {
		console.log('Form Data:', data);
	});

	return (
		<ThemeProvider theme={/*your application theme*/}>
			<LocalizationProvider
				lang="fa"
				// Customize local texts
				localeText={{ 'validation.required': () => 'این فیلد اجباری است' }}
			>
				<RHFForm
					methods={methods}
					onSubmit={onSubmit}
				>
					<RHFTextField
						name="name"
						label="Name"
					/>
					<RHFNumberField
						name="age"
						label="Age"
					/>
					<Button
						type="submit"
						variant="contained"
						color="primary"
					>
						Submit
					</Button>
				</RHFForm>
			</LocalizationProvider>
		</ThemeProvider>
	);
}

export default App;
```

## Localization

**Localization Provider** allows you to easy manage translation and localization of components. The provider uses a context-based approach to deliver translation functionality across all components, ensuring that any text in the components can be translated dynamically.

The Localization Provider can be customized with your own set of translation keys, and it supports a default language system for managing translations across different locales. This makes it easy to integrate into your existing multilingual applications.

### usage example

```tsx
import { LocalizationProvider } from '@reevolve/components';

function App() {
  return (
    <LocalizationProvider
      lang={/*Application language*/}
      localeText={/*Customize local texts*/}
    >
      {/* use components Here*/}
    </LocalizationProvider>
  )
}
```

### useLocalization

Returns the localization context value. Must be used inside `LocalizationProvider`.

```tsx
import { useLocalization } from '@reevolve/components';

function MyComponent() {
  const { translate, lang } = useLocalization();

  return <span>{translate('select.emptyOptionLabel')}</span>;
}
```

| Prop / Return | Type | Description |
| ------------- | ---- | ----------- |
| `lang` | `string` | Current language code (default: `"en"`). |
| `translate` | `(key: keyof LocaleText, params?: any) => string` | Resolves a localization key to text. |

### LocaleText

The `LocaleText` and `LocalizationContextType` interfaces (exported from `@reevolve/components`) define all built-in translation keys, including validation messages, autocomplete labels, date picker labels, upload messages, and map-related strings. Pass partial overrides via `LocalizationProvider`'s `localeText` prop.

---

## Customization

Just like other MUI components, **Reevolve components** can be customized globally using the `theme.components` configuration. This allows you to define default props, styles, and variants via the theme in a consistent and centralized way.

Refer to [MUI's customization guide](https://mui.com/material-ui/customization/theme-components/) for general theming patterns.

### Supported components

You can define defaults and overrides for the following Reevolve components in your theme:

| Component            | Theme key (`theme.components`)   |
| -------------------- | -------------------------------- |
| `TextField`          | `ReevolveTextField`                |
| `Password`           | `ReevolvePassword`                 |
| `Checkbox`           | `ReevolveCheckbox`                 |
| `Switch`             | `ReevolveSwitch`                   |
| `Select`             | `ReevolveSelect`                   |
| `MultiSelect`        | `ReevolveMultiSelect`              |
| `DatePicker`         | `ReevolveDatePicker`               |
| `TimePicker`         | `ReevolveTimePicker`               |
| `DateTimePicker`     | `ReevolveDateTimePicker`           |
| `NumberField`        | `ReevolveNumberField`              |
| `CodeField`          | `ReevolveCodeField`                |
| `Spin`               | `ReevolveSpin`                     |
| `LocationPicker`     | `ReevolveLocationPicker`           |
| `LocationView`       | `ReevolveLocationView`             |
| `Upload`             | `ReevolveUpload`                   |
| `Image`              | `ReevolveImage`                    |
| `FileThumbnail`      | `ReevolveFileThumbnail`            |
| `RHFForm`            | `ReevolveRHFForm`                  |
| `RHFTextField`       | `ReevolveRHFTextField`             |
| `RHFPassword`        | `ReevolveRHFPassword`              |
| `RHFNumberField`     | `ReevolveRHFNumberField`           |
| `RHFCheckbox`        | `ReevolveRHFCheckbox`              |
| `RHFSwitch`          | `ReevolveRHFSwitch`                |
| `RHFRadioGroup`      | `ReevolveRHFRadioGroup`            |
| `RHFDatePicker`      | `ReevolveRHFDatePicker`            |
| `RHFTimePicker`      | `ReevolveRHFTimePicker`            |
| `RHFDateTimePicker`  | `ReevolveRHFDateTimePicker`        |
| `RHFAutocomplete`    | `ReevolveRHFAutocomplete`          |
| `RHFSelect`          | `ReevolveRHFSelect`                |
| `RHFMultiSelect`     | `ReevolveRHFMultiSelect`           |
| `RHFLocationPicker`  | `ReevolveRHFLocationPicker`        |
| `RHFUpload`          | `ReevolveRHFUpload`                |
| `RHFCodeField`       | `ReevolveRHFCodeField`             |

All Reevolve components are integrated with MUI’s system and extend the [`Components`](https://mui.com/material-ui/customization/theme-components/#adding-new-component-types-to-theme) interface under the module `"@mui/material/styles/components"`.

### Example

Here’s how you can globally customize the `ReevolveUpload` and `ReevolveImage` components:

```ts
import { createTheme } from '@mui/material/styles';

const theme = createTheme({
	components: {
		ReevolveUpload: {
			defaultProps: {
				multiple: true,
				maxFiles: 3
			}
		},
		ReevolveImage: {
			defaultProps: {
				effect: 'blur',
				aspectRatio: '16/9'
			}
		}
	}
});
```

This approach helps ensure consistency across your application and reduces the need to repeat props and styles in every usage.

---

## Hooks

### useDefaultProps

Internal hook used by Reevolve components to merge `theme.components[ReevolveComponentName].defaultProps` with incoming props. You can import it when building custom wrappers that follow the same theming pattern.

```tsx
import { useDefaultProps } from '@reevolve/components';

function MyWrapper(inProps: MyProps) {
  const props = useDefaultProps({ name: 'ReevolveTextField', props: inProps });
  // ...
}
```

| Param | Type | Description |
| ----- | ---- | ----------- |
| `name` | `keyof Components` | Theme component key (e.g. `'ReevolveUpload'`). |
| `props` | `TProps` | Props passed to the component. |

**Returns:** Merged props (`theme defaultProps` + `props`).

---

## Utilities

Utility functions exported from `@reevolve/components` for use inside or outside the package.

### fData

Formats a byte size into a human-readable string (e.g. `1024` → `"1 KB"`).

```tsx
import { fData } from '@reevolve/components';

fData(2048); // "2 KB"
```

| Param | Type | Description |
| ----- | ---- | ----------- |
| `inputValue` | `number \| string \| null` | Size in bytes. |

### isRtlText

Detects whether the given text contains RTL characters (Arabic, Hebrew, Persian, etc.).

```tsx
import { isRtlText } from '@reevolve/components';

isRtlText('سلام'); // true
```

| Param | Type | Description |
| ----- | ---- | ----------- |
| `inputText` | `string` | Text to analyze. |

**Returns:** `boolean`

### isReactRef

Returns `true` if the value looks like a React ref object (`{ current: ... }`).

```tsx
import { isReactRef } from '@reevolve/components';
```

| Param | Type | Description |
| ----- | ---- | ----------- |
| `value` | `unknown` | Value to check. |

**Returns:** `boolean`

### propsMerge

Deep-merges two objects with special handling for React refs, elements, functions, and MUI `sx` props. Used by `useDefaultProps`.

```tsx
import { propsMerge } from '@reevolve/components';
```

| Param | Type | Description |
| ----- | ---- | ----------- |
| `object` | `TObject` | Base object (typically theme defaults). |
| `source` | `TSource` | Overrides. |

**Returns:** `TObject & TSource`

---

## React Hook Form components

These components integrate seamlessly with **React Hook Form** for efficient form state management and leverage **Material-UI's theming** for consistent styling across your application.

Each form field is built with the following principles in mind:

- **Ease of Use**: Components are pre-configured for common use cases and can be easily customized using props.
- **Validation Support**: They work out of the box with React Hook Form's validation, ensuring robust form validation with minimal configuration.
- **Theme Integration**: Fully compatible with MUI's light and dark themes, adapting to the application's overall design effortlessly.
- **Accessibility**: Designed to adhere to accessibility standards for a better user experience.

### RHFForm

The `RHFForm` component is a wrapper designed to simplify the integration of **React Hook Form** with your form components. It provides context for managing form state and validation, while ensuring a clean and structured setup for your forms.

#### Basic usage example

```tsx
import React from 'react';
import { useForm } from 'react-hook-form';
import { RHFForm, RHFTextField } from '@reevolve/components';

function MyForm() {
	const methods = useForm({
		defaultValues: {
			name: '',
			email: ''
		}
	});

	const onSubmit = methods.handleSubmit((data) => {
		console.log('Form Data:', data);
	});

	return (
		<RHFForm
			methods={methods}
			onSubmit={onSubmit}
			formElementProps={{ className: 'my-custom-form' }}
		>
			<RHFTextField
				name="name"
				label="Name"
			/>

			<RHFTextField
				name="email"
				label="Email"
			/>

			<button type="submit">Submit</button>
		</RHFForm>
	);
}

export default MyForm;
```

#### Props

| **Prop** | **Type** | **Required** | **Description** |
| -------- | -------- | ------------ | --------------- |
| `methods` | `UseFormReturn` | ✅ | React Hook Form methods from `useForm()`. |
| `onSubmit` | `ReturnType<UseFormHandleSubmit>` | ✅ | Submit handler from `methods.handleSubmit()`. |
| `formElementProps` | `FormHTMLAttributes` (omit `onSubmit`, `noValidate`) | ❌ | Props passed to the underlying `<form>` element. |
| `children` | `ReactNode` | ✅ | Form fields and actions. |

---

### RHFTextField

The **RHFTextField** is a reusable form input component that integrates seamlessly with **React Hook Form** and **Material-UI (MUI)**. It is designed to simplify the creation of text fields in forms by managing form state and validation using React Hook Form while leveraging the styling and features of Material-UI's `TextField`. Additionally, it supports various input types, including text, select, and other types provided by Material-UI's `TextField` component.

#### Basic usage example

```tsx
<RHFTextField
	name="text field"
	label="text field"
	control={control}
	helperText="textfield helpertext sample"
	inputMode="search"
	type="text"
	placeholder="input"
/>
```

#### Props

The following table lists include **props** added by `RHFTextField`. For standard props, refer to the [MUI Text Field](https://mui.com/material-ui/api/text-field/) documentation and [React Hook Form use Controller](https://www.react-hook-form.com/api/usecontroller/) documentation.

| **Prop**           | **Type**                              | **Required** | **Description**                                                                         |
| ------------------ | ------------------------------------- | ------------ | --------------------------------------------------------------------------------------- |
| `name`             | `string`                              | ✅           | The name of the input field in the form state.                                          |
| `control`          | `Control<FieldValues>`                | ❌           | The React Hook Form `control` object to manage the form field.                          |
| `rules`            | `ValidationRules`                     | ❌           | Validation rules for the field (e.g., `required`, `minLength`, `maxLength`).            |
| `transform`        | `(value: string) => TransformedValue` | ❌           | Function to transform the input value before updating the form state.                   |
| `autoDirection`    | `boolean` (default: `true`)           | ❌           | Automatically sets the text direction based on the user's input language.               |
| `nullable`         | `boolean` (default: `true`)           | ❌           | When enabled, an empty string input ("") will be treated as a null value for the field. |
| `trim`             | `boolean` (default: `true`)           | ❌           | Trims leading/trailing whitespace on blur.                                              |
| `defaultValue`     | `string`                              | ❌           | Default value for the input field                                                       |
| `shouldUnregister` | `boolean`                             | ❌           | Whether to unregister the input when removed from the UI.                               |
| `disabled`         | `boolean`                             | ❌           | Disables the input.                                                                     |

---

### RHFNumberField

The `RHFNumberField` component is a **React Hook Form-integrated** numeric input built on top of the [`NumberField`](#numberfield) component. It combines the power of form validation and control from `react-hook-form` with the enhanced number input experience provided by `rc-input-number` and MUI's `TextField`.

It’s ideal for use cases where you need precise and controlled numeric input as part of a form.

#### Basic usage example

```tsx
<RHFNumberField
	name="price"
	control={control}
	label="Price"
	min={0}
	max={9999}
	step={0.5}
	helperText="Enter the item price"
/>
```

#### **Props**

The `RHFNumberField` accepts all props from [`NumberField`](#numberfield), except for `value` and `onChange`, which are managed internally by `react-hook-form`.

It also supports the standard `UseControllerProps` from `react-hook-form`:

| Prop      | Type                   | Required | Description                                                      |
| --------- | ---------------------- | -------- | ---------------------------------------------------------------- |
| `name`    | `string`               | ✅       | The name of the input field in the form state.                   |
| `control` | `Control<FieldValues>` | ❌       | The React Hook Form `control` object to manage the form field.   |
| `rules`   | `ValidationRules`      | ❌       | Validation rules for the field (e.g., `required`, `min`, `max`). |

Other props from `NumberField`, such as `min`, `max`, `step`, `formatter`, and `parser`, can also be passed directly to customize behavior and formatting.

---

### RHFPassword

The **RHFPassword** component is a reusable password input field that integrates seamlessly with **React Hook Form** and **Material-UI (MUI)**.
It is built on top of [`RHFTextField`](#rhftextfield) and is specifically designed for handling password inputs with an optional **show/hide password toggle button**.

#### Basic usage example

```tsx
<RHFPassword
	name="password"
	label="Password"
	control={control}
	helperText="Enter your account password."
	showPasswordTogglerButtonPosition="end"
/>
```

#### Props

The `RHFPassword` component supports all props from [`RHFTextField`](#rhftextfield) **except** `select`.
For shared props, refer to the [RHFTextField documentation](#rhftextfield).

##### Additional Props

| **Prop**                            | **Type**                                                                                                      | **Default** | **Description**                                                                   |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------- |
| `showPasswordTogglerButtonPosition` | `'end' \| 'start'`                                                                                            | `'end'`     | Determines the position of the show/hide password toggle button inside the input. |
| `slots`                             | `{ showPasswordIcon?: React.ElementType; hidePasswordIcon?: React.ElementType; }`                             | `{}`        | Custom components for the show/hide password icons.                               |
| `slotProps`                         | `{ showPasswordIcon?: React.SVGAttributes<SVGElement>; hidePasswordIcon?: React.SVGAttributes<SVGElement>; }` | `{}`        | Props passed to the show/hide password icon components.                           |

#### Notes

- By default, the password input masks the text; users can toggle visibility with the provided button.
- Icons for show/hide password can be customized using the `slots` and `slotProps` props.
- This component inherits all validation, state management, and styling capabilities from [`RHFTextField`](#rhftextfield).

---

### RHFCheckbox

The **RHFCheckbox** is a reusable checkbox component that integrates **React Hook Form** and **Material-UI (MUI)**. It simplifies the creation of form checkboxes by managing state and validation using React Hook Form, while also leveraging the styling capabilities of Material-UI components.

#### Basic usage example

```tsx
<RHFCheckbox
	name="notifications"
	control={control}
	label="Enable notifications"
/>
```

#### Props

The following table lists **props** added by `RHFCheckbox`. For other props, refer to the [React Hook Form documentation](https://react-hook-form.com/) and [Checkbox](#checkbox) / [MUI Checkbox](https://mui.com/material-ui/api/checkbox/) documentation.

| Prop         | Type                            | Required | Description                                                                                         |
| ------------ | ------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `name`       | `string`                        | ✅       | Name of the field in the form.                                                                      |
| `control`    | `Control<T>`                    | ❌       | React Hook Form's `control` object.                                                                 |
| `rules`      | `RegisterOptions`               | ❌       | Validation rules for the field.                                                                     |
| `required`   | `boolean`                       | ❌       | Indicates whether the checkbox is required for validation.                                          |
| `helperText` | `string`                        | ❌       | Additional text to display below the checkbox.                                                      |
| `onChange`   | `(event, isChecked) => void`    | ❌       | Callback fired when the checkbox's value changes.                                                   |
| `onBlur`     | `(event) => void`               | ❌       | Callback fired when the checkbox loses focus.                                                       |
| `slotProps`  | `RHFCheckBoxProps["slotProps"]` | ❌       | Allows customization of inner components via props.                                                 |

Inherits remaining props from [`Checkbox`](#checkbox).

Also supports standard `UseControllerProps` (`defaultValue`, `shouldUnregister`, `disabled`, etc.).

---

### RHFSwitch

The **RHFSwitch** is a reusable Switch component that integrates **React Hook Form** and **Material-UI (MUI)**. It simplifies the creation of form switches by managing state and validation using React Hook Form, while also leveraging the styling capabilities of Material-UI components.

#### Basic usage example

```tsx
<RHFSwitch
	name="notifications"
	control={control}
	label="Enable notifications"
/>
```

#### Props

The following table lists **props** added by `RHFSwitch`. For other props, refer to the [React Hook Form documentation](https://react-hook-form.com/) and [Switch](#switch) / [MUI Switch](https://mui.com/material-ui/api/switch/) documentation.

| Prop         | Type                          | Required | Description                                                                                         |
| ------------ | ----------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `name`       | `string`                      | ✅       | Name of the field in the form.                                                                      |
| `control`    | `Control<T>`                  | ❌       | React Hook Form's `control` object.                                                                 |
| `rules`      | `RegisterOptions`             | ❌       | Validation rules for the field.                                                                     |
| `required`   | `boolean`                     | ❌       | Indicates whether the switch is required for validation.                                            |
| `helperText` | `string`                      | ❌       | Additional text to display below the switch.                                                        |
| `onChange`   | `(event, isChecked) => void`  | ❌       | Callback fired when the switch value changes.                                                       |
| `onBlur`     | `(event) => void`             | ❌       | Callback fired when the switch loses focus.                                                         |
| `slotProps`  | `RHFSwitchProps["slotProps"]` | ❌       | Allows customization of inner components via props.                                                 |

Inherits remaining props from [`Switch`](#switch). Also supports `UseControllerProps`.

---

### RHFRadioGroup

The **RHFRadioGroup** is a reusable component that integrates **React Hook Form** and **Material-UI (MUI)** to simplify the creation of radio group inputs in forms. It supports validation, localization, and customization while managing form state and leveraging Material-UI's styling

#### Basic usage example

```tsx
<RHFRadioGroup
	name="radioField"
	label="radiolabel"
	control={control}
	defaultValue={'2'}
	helperText={'radio helpertext sample'}
	options={[
		{ value: '1', label: 'asdasd' },
		{ value: '2', label: 'asdasd2' }
	]}
	rules={{ required: true }}
/>
```

#### Props

The following table lists **props** added by `RHFRadioGroup`. For other props, refer to the [React Hook Form documentation](https://react-hook-form.com/) and [Material-UI Radio documentation](https://mui.com/material-ui/api/radio/).

| Prop         | Type                              | Required | Description                                                                                        |
| ------------ | --------------------------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `name`       | `string`                          | ✅       | Name of the field in the form.                                                                     |
| `control`    | `Control<T>`                      | ❌       | React Hook Form's `control` object.                                                                |
| `label`      | `string`                          | ❌       | Label displayed above the radio group.                                                             |
| `options`    | `RadioOption[]`                   | ❌       | Array of radio button options, each containing `value`, `label`, and optional customization props. |
| `helperText` | `string`                          | ❌       | Additional text to display below the radio group for information or validation messages.           |
| `onChange`   | `(event, value) => void`          | ❌       | Callback fired when the value of the radio group changes.                                          |
| `onBlur`     | `(event) => void`                 | ❌       | Callback fired when the radio group loses focus.                                                   |
| `slotProps`  | `RHFRadioGroupProps["slotProps"]` | ❌       | Allows customization of inner components via props.                                                |

---

### RHFDatePicker

The **RHFDatePicker** is a reusable date picker component that integrates **React Hook Form** and **MUI X Date Picker**. It simplifies the creation of date pickers by managing state and validation using React Hook Form, while also allowing customization for Jalali or Gregorian calendars and multi-language support.

#### Basic usage example

```tsx
<RHFDatePicker
	name="birthdate"
	control={control}
	label="Select your birthdate"
	rules={{ required: true }}
	dateAdapter="gregorian"
	adapterLocale="en"
	helperText="Please select a date"
/>
```

#### Props

The following table lists props specific to `RHFDatePicker`. For other props, refer to the [React Hook Form documentation](https://react-hook-form.com/) and [MUI X DatePicker documentation](https://mui.com/x/api/date-pickers/date-picker/).

| Prop            | Type                                                           | Required | Description                                                                                            |
| --------------- | -------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `name`          | `string`                                                       | ✅       | Name of the field in the form.                                                                         |
| `control`       | `Control<T>`                                                   | ❌       | React Hook Form's `control` object.                                                                    |
| `rules`         | `Object`                                                       | ❌       | Validation rules for the field, supports React Hook Form validation schema.                            |
| `label`         | `string`                                                       | ❌       | Label for the date picker input field.                                                                 |
| `required`      | `boolean`                                                      | ❌       | Indicates whether the date picker is required for validation.                                          |
| `dateAdapter`   | `'jalali' \| 'gregorian' \| MuiPickersAdapter<TDate, TLocale>` | ❌       | Specifies the date adapter to use (e.g., Jalali or Gregorian). Defaults to Gregorian if not provided.  |
| `adapterLocale` | `'fa' \| 'en' \| TLocale`                                      | ❌       | Locale for the date adapter, e.g., `fa` for Persian or `en` for English.                               |
| `helperText`    | `string`                                                       | ❌       | Additional text to display below the date picker, often used for validation or informational messages. |
| `onChange`      | `(newValue: TDate, context?: PickerChangeContext) => void`     | ❌       | Callback fired when the date picker value changes.                                                     |

---

### RHFTimePicker

The `RHFTimePicker` component is a reusable and customizable time picker built with MUI's `TimePicker`, integrated with React Hook Form for form validation and state management. It supports both Jalali and Gregorian calendars, as well as localization.

#### Basic usage example

```tsx
<RHFTimePicker
	name="time"
	label="time"
	control={control}
	onChange={console.log}
	helperText="time picker sample helper text"
/>
```

#### Props

The following table lists props specific to `RHFTimePicker`. For other props, refer to the [React Hook Form documentation](https://react-hook-form.com/) and [MUI X TimePicker documentation](https://mui.com/x/api/date-pickers/time-picker/).

| Prop Name          | Type                                             | Required | Description                                                                |
| ------------------ | ------------------------------------------------ | -------- | -------------------------------------------------------------------------- |
| `name`             | `string`                                         | ✅       | Name of the field for React Hook Form.                                     |
| `control`          | `Control<T>`                                     | ❌       | The control object from React Hook Form.                                   |
| `rules`            | `FieldRules`                                     | ❌       | Validation rules for the field.                                            |
| `defaultValue`     | `any`                                            | ❌       | Default value for the field.                                               |
| `shouldUnregister` | `boolean`                                        | ❌       | Whether to unregister the input on unmount.                                |
| `label`            | `string`                                         | ❌       | Label for the time picker.                                                 |
| `required`         | `boolean`                                        | ❌       | Whether the field is required.                                             |
| `dateAdapter`      | `'jalali' \| 'gregorian' \| MuiPickersAdapter`   | ❌       | Date adapter for the time picker (Jalali, Gregorian, or a custom adapter). |
| `adapterLocale`    | `'fa' \| 'en' \| TLocale`                        | ❌       | Locale for the date adapter (supports Persian and English by default).     |
| `helperText`       | `string`                                         | ❌       | Additional helper text to display below the picker.                        |
| `onChange`         | `(value: Date \| null, context: object) => void` | ❌       | Callback triggered when the value changes.                                 |
| `ampm`             | `boolean`                                        | ❌       | Whether to display the time in AM/PM format. Defaults to `false`.          |

---

### RHFDateTimePicker

The `RHFDateTimePicker` is a reusable datetime picker component that integrates with **React Hook Form**. It provides localization support for multiple languages (including **Gregorian** and **Jalali** calendars), dynamic error handling, and custom helper text.

#### Basic usage example

```tsx
<RHFDateTimePicker
	name="dateasd3"
	label="date time"
	control={control}
	helperText="date picker sample helper text"
/>
```

#### Props

The following table lists props specific to `RHFDateTimePicker`. For other props, refer to the [React Hook Form documentation](https://react-hook-form.com/) and [MUI X DateTimePicker documentation](https://mui.com/x/api/date-pickers/date-time-picker/).

| Prop            | Type                                                           | Required | Description                                                                                            |
| --------------- | -------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `name`          | `string`                                                       | ✅       | Name of the field in the form.                                                                         |
| `control`       | `Control<T>`                                                   | ❌       | React Hook Form's `control` object.                                                                    |
| `rules`         | `Object`                                                       | ❌       | Validation rules for the field, supports React Hook Form validation schema.                            |
| `label`         | `string`                                                       | ❌       | Label for the date picker input field.                                                                 |
| `required`      | `boolean`                                                      | ❌       | Indicates whether the date picker is required for validation.                                          |
| `dateAdapter`   | `'jalali' \| 'gregorian' \| MuiPickersAdapter<TDate, TLocale>` | ❌       | Specifies the date adapter to use (e.g., Jalali or Gregorian). Defaults to Gregorian if not provided.  |
| `adapterLocale` | `'fa' \| 'en' \| TLocale`                                      | ❌       | Locale for the date adapter, e.g., `fa` for Persian or `en` for English.                               |
| `helperText`    | `string`                                                       | ❌       | Additional text to display below the date picker, often used for validation or informational messages. |
| `onChange`      | `(newValue: TDate, context?: PickerChangeContext) => void`     | ❌       | Callback fired when the date picker value changes.                                                     |
| `ampm`          | `boolean`                                                      | ❌       | Whether to display the time in AM/PM format. Defaults to `false`.                                      |

---

### RHFAutocomplete

The **RHFAutocomplete** component integrates **React Hook Form** with **Material-UI's Autocomplete**, providing a powerful, customizable, and reusable autocomplete field. It simplifies form state management, validation, and localization while leveraging Material-UI's styling and interaction features.

#### Basic usage Example

```tsx
<RHFAutocomplete
	name="selectasd"
	label="ello"
	helperText={'select helpertext sample'}
	control={control}
	multiple
	options={[1, 2, 3]}
	getOptionLabel={(option) => `option ${option}`}
	rules={{ required: true }}
/>
```

#### Props

The following table lists include **props** added by `RHFAutocomplete`. For other props, refer to the [React Hook Form documentation](https://react-hook-form.com/) and [Material-UI Autocomplete documentation](https://mui.com/material-ui/api/autocomplete/).

| **Prop**           | **Type**                                         | Required | **Description**                                                                            |
| ------------------ | ------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------ |
| `name`             | `string`                                         | ✅       | Name of the field in the form.                                                             |
| `control`          | `Control<TFieldValues>`                          | ❌       | React Hook Form's control object.                                                          |
| `rules`            | `RegisterOptions`                                | ❌       | Validation rules for the field.                                                            |
| `options`          | `TValue[]`                                       | ❌       | Array of options to display in the autocomplete dropdown.                                  |
| `multiple`         | `boolean`                                        | ❌       | Enables selection of multiple values. Defaults to `false`.                                 |
| `label`            | `string`                                         | ❌       | Label for the `TextField` displayed in the autocomplete.                                   |
| `helperText`       | `string`                                         | ❌       | Helper text displayed below the input field.                                               |
| `variant`          | `'filled' \| 'outlined' \| 'standard'`           | ❌       | Sets the variant style of the `TextField`.                                                 |
| `color`            | `TextFieldProps['color']`                        | ❌       | Color of the `TextField`.                                                                  |
| `size`             | `TextFieldProps['size']`                         | ❌       | Size of the `TextField`.                                                                   |
| `placeholder`      | `TextFieldProps['placeholder']`                  | ❌       | placeholder of the `TextField`.                                                            |
| `TextFieldProps`   | `TextFieldProps` or `(params) => TextFieldProps` | ❌       | Props to customize the underlying `TextField`.                                             |
| `transform`        | `(event, value, reason, details) => TValue`      | ❌       | Custom function to transform the value before passing it to React Hook Form.               |
| `onChange`         | `(value) => void`                                | ❌       | Callback triggered when the value changes.                                                 |
| `required`         | `boolean`                                        | ❌       | Marks the field as required.                                                               |
| `disableClearable` | `boolean`                                        | ❌       | If `true`, disables the option to clear the selection. Defaults to `true`.                 |
| `freeSolo`         | `boolean`                                        | ❌       | If `true`, allows free text input in addition to selecting an option. Defaults to `false`. |

---

### RHFSelect

The `RHFSelect` component is a **React Hook Form-integrated** dropdown built on top of MUI's `Select`. It simplifies the process of creating accessible, form-bound select fields with customizable options and MUI styling.

It combines the power of MUI's `<Select>` with the form management capabilities of `react-hook-form`.

#### Basic usage example

```tsx
<RHFSelect
	name="status"
	control={control}
	label="Select status"
	options={[
		{ label: 'Active', value: 'active' },
		{ label: 'Inactive', value: 'inactive' }
	]}
	helperText="Choose the current status."
/>
```

#### **Props**

The following table lists include **props** added by `RHFSelect`. For other props, refer to the [React Hook Form documentation](https://react-hook-form.com/) and [Material-UI Select documentation](https://mui.com/material-ui/api/select/).

| Prop               | Type                                           | Require | Default                                | Description                                                  |
| ------------------ | ---------------------------------------------- | ------- | -------------------------------------- | ------------------------------------------------------------ |
| `name`             | `string`                                       | ✅      | -                                      | Name of the field in the form.                               |
| `options`          | `SelectOption[]`                               | ✅      | -                                      | Array of options with `{ label, value }`.                    |
| `control`          | `Control<TFieldValues>`                        | ❌      | -                                      | React Hook Form's control object.                            |
| `rules`            | `RegisterOptions`                              | ❌      | -                                      | Validation rules for the field.                              |
| `onChange`         | `(value: string \| boolean \| number) => void` | ❌      | -                                      | Custom callback when value changes.                          |
| `helperText`       | `ReactNode`                                    | ❌      | -                                      | Helper text shown below the select.                          |
| `emptyOption`      | `boolean`                                      | ❌      | `false`                                | Adds an empty item at the top of the list.                   |
| `emptyOptionValue` | `any`                                          | ❌      | `null`                                 | The value of the empty option (useful for nullable selects). |
| `emptyOptionLabel` | `ReactNode`                                    | ❌      | `translate('select.emptyOptionLabel')` | The label for the empty option.                              |
| `slotProps`        | `object`                                       | ❌      | `{}`                                   | Custom props for internal MUI components.                    |

##### **Slot Props**

Customize the inner MUI components via the `slotProps` prop.

| Slot            | Description                                                    |
| --------------- | -------------------------------------------------------------- |
| `formControl`   | Props for the MUI `FormControl` component.                     |
| `helperText`    | Props for the MUI `FormHelperText` component.                  |
| `inputLabel`    | Props for the MUI `InputLabel` component.                      |
| `menuItemProps` | Props applied to each `MenuItem`, excluding `value` and `key`. |

---

### RHFMultiSelect

The `RHFMultiSelect` component is a **React Hook Form-integrated** multi-value select built on top of MUI's `Select`. It allows users to select multiple options with additional visual enhancements like **checkboxes** and **chips**.

This component is designed to simplify form integration while maintaining flexibility and customization through MUI and RHF capabilities.

#### Basic usage example

```tsx
<RHFMultiSelect
	name="roles"
	control={control}
	label="Select roles"
	options={[
		{ label: 'Admin', value: 'admin' },
		{ label: 'Editor', value: 'editor' },
		{ label: 'Viewer', value: 'viewer' }
	]}
	checkbox
	chip
	helperText="You can select multiple roles."
/>
```

#### **Props**

The following table lists **props** specific to `RHFMultiSelect`. For additional props, refer to the [React Hook Form documentation](https://react-hook-form.com/) and [Material-UI Select documentation](https://mui.com/material-ui/api/select/).

| Prop          | Type                                | Require | Default | Description                                      |
| ------------- | ----------------------------------- | ------- | ------- | ------------------------------------------------ |
| `name`        | `string`                            | ✅      | -       | Name of the field in the form.                   |
| `options`     | `MultiSelectOption[]`               | ✅      | -       | Array of options with `{ label, value }`.        |
| `control`     | `Control<TFieldValues>`             | ❌      | -       | React Hook Form's control object.                |
| `rules`       | `RegisterOptions`                   | ❌      | -       | Validation rules for the field.                  |
| `onChange`    | `(value: MultiSelectValue) => void` | ❌      | -       | Custom callback when value changes.              |
| `helperText`  | `ReactNode`                         | ❌      | -       | Helper text shown below the select.              |
| `placeholder` | `ReactNode`                         | ❌      | -       | Placeholder text shown when no item is selected. |
| `checkbox`    | `boolean`                           | ❌      | `false` | Shows a checkbox next to each option.            |
| `chip`        | `boolean`                           | ❌      | `false` | Displays selected items as chips in the input.   |
| `slotProps`   | `object`                            | ❌      | `{}`    | Custom props for internal MUI components.        |

##### **Slot Props**

Customize internal components using the `slotProps` prop.

| Slot            | Description                                   |
| --------------- | --------------------------------------------- |
| `formControl`   | Props for the MUI `FormControl` component.    |
| `helperText`    | Props for the MUI `FormHelperText` component. |
| `inputLabel`    | Props for the MUI `InputLabel` component.     |
| `menuItemProps` | Props applied to each `MenuItem`.             |
| `checkbox`      | Props applied to each MUI `Checkbox`.         |
| `chip`          | Props applied to each MUI `Chip`.             |

---

### RHFLocationPicker

The **RHFLocationPicker** component integrates **React Hook Form** with [LocationPicker](#locationpicker) component, providing a customizable, reusable location picker field with form state management, validation, and localization support.

for using this component import leaflet styles in your project:

```ts
import 'leaflet/dist/leaflet.css';
```

#### Basic usage Example

```tsx
<RHFLocationPicker
	name="location"
	control={control}
	label="your location"
	helperText="pick your location on map"
	rules={{ required: true }}
/>
```

#### Props

The following table lists the **props** added by `RHFLocationPicker`. For other props, refer to the [React Hook Form documentation](https://react-hook-form.com/).

| **Prop**      | **Type**                           | Required | **Description**                                                |
| ------------- | ---------------------------------- | -------- | -------------------------------------------------------------- |
| `name`        | `string`                           | ✅       | Name of the field in the form.                                 |
| `control`     | `Control<TFieldValues>`            | ❌       | React Hook Form's control object.                              |
| `rules`       | `RegisterOptions`                  | ❌       | Validation rules for the field.                                |
| `label`       | `ReactNode`                        | ❌       | Label for the location field.                                  |
| `helperText`  | `ReactNode`                        | ❌       | Helper text displayed below the map.                           |
| `error`       | `boolean`                          | ❌       | Error state for the form control.                              |
| `required`    | `boolean`                          | ❌       | Marks the field as required.                                   |
| `onChange`    | `(value: LatLngLiteral) => void`   | ❌       | Called when the user picks a location.                         |
| `disabled`    | `boolean`                          | ❌       | Disables the picker.                                           |
| `zoom`        | `number` (default: `15`)           | ❌       | Initial zoom level of the Leaflet map (`MapContainer` prop).   |
| `ref`         | `Ref<Map>`                         | ❌       | Ref to the `MapContainer` instance.                            |
| `slotProps`   | `LocationPickerProps["slotProps"]` | ❌       | Props for inner components (`formControl`, `mapWrapper`, etc.). |
| `slots`       | `LocationPickerProps["slots"]`     | ❌       | Custom nodes (e.g. `floatingMarker`).                          |

Inherits additional props from [`MapContainer`](https://react-leaflet.js.org/docs/api-map/#mapcontainer) (except `children` and `center`).

---

### RHFUpload

The **RHFUpload** component integrates **React Hook Form** with [Upload](#upload), providing a customizable, reusable file upload field with form state management, validation, and localization support.

It accepts all props from [`Upload`](#upload) except `value`, `error`, `disabled`, `onDrop`, `onDelete`, `onRemove`, `onRemoveAll`, and `onUpload` (managed internally or via RHF-specific callbacks).

#### Basic usage Example

```tsx
<RHFUpload
	name="uploadField"
	control={control}
	label="Upload File"
	helperText="Select a file to upload"
	multiple={false}
	rules={{ required: 'File upload is required' }}
	onChange={(value) => console.log(value)}
/>
```

#### Props

The following table lists the **props** added by `RHFUpload`. For other props, refer to the [React Hook Form documentation](https://react-hook-form.com/).

| **Prop**         | **Type**                                     | Required | **Description**                                                              |
| ---------------- | -------------------------------------------- | -------- | ---------------------------------------------------------------------------- |
| `name`           | `string`                                     | ✅       | Name of the field in the form.                                               |
| `control`        | `Control<TFieldValues>`                      | ❌       | React Hook Form's control object.                                            |
| `rules`          | `RegisterOptions`                            | ❌       | Validation rules for the field.                                              |
| `multiple`       | `boolean`                                    | ❌       | Enables selection of multiple files.                                         |
| `label`          | `string`                                     | ❌       | Label for the file upload field.                                             |
| `helperText`     | `string`                                     | ❌       | Helper text displayed below the upload field.                                |
| `required`       | `boolean`                                    | ❌       | Marks the field as required.                                                 |
| `onChange`       | `(value) => void`                            | ❌       | Called when selected file(s) change.                                         |
| `onUpload`       | `(value) => void`                            | ❌       | Called when upload action is triggered.                                      |
| `transform`      | `(value) => File \| File[] \| Promise<...>`  | ❌       | Transforms file value before updating form state.                            |
| `disabled`       | `boolean`                                    | ❌       | Disables the upload field.                                                   |

All other [`Upload`](#upload) props (e.g. `accept`, `maxFiles`, `thumbnail`, `slotProps`) can be passed through.

---

### RHFCodeField

The **RHFCodeField** component integrates **React Hook Form** with [CodeField](#codefield).

#### Basic usage Example

```tsx
<RHFCodeField
	label="one time password"
	name="otp"
	length={5}
	helperText="helper text"
	rules={{
		required: true
	}}
/>
```

#### **Props**

The `RHFCodeField` accepts all props from [`CodeField`](#codefield), except:

- `value`
- `error`

These are managed internally via React Hook Form's `useController`.

It also supports all props from [`useController`](https://react-hook-form.com/docs/usecontroller), such as:

| Prop           | Type                    | Description                                  |
| -------------- | ----------------------- | -------------------------------------------- |
| `name`         | `string`                | Name of the form field.                      |
| `control`      | `Control<TFieldValues>` | Control object from `useForm`.               |
| `rules`        | `RegisterOptions`       | Validation rules (e.g., required, minLength) |
| `defaultValue` | `string`                | Default value for the field.                 |

---

## TextField

The **TextField** component wraps MUI's `TextField` with Reevolve-specific behavior: automatic RTL/LTR direction, nullable empty strings, and trim-on-blur.

### Basic usage example

```tsx
<TextField
	label="Name"
	value={name}
	onChange={(value) => setName(value)}
	nullable
	autoDirection
/>
```

### Props

In addition to [MUI TextField](https://mui.com/material-ui/api/text-field/) props (except `onChange`), the following props are supported:

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `autoDirection` | `boolean` | `true` | Sets `dir` on the input based on typed text (via `isRtlText`). |
| `nullable` | `boolean` | `true` | Treats empty string as `null` in `onChange`. |
| `trim` | `boolean` | `true` | Trims whitespace on blur. |
| `onChange` | `(value, event) => void` | – | Receives parsed value (`string \| null` when `nullable`). |

---

## Password

The **Password** component extends [`TextField`](#textfield) with a show/hide password toggle. See [RHFPassword](#rhfpassword) for the React Hook Form variant.

### Basic usage example

```tsx
<Password
	label="Password"
	value={password}
	onChange={setPassword}
	showPasswordTogglerButtonPosition="end"
/>
```

### Props

Supports all [`TextField`](#textfield) props except `select`, plus:

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `showPasswordTogglerButtonPosition` | `'end' \| 'start'` | `'end'` | Position of the visibility toggle button. |
| `slots` | `{ showPasswordIcon?, hidePasswordIcon? }` | `{}` | Custom icon components. |
| `slotProps` | `{ showPasswordIcon?, hidePasswordIcon?, showPasswordTogglerButton? }` | `{}` | Props for icons and toggle `IconButton`. |

> `autoDirection` defaults to `false` for password fields.

---

## Checkbox

Standalone checkbox with label and helper text, built on MUI `Checkbox`.

### Basic usage example

```tsx
<Checkbox
	label="Accept terms"
	value={accepted}
	onChange={(e, checked) => setAccepted(checked)}
	helperText="You must accept to continue"
/>
```

### Props

| Prop | Type | Description |
| ---- | ---- | ----------- |
| `label` | `string` | Label next to the checkbox. |
| `required` | `boolean` | Marks the field as required. |
| `helperText` | `ReactNode` | Text below the control. |
| `value` | `boolean` | Checked state. |
| `error` | `boolean` | Error state. |
| `slotProps` | `{ formControlLabel?, helperText?, formControl? }` | Inner component props. |

Also supports standard [MUI Checkbox](https://mui.com/material-ui/api/checkbox/) props (except `value` / `checked` — use `value` as boolean).

---

## Switch

Standalone switch with label and helper text, built on MUI `Switch`. See [RHFSwitch](#rhfswitch) for the form-bound variant.

### Basic usage example

```tsx
<Switch
	label="Enable notifications"
	value={enabled}
	onChange={(e, checked) => setEnabled(checked)}
/>
```

### Props

Same shape as [`Checkbox`](#checkbox) props (`label`, `required`, `helperText`, `value`, `error`, `slotProps`), with MUI [Switch](https://mui.com/material-ui/api/switch/) behavior.

---

## Select

The **Select** component is a typed MUI `Select` with option list support, empty option, and localization for the empty label.

### Basic usage example

```tsx
<Select
	label="Status"
	value={status}
	onChange={setStatus}
	options={[
		{ label: 'Active', value: 'active' },
		{ label: 'Inactive', value: 'inactive' }
	]}
	emptyOption
/>
```

### Props

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `options` | `SelectOption[]` | – | `{ label, value, menuItemProps? }[]` (required). |
| `value` | option value \| empty value | – | Current selection (required). |
| `onChange` | `(value, event, child) => void` | – | Change handler. |
| `emptyOption` | `boolean` | `false` | Adds an empty item at the top. |
| `emptyOptionValue` | `any` | `null` | Value for the empty option. |
| `emptyOptionLabel` | `ReactNode` | localized | Label for the empty option. |
| `placeholder` | `ReactNode` | – | Placeholder when nothing is selected. |
| `helperText` | `ReactNode` | – | Helper text below the select. |
| `slotProps` | `{ formControl?, helperText?, inputLabel?, menuItemProps? }` | – | Inner MUI component props. |

Also supports [MUI Select](https://mui.com/material-ui/api/select/) props (except `onChange` / `value`).

---

## MultiSelect

Multi-value select with optional checkboxes and chips for selected items.

### Basic usage example

```tsx
<MultiSelect
	label="Roles"
	value={roles}
	onChange={setRoles}
	options={[
		{ label: 'Admin', value: 'admin' },
		{ label: 'Editor', value: 'editor' }
	]}
	checkbox
	chip
/>
```

### Props

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `options` | `MultiSelectOption[]` | – | Options list (required). |
| `value` | `array` of option values | – | Selected values (required). |
| `onChange` | `(value, event, child) => void` | – | Change handler. |
| `checkbox` | `boolean` | `false` | Show checkbox per option. |
| `chip` | `boolean` | `false` | Render selected values as chips. |
| `placeholder` | `ReactNode` | – | Shown when nothing is selected. |
| `helperText` | `ReactNode` | – | Helper text. |
| `slotProps` | `{ formControl?, helperText?, inputLabel?, menuItemProps?, checkbox?, chip? }` | – | Inner component props. |

---

## Date Pickers

Standalone date/time pickers built on [MUI X Date Pickers](https://mui.com/x/react-date-pickers/). Each picker wraps [`PickersLocalizationProvider`](#pickerslocalizationprovider) for Jalali/Gregorian calendar support.

### DatePicker

```tsx
<DatePicker
	label="Birth date"
	value={date}
	onChange={setDate}
	dateAdapter="jalali"
	adapterLocale="fa"
/>
```

| Prop | Type | Description |
| ---- | ---- | ----------- |
| `dateAdapter` | `'jalali' \| 'gregorian' \| MuiPickersAdapter` | Calendar system. |
| `adapterLocale` | `'fa' \| 'en' \| TLocale` | Locale for the adapter. |
| `required` | `boolean` | Required field. |
| `error` | `boolean` | Error state. |
| `helperText` | `string` | Helper text. |
| `variant` / `size` / `color` | MUI TextField | Field appearance. |
| `onBlur` | `() => void` | Blur handler. |

Plus all [MUI DatePicker](https://mui.com/x/api/date-pickers/date-picker/) props.

### TimePicker

```tsx
<TimePicker
	label="Meeting time"
	value={time}
	onChange={setTime}
	ampm={false}
/>
```

Same localization props as `DatePicker`, plus [MUI TimePicker](https://mui.com/x/api/date-pickers/time-picker/) props (including `ampm`).

### DateTimePicker

```tsx
<DateTimePicker
	label="Appointment"
	value={dateTime}
	onChange={setDateTime}
/>
```

Combines date and time picking with the same `dateAdapter` / `adapterLocale` props and [MUI DateTimePicker](https://mui.com/x/api/date-pickers/date-time-picker/) API.

### PickersLocalizationProvider

Low-level provider used internally by date pickers. Can be used directly when composing custom picker UIs.

| Prop | Type | Description |
| ---- | ---- | ----------- |
| `dateAdapter` | `'jalali' \| 'gregorian' \| MuiPickersAdapter` | Calendar adapter class or preset. |
| `adapterLocale` | `'fa' \| 'en' \| TLocale` | `date-fns` locale object or shorthand. |
| `children` | `ReactNode` | Pickers to render inside the provider. |

Defaults: if `dateAdapter` is omitted, `fa` language uses Jalali adapter; otherwise Gregorian. Locale follows `adapterLocale`, `LocalizationProvider` language, or `en`.

---

## Spin

The Spin component is a component that displays a loading indicator while dimming its child content. It’s ideal for scenarios where you need to communicate loading or processing states to the user.

### Props

| Name        | Type              | Default                                      | Required | Description                                                                                         |
| ----------- | ----------------- | -------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `children`  | `React.ReactNode` | –                                            | ✅       | Content to wrap with the loading overlay.                                                           |
| `spinning`  | `boolean`         | `true`                                       | ❌       | Controls the loading state. When `true`, the spinner is displayed, and child components are dimmed. |
| `indicator` | `React.ReactNode` | A default spinner with three dots animation. | ❌       | The loading indicator to display while `spinning` is `true`.                                        |

### Basic usage example

```tsx
import React, { useState } from 'react';
import { Spin } from '@reevolve/components';
import { Button, Box } from '@mui/material';

function App() {
	const [loading, setLoading] = useState(false);

	const toggleLoading = () => setLoading(!loading);

	return (
		<Box>
			<Spin spinning={loading}>
				<Box p={2}>
					<h1>Content Area</h1>
					<p>This is the main content. It will be dimmed when loading.</p>
				</Box>
			</Spin>
			<Button
				variant="contained"
				color="primary"
				onClick={toggleLoading}
			>
				{loading ? 'Stop Loading' : 'Start Loading'}
			</Button>
		</Box>
	);
}

export default App;
```

---

## LocationPicker

this component use for pick a location on map using `Leaflet`.

for using this component import leaflet styles in your project:

```ts
import 'leaflet/dist/leaflet.css';
```

### Props

| **Prop**      | **Type**                           | Required | **Description**                                                |
| ------------- | ---------------------------------- | -------- | -------------------------------------------------------------- |
| `value`       | `LatLngLiteral`                    | ❌       | Value state of field                                           |
| `onChange`    | `(value: LatLngLiteral) => void`   | ❌       | Change handler for value state of field                        |
| `name`        | `string`                           | ❌       | Input name (for forms).                                        |
| `label`       | `ReactNode`                        | ❌       | Label for the location field.                                  |
| `helperText`  | `ReactNode`                        | ❌       | Helper text below the map.                                     |
| `error`       | `boolean`                          | ❌       | Error state for the form control.                              |
| `required`    | `boolean`                          | ❌       | Marks the field as required.                                   |
| `disabled`    | `boolean`                          | ❌       | Disables the picker.                                           |
| `zoom`        | `number` (default: `15`)           | ❌       | Initial zoom level of the Leaflet map.                         |
| `ref`         | `Ref<Map>`                         | ❌       | Ref to the `MapContainer` instance.                            |
| `inputRef`    | `Ref<HTMLInputElement>`            | ❌       | Ref to the hidden input element.                               |
| `slotProps`   | `LocationPickerProps["slotProps"]` | ❌       | Props for inner components.                                    |
| `slots`       | `LocationPickerProps["slots"]`     | ❌       | Custom nodes (e.g. `floatingMarker`).                          |

Inherits additional props from [`MapContainer`](https://react-leaflet.js.org/docs/api-map/#mapcontainer) (except `children` and `center`).

### Basic usage example

```tsx
import 'leaflet/dist/leaflet.css';

import { useState } from 'react';
import { LocationPicker } from '@reevolve/components';

function App() {
	const [latLng, setLatLng] = useState();

	return (
		<LocationPicker
			value={latLng}
			onChange={(value) => setLatLng(value)}
		/>
	);
}

export default App;
```

---

## LocationView

this component use for show a location on map using `Leaflet`.

for using this component import leaflet styles in your project:

```ts
import 'leaflet/dist/leaflet.css';
```

### Props

| **Prop**    | **Type**                         | Required | **Description**                                      |
| ----------- | -------------------------------- | -------- | ---------------------------------------------------- |
| `position`  | `LatLngLiteral`                  | ✅       | Map marker position.                                 |
| `zoom`      | `number` (default: `17`)         | ❌       | Initial zoom level of the Leaflet map.             |
| `ref`       | `Ref<Map>`                       | ❌       | Ref to the `MapContainer` instance.                |
| `slotProps` | `LocationViewProps["slotProps"]` | ❌       | Props for `mapWrapper`, `tileLayer`, `marker`, etc. |

### Basic usage example

```tsx
import 'leaflet/dist/leaflet.css';

import { LocationView } from '@reevolve/components';

function App() {
	return (
		<LocationView
			position={{ lat: 35.6997, lng: 51.338 }}
			zoom={17}
		/>
	);
}

export default App;
```

---

## Upload

The `Upload` component is a versatile file uploader that integrates with the MUI ecosystem. It supports single and multiple file uploads, drag-and-drop functionality, and a variety of customization options to suit your application's needs. Below is the detailed documentation for this component:

### Basic usage example

**Single File Upload**

```tsx
<Upload
	label="Upload your profile picture"
	value={file}
	onRemove={() => setFile(undefined)}
	onDrop={(acceptedFiles) => setFile(acceptedFiles[0])}
	helperText="Only JPG or PNG files are allowed."
	accept={['image/jpeg', 'image/png']}
/>
```

**Multiple File Upload**

```tsx
<Upload
	label="Upload your documents"
	multiple
	value={files}
	onRemove={(file) => setFiles((prev) => prev.filter((f) => f !== file))}
	onRemoveAll={() => setFiles([])}
	onDrop={(acceptedFiles) => setFiles((prev) => [...prev, ...acceptedFiles])}
	maxFiles={5}
	helperText="You can upload up to 5 files."
/>
```

### **Props**

| Prop                      | Type                          | Default | Description                                                    |
| ------------------------- | ----------------------------- | ------- | -------------------------------------------------------------- |
| `required`                | `boolean`                     | `false` | Indicates if the field is required.                            |
| `loading`                 | `boolean`                     | `false` | Displays a spinner overlay when `true`.                        |
| `imagePreviewAspectRatio` | `number`                      | `16/9`  | Single image file preview aspect ratio.                        |
| `singleFileListPreview`   | `boolean`                     | `true`  | Show single-file preview in the multi-file list view.          |
| `enableDownload`          | `boolean`                     | `false` | Show download button in file previews.                         |
| `slotProps`               | `object`                      | `{}`    | Allows customization of inner components via props.            |
| `slots`                   | `object`                      | `{}`    | Allows replacing default placeholders with custom React nodes. |
| `sx`                      | `object` or `function`        | -       | Custom styles for the root container.                          |
| `multiple`                | `boolean`                     | `false` | Enables uploading multiple files.                              |
| `name`                    | `string`                      | -       | Specifies the name of the input field.                         |
| `value`                   | `File` or `File[]`            | -       | The current value of the file(s).                              |
| `label`                   | `React.ReactNode`             | -       | Displays a label for the upload input.                         |
| `error`                   | `boolean`                     | `false` | Shows an error state for the input.                            |
| `disabled`                | `boolean`                     | `false` | Disables the input.                                            |
| `helperText`              | `React.ReactNode`             | -       | Provides additional information or feedback.                   |
| `thumbnail`               | `boolean`                     | `false` | Enables thumbnail previews for uploaded files.                 |
| `onDelete`                | `function`                    | -       | Callback when a file is deleted.                               |
| `onUpload`                | `function`                    | -       | Callback when files are uploaded.                              |
| `onRemove`                | `(file: File) => void`        | -       | Callback when a specific file is removed.                      |
| `onRemoveAll`             | `function`                    | -       | Callback when all files are removed.                           |
| `onBlur`                  | `function`                    | -       | Triggered on input blur.                                       |
| `maxFiles`                | `number`                      | -       | Maximum number of files allowed.                               |
| `minSize`                 | `number`                      | -       | Minimum file size in bytes.                                    |
| `maxSize`                 | `number`                      | -       | Maximum file size in bytes.                                    |
| `accept`                  | `string[]`                    | -       | Array of accepted file MIME types.                             |
| `onDrop`                  | `(files, rejections) => void` | -       | Callback for handling dropped files.                           |

#### **Slots and Slot Props**

The `Upload` component provides customizable inner components via `slotProps` and `slots`. Below are the customizable parts:

| Slot                     | Description                                     |
| ------------------------ | ----------------------------------------------- |
| `wrap`                   | Wrapper for the input area.                     |
| `formLabel`              | Props for the MUI `FormLabel`.                  |
| `helperText`             | Props for the MUI `FormHelperText`.             |
| `formControl`            | Props for the MUI `FormControl`.                |
| `deleteButton`           | Props for the delete button.                    |
| `deleteIconButton`       | Props for the icon-based delete button.         |
| `actionButtonsContainer` | Props for the container holding action buttons. |
| `removeAllButton`        | Props for the "Remove All" button.              |
| `uploadButton`           | Props for the "Upload" button.                  |
| `multiFilePreview`       | Props for the multi-file preview area.          |
| `singleFilePreview`      | Props for the single-file preview area.         |
| `placeholder`            | Custom placeholder for the dropzone area.       |
| `rejectionFiles`         | Props for showing rejected files.               |
| `downloadIconButton`     | Props for the download icon button.             |

---

## CodeField

The `CodeField` component is an OTP (One-Time Password) input field built on top of the [`mui-one-time-password-input`](https://www.npmjs.com/package/mui-one-time-password-input) package. It provides a user-friendly interface for entering verification codes, supporting character validation, completion callbacks, and deep integration with MUI components.

### Basic usage example

```tsx
<CodeField
	length={6}
	value={code}
	onChange={setCode}
	onComplete={(value) => console.log('Completed code:', value)}
	label="Enter your verification code"
	helperText="The code was sent to your phone."
/>
```

### **Props**

| Prop              | Type                                                    | Default | Description                                                                    |
| ----------------- | ------------------------------------------------------- | ------- | ------------------------------------------------------------------------------ |
| `value`           | `string`                                                | `""`    | The current value of the OTP input.                                            |
| `length`          | `number`                                                | `6`     | Number of input boxes (length of the code).                                    |
| `autoFocus`       | `boolean`                                               | `false` | Automatically focuses the first input on mount.                                |
| `TextFieldsProps` | `TextFieldProps` or `(index: number) => TextFieldProps` | -       | Props to apply to each `TextField`, or a function that returns them per index. |
| `onComplete`      | `(value: string) => void`                               | -       | Called when all inputs are filled.                                             |
| `validateChar`    | `(character: string, index: number) => boolean`         | -       | Custom validator for each character at a given index.                          |
| `onChange`        | `(value: string) => void`                               | -       | Called whenever the value changes.                                             |
| `onBlur`          | `(value: string, isCompleted: boolean) => void`         | -       | Called when the input loses focus.                                             |
| `label`           | `string` or `React.ReactNode`                           | -       | Optional label shown above the input field.                                    |
| `required`        | `boolean`                                               | `false` | Marks the input as required.                                                   |
| `helperText`      | `string` or `React.ReactNode`                           | -       | Additional text displayed below the field.                                     |
| `error`           | `boolean`                                               | `false` | Shows the field in error state.                                                |
| `disabled`        | `boolean`                                               | `false` | Disables all input boxes.                                                      |
| `variant`         | `TextFieldProps['variant']`                             | –       | MUI TextField variant for OTP inputs.                                          |
| `size`            | `TextFieldProps['size']`                                | –       | MUI TextField size.                                                            |
| `color`           | `TextFieldProps['color']`                               | –       | MUI TextField color.                                                           |
| `firstInputRef`   | `Ref<any>`                                              | –       | Ref to the first input box, useful for focus control.                          |
| `slotProps`       | `object`                                                | `{}`    | Custom props for inner MUI components.                                         |

### **Slot Props**

The `CodeField` component supports customization of internal MUI components using the `slotProps` prop.

| Slot          | Description                                                                     |
| ------------- | ------------------------------------------------------------------------------- |
| `formLabel`   | Props passed to the MUI `FormLabel` component.                                  |
| `helperText`  | Props passed to the MUI `FormHelperText` component.                             |
| `formControl` | Props passed to the MUI `FormControl` component, excluding children, name, etc. |

---

## Image

The `Image` component is a **lazy-loading image renderer** built on top of [`react-lazy-load-image-component`](https://www.npmjs.com/package/react-lazy-load-image-component), wrapped in MUI’s `Box` for styling flexibility and responsive layout support.

It supports features like loading effects, placeholder images, intersection observer customization, and MUI-style `aspectRatio` control.

### Basic usage example

```tsx
<Image
	src="/images/product.jpg"
	alt="Product image"
	aspectRatio={16 / 9}
	sx={{ borderRadius: 1 }}
/>
```

### **Props**

The table below lists the most important props available in `Image`. It includes props inherited from MUI's `Box`, the `LazyLoadImage` component, and additional customizations.

| Prop                      | Type                                                       | Default      | Description                                                              |
| ------------------------- | ---------------------------------------------------------- | ------------ | ------------------------------------------------------------------------ |
| `src`                     | `string`                                                   | –            | Image source URL.                                                        |
| `alt`                     | `string`                                                   | –            | Alternative text for the image.                                          |
| `effect`                  | `'blur' \| 'opacity' \| 'black-and-white'`                 | `'blur'`     | The effect to apply while the image is loading.                          |
| `placeholderSrc`          | `string`                                                   | –            | A low-resolution image to show as a placeholder.                         |
| `delayTime`               | `number`                                                   | `0`          | Delay in milliseconds before loading starts.                             |
| `delayMethod`             | `'debounce' \| 'throttle'`                                 | `'throttle'` | The delay strategy used.                                                 |
| `threshold`               | `number`                                                   | `100`        | Distance in pixels before the image enters viewport to start loading.    |
| `beforeLoad`              | `() => void`                                               | –            | Called before the image starts loading.                                  |
| `placeholder`             | `ReactNode`                                                | –            | A custom placeholder component.                                          |
| `wrapperProps`            | `object`                                                   | –            | Props passed to the wrapper span around the image.                       |
| `scrollPosition`          | `object`                                                   | –            | Scroll position (used with higher-order component for scroll awareness). |
| `visibleByDefault`        | `boolean`                                                  | `false`      | If `true`, the image is visible without waiting for intersection.        |
| `useIntersectionObserver` | `boolean`                                                  | `true`       | Whether to use the `IntersectionObserver` API for lazy loading.          |
| `srcSet`                  | `string`                                                   | –            | Sets of images for responsive loading.                                   |
| `aspectRatio`             | `string \| number`                                         | –            | Applies a CSS aspect ratio to the image container.                       |
| `objectFit`               | `'contain' \| 'cover' \| 'fill' \| 'none' \| "scale-down"` | `'cover'`    | Applies a CSS objectFit to the image container.                          |
| `disabledEffect`          | `boolean`                                                  | `false`      | Disables loading effects like blur or fade-in.                           |
| `ref`                     | `React.Ref<HTMLSpanElement>`                               | –            | Ref for the wrapper element.                                             |
| `slotProps`               | `object`                                                   | –            | Custom props for internal elements like the image or overlay.            |

Also exported: `imageClasses` — CSS class names for the image wrapper.

### **Slot Props**

Customize internal structure using the `slotProps` object:

| Slot      | Description                                                             |
| --------- | ----------------------------------------------------------------------- |
| `img`     | Props passed directly to the underlying `LazyLoadImage` element.        |
| `overlay` | Props for a span wrapper around the image (e.g., for adding gradients). |

---

## NumberField

The `NumberField` component is a **number input field** built by combining [`rc-input-number`](https://www.npmjs.com/package/rc-input-number) with MUI's [`TextField`](https://mui.com/material-ui/api/text-field/). It enables advanced number handling features such as custom parsing, formatting, and step controls, while maintaining full MUI compatibility.

This component is ideal when you need numeric inputs with proper UX, accessibility, and input control.

### Basic usage example

```tsx
<NumberField
	label="Price"
	value={price}
	onChange={setPrice}
	min={0}
	max={1000}
	step={0.5}
	precision={2}
/>
```

### **Props**

The `NumberField` supports a combination of props from MUI’s [`TextField`](https://mui.com/material-ui/api/text-field/) and selected props from [`rc-input-number`](https://www.npmjs.com/package/rc-input-number).

| Prop               | Type                                           | Default  | Description                                                 |
| ------------------ | ---------------------------------------------- | -------- | ----------------------------------------------------------- |
| `value`            | `number \| string \| null`                     | –        | Current value of the input.                                 |
| `onChange`         | `(value: T \| null) => void`                   | –        | Callback when the value changes.                            |
| `min`              | `number`                                       | –        | Minimum allowed value.                                      |
| `max`              | `number`                                       | –        | Maximum allowed value.                                      |
| `step`             | `number`                                       | `1`      | Step interval when using up/down arrows or keyboard.        |
| `precision`        | `number`                                       | –        | Number of decimal places to round to.                       |
| `formatter`        | `(value: string \| number) => string`          | –        | Function to format display value.                           |
| `parser`           | `(displayValue: string) => number`             | –        | Function to parse the input string into a number.           |
| `decimalSeparator` | `string`                                       | `.`      | Decimal separator used in parsing/formatting.               |
| `pattern`          | `string`                                       | –        | Regex pattern for the input element.                        |
| `stringMode`       | `boolean`                                      | `false`  | When `true`, returns value as string (preserves precision). |
| `controls`         | `boolean`                                      | `false`  | Whether to show increment/decrement buttons.                |
| `keyboard`         | `boolean`                                      | `true`   | Whether keyboard arrow keys affect the value.               |
| `changeOnWheel`    | `boolean`                                      | `false`  | Whether mouse wheel changes the value.                      |
| `changeOnBlur`     | `boolean`                                      | `true`   | Whether to trigger change when field loses focus.           |
| `onPressEnter`     | `(event: React.KeyboardEvent) => void`         | –        | Called when Enter key is pressed.                           |
| `onInput`          | `(event: React.FormEvent) => void`             | –        | Called when input value changes.                            |
| `onStep`           | `(value: T, info: { offset: number }) => void` | –        | Called when step up/down is triggered.                      |
| `upHandler`        | `ReactNode`                                    | –        | Custom icon/component for increment button.                 |
| `downHandler`      | `ReactNode`                                    | –        | Custom icon/component for decrement button.                 |
| `prefixCls`        | `string`                                       | –        | CSS class prefix for the underlying input number.           |

Additionally, all standard props from MUI's [`TextField`](https://mui.com/material-ui/api/text-field/) (except the omitted ones) are supported.

### Notes

- The `NumberField` is **not a native `<input type="number">`**, but instead provides more control over parsing and formatting.
- The component behaves like a regular MUI `<TextField>` with full support for styling, labels, helper texts, etc.
- Use `formatter` and `parser` to control how numbers are displayed and stored (e.g., showing currency format).
- `stringMode` is useful for preserving decimal precision when working with big numbers.

---

## FileThumbnail

Displays a file icon or image thumbnail with optional tooltip, remove, and download actions. Used internally by `Upload` and exported for custom file lists.

### Basic usage example

```tsx
import { FileThumbnail } from '@reevolve/components';

<FileThumbnail
	file={file}
	tooltip
	imageView
	onRemove={() => removeFile(file)}
/>
```

### Props

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `file` | `File` | – | File to display (required). |
| `tooltip` | `boolean` | – | Show filename in a tooltip. |
| `imageView` | `boolean` | – | Render image preview for image types. |
| `onRemove` | `() => void` | – | Shows remove button when provided. |
| `onDownload` | `() => void` | – | Shows download button when provided. |
| `slotProps` | `{ img?, icon?, removeButton?, downloadButton? }` | – | Inner element props. |

Also supports [MUI Stack](https://mui.com/material-ui/api/stack/) props (`sx`, `className`, etc.).

### Exported helpers

| Export | Description |
| ------ | ----------- |
| `fileThumbnailClasses` | CSS class names for styling thumbnails. |
| `fileFormat` | Returns format key (`'image'`, `'pdf'`, etc.) from a URL or filename. |
| `fileThumb` | Returns a React icon component for the file format. |
| `fileTypeByUrl` | MIME-style type string from URL. |
| `fileNameByUrl` | Extracts filename from URL. |
| `fileData` | Returns `{ name, size, preview, type }` for a `File` or URL. |