validin/README.md

A package to validate Persian/English inputs, IPs, etc.

## Validin

A concise React input validation toolkit with built‑in validation, theming, and multi‑language support.

## Tailwind CSS Required

This package is built with Tailwind CSS utility classes and requires Tailwind to be installed and configured in your app. See the Tailwind installation guide: [Tailwind Docs](https://tailwindcss.com/docs/installation)

## Features

- **Flexible theming**: `glassmorphism`, `neumorphism`, `skeuomorphism`, `gradient`, `micro`, `minimal`
- **Multi-language**: English (default) and Persian/Farsi via `lang="fa"`
- **Built-in validation**: Email, IP, phone (including Iranian), DNS, MAC address, port, and strong password
- **TypeScript**: Full TypeScript support
- **Native input props**: All native `input` props are supported and forwarded

## Installation

```bash
npm install validin
# or
yarn add validin
```

## Available Components

```ts
import {
  EmailInput,
  PhoneInput,
  IranianPhoneInput,
  IPInput,
  DNSInput,
  MacAddressInput,
  PortInput,
  StrongPasswordInput,
} from "validin";
```

## Basic Usage

```jsx
import { EmailInput, StrongPasswordInput } from "validin";

export default function Example() {
  return (
    <div className="max-w-md space-y-4">
      <EmailInput
        label="Email"
        placeholder="user@example.com"
        onValid={(value) => console.log("valid email:", value)}
      />

      <StrongPasswordInput
        label="Password"
        placeholder="Enter a strong password"
        onValid={(value) => console.log("valid password:", value)}
      />
    </div>
  );
}
```

## Theming

Each component supports a `theme` prop and a `themeOptions` object. Valid themes and their option keys:

- **glassmorphism**: `blur`, `bgColor`, `borderColor`, `shadow`
- **neumorphism**: `bgColor`, `shadow`, `textColor`, `radius`
- **skeuomorphism**: `texture`, `shadow`, `radius`
- **gradient**: `direction`, `fromColor`, `toColor`, `textColor`
- **micro**: `transition`, `duration`, `scale`
- **minimal**: `bgColor`, `borderColor`, `textColor`

Example:

```jsx
<EmailInput
  theme="glassmorphism"
  themeOptions={{
    blur: "backdrop-blur-md",
    bgColor: "bg-white/10",
    borderColor: "border border-white/30",
    shadow: "shadow-lg",
  }}
  className="w-full"
  label="Email"
  placeholder="user@example.com"
  onValid={(value) => console.log(value)}
/>
```

## Multi-language (fa)

```jsx
<IranianPhoneInput
  label="شماره موبایل"
  placeholder="09123456789"
  lang="fa"
  onValid={(value) => console.log(value)}
/>
```

## API (Common Props)

All components accept the following common props in addition to all native `input` props:

```ts
type ThemeName =
  | "glassmorphism"
  | "neumorphism"
  | "skeuomorphism"
  | "gradient"
  | "micro"
  | "minimal";

interface CommonProps {
  label?: string;
  placeholder?: string;
  className?: string;
  theme?: ThemeName;
  themeOptions?: Record<string, unknown>;
  lang?: "en" | "fa";
  onValid?: (value: string | boolean) => void;
}
```

Notes:

- `onValid` is called with the validated value when the input passes validation.
- Direction (`dir`) is automatically set based on `lang`.

## Additional Examples

```jsx
<PhoneInput label="Phone" placeholder="(123) 456-7890" onValid={console.log} />
<IPInput label="IP Address" placeholder="192.168.1.1" onValid={console.log} />
<DNSInput label="DNS" placeholder="example.com" onValid={console.log} />
<MacAddressInput label="MAC" placeholder="AA:BB:CC:DD:EE:FF" onValid={console.log} />
<PortInput label="Port" placeholder="8080" type="number" onValid={console.log} />
```

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please open a pull request.

## Support

For support, please open an issue or contact: `mohamad.ganjif@gmail.com`.