validin/README.md

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

# Validin

A comprehensive React input validation package with built-in validation, theming support, and multi-language capabilities.

## Features

- 🎨 **Flexible Theming**: Pre-built themes (glassmorphism, neumorphism, skeuomorphism, gradient, micro, minimal) with customizable options
- 🌍 **Multi-language Support**: Built-in support for English (default) and Persian/Farsi
- ✅ **Built-in Validation**: Real-time validation with customizable rules
- 🎯 **TypeScript Support**: Full TypeScript support with type definitions
- 🚀 **Easy Integration**: Simple API with extensive customization options
- 📱 **Responsive Design**: Mobile-first approach with responsive styling

## Installation

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

## Basic Usage

```jsx
import { EmailInput, PasswordInput, TextInput, NumberInput } from "validin";

function App() {
  return (
    <div>
      <EmailInput
        placeholder="user@example.com"
        className="mb-4"
        label="Email"
        onValidation={(isValid, value) => console.log(isValid, value)}
      />

      <PasswordInput
        placeholder="Enter password"
        className="mb-4"
        label="Password"
        minLength={8}
        requireSpecialChar={true}
      />
    </div>
  );
}
```

## Theming

### Custom Theme Options

You can customize any theme using the `themeOptions` prop:

```jsx
<EmailInput
  theme="glassmorphism"
  themeOptions={{
    bgColor: "bg-white/10",
    backdrop: "backdrop-blur-md",
    border: "border border-white/20",
    radius: "rounded-xl",
    textColor: "text-white",
    focusColor: "focus:ring-purple-500",
  }}
  placeholder="user@example.com"
  label="Email"
/>
```

### Combining with className

You can use both theme/themeOptions and className together:

```jsx
<EmailInput
  theme="glassmorphism"
  themeOptions={{
    bgColor: "bg-white/10",
    backdrop: "backdrop-blur-md",
    border: "border border-white/20",
    radius: "rounded-xl",
    textColor: "text-white",
  }}
  className="mb-4 w-full max-w-md"
  placeholder="user@example.com"
  label="Email"
/>
```

## Multi-language Support

### Persian/Farsi Example

```jsx
<EmailInput
  theme="glassmorphism"
  themeOptions={{
    bgColor: "bg-white/10",
    backdrop: "backdrop-blur-md",
    border: "border border-white/20",
    radius: "rounded-xl",
    textColor: "text-white",
  }}
  placeholder="user@example.com"
  lang="fa"
  className="mb-4"
  label="ایمیل"
/>

<PasswordInput
  theme="neumorphism"
  themeOptions={{
    bgColor: "bg-gray-200",
    shadow: "shadow-inner",
    radius: "rounded-lg",
    textColor: "text-gray-800",
  }}
  lang="fa"
  className="mb-4"
  label="رمز عبور"
  placeholder="رمز عبور را وارد کنید"
/>
```

## Available Components

### EmailInput

```jsx
<EmailInput
  theme="glassmorphism"
  themeOptions={{
    bgColor: "bg-white/10",
    backdrop: "backdrop-blur-md",
    border: "border border-white/20",
    radius: "rounded-xl",
    textColor: "text-white",
    focusColor: "focus:ring-purple-500",
  }}
  className="mb-4"
  label="Email Address"
  placeholder="user@example.com"
  required={true}
  onValidation={(isValid, value) => console.log(isValid, value)}
/>
```

### PasswordInput

```jsx
<PasswordInput
  theme="neumorphism"
  themeOptions={{
    bgColor: "bg-gray-200",
    shadow: "shadow-inner",
    radius: "rounded-lg",
    textColor: "text-gray-800",
    focusColor: "focus:ring-blue-500",
  }}
  className="mb-4"
  label="Password"
  placeholder="Enter your password"
  minLength={8}
  requireUppercase={true}
  requireLowercase={true}
  requireNumbers={true}
  requireSpecialChar={true}
  showStrengthIndicator={true}
  showToggleVisibility={true}
  onValidation={(isValid, value, strength) =>
    console.log(isValid, value, strength)
  }
/>
```

### NumberInput

```jsx
<NumberInput
  theme="gradient"
  themeOptions={{
    bgColor: "bg-gradient-to-r from-blue-500 to-purple-600",
    textColor: "text-white",
    border: "border-none",
    radius: "rounded-lg",
    focusColor: "focus:ring-white",
  }}
  className="mb-4"
  label="Amount"
  placeholder="Enter amount"
  min={0}
  max={1000000}
  step={0.01}
  currency="USD"
  thousandSeparator={true}
  onValidation={(isValid, value) => console.log(isValid, value)}
/>
```

### PhoneInput

```jsx
<PhoneInput
  theme="micro"
  themeOptions={{
    bgColor: "bg-white",
    border: "border border-gray-200",
    radius: "rounded-md",
    textColor: "text-gray-700",
    fontSize: "text-sm",
    padding: "px-2 py-1",
  }}
  className="mb-4"
  label="Phone Number"
  placeholder="Enter phone number"
  country="US"
  format="international"
  onValidation={(isValid, value, country) =>
    console.log(isValid, value, country)
  }
/>
```

## Validation Features

All components include built-in validation with real-time feedback and customizable validation rules.

## API Reference

### Common Props

All components support these common props:

```typescript
interface CommonProps {
  theme?:
    | "glassmorphism"
    | "neumorphism"
    | "skeuomorphism"
    | "gradient"
    | "micro"
    | "minimal";
  themeOptions?: ThemeOptions;
  className?: string;
  label?: string;
  placeholder?: string;
  required?: boolean;
  disabled?: boolean;
  lang?: "en" | "fa";
  onValidation?: (isValid: boolean, value: string, ...args: any[]) => void;
  customValidation?: (value: string) => { isValid: boolean; message: string };
  asyncValidation?: (
    value: string
  ) => Promise<{ isValid: boolean; message: string }>;
}
```

## Examples

### Complete Form Example

```jsx
import {
  EmailInput,
  PasswordInput,
  TextInput,
  NumberInput,
  PhoneInput,
} from "validin";

function RegistrationForm() {
  const [formData, setFormData] = useState({});
  const [isFormValid, setIsFormValid] = useState(false);

  const handleValidation = (field, isValid, value) => {
    setFormData((prev) => ({ ...prev, [field]: { isValid, value } }));
  };

  return (
    <div className="max-w-md mx-auto p-6 bg-white rounded-lg shadow-lg">
      <h2 className="text-2xl font-bold mb-6 text-center">Sign Up</h2>

      <TextInput
        theme="glassmorphism"
        themeOptions={{
          bgColor: "bg-white/10",
          backdrop: "backdrop-blur-md",
          border: "border border-white/20",
          radius: "rounded-lg",
          textColor: "text-white",
        }}
        className="mb-4"
        label="Full Name"
        placeholder="Enter your full name"
        required={true}
        onValidation={(isValid, value) =>
          handleValidation("name", isValid, value)
        }
      />

      <EmailInput
        theme="neumorphism"
        themeOptions={{
          bgColor: "bg-gray-200",
          shadow: "shadow-inner",
          radius: "rounded-lg",
          textColor: "text-gray-800",
        }}
        className="mb-4"
        label="Email"
        placeholder="user@example.com"
        required={true}
        onValidation={(isValid, value) =>
          handleValidation("email", isValid, value)
        }
      />

      <PhoneInput
        theme="skeuomorphism"
        themeOptions={{
          bgColor: "bg-gradient-to-b from-gray-100 to-gray-200",
          border: "border border-gray-400",
          shadow: "shadow-md",
          radius: "rounded-lg",
          textColor: "text-gray-800",
        }}
        className="mb-4"
        label="Phone Number"
        placeholder="Enter phone number"
        country="US"
        onValidation={(isValid, value) =>
          handleValidation("phone", isValid, value)
        }
      />

      <PasswordInput
        theme="gradient"
        themeOptions={{
          bgColor: "bg-gradient-to-r from-blue-500 to-purple-600",
          textColor: "text-white",
          border: "border-none",
          radius: "rounded-lg",
        }}
        className="mb-6"
        label="Password"
        placeholder="Create a strong password"
        minLength={8}
        requireUppercase={true}
        requireLowercase={true}
        requireNumbers={true}
        requireSpecialChar={true}
        showStrengthIndicator={true}
        showToggleVisibility={true}
        onValidation={(isValid, value) =>
          handleValidation("password", isValid, value)
        }
      />

      <button
        type="submit"
        disabled={!isFormValid}
        className="w-full py-3 px-4 bg-blue-600 text-white rounded-lg font-medium hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
      >
        Sign Up
      </button>
    </div>
  );
}
```

### Persian/Farsi Form Example

```jsx
function PersianForm() {
  return (
    <div
      className="max-w-md mx-auto p-6 bg-white rounded-lg shadow-lg"
      dir="rtl"
    >
      <h2 className="text-2xl font-bold mb-6 text-center">ثبت نام</h2>
      <TextInput
        theme="glassmorphism"
        themeOptions={{
          bgColor: "bg-white/10",
          backdrop: "backdrop-blur-md",
          border: "border border-white/20",
          radius: "rounded-xl",
          textColor: "text-white",
        }}
        className="mb-4"
        label="نام کامل"
        placeholder="نام کامل خود را وارد کنید"
        lang="fa"
        required={true}
      />
      <EmailInput
        theme="neumorphism"
        themeOptions={{
          bgColor: "bg-gray-200",
          shadow: "shadow-md",
          radius: "rounded-xl",
          textColor: "text-black",
        }}
        className="mb-4"
        label="ایمیل"
        placeholder="user@example.com"
        lang="fa"
        required={true}
      />
      <PasswordInput
        theme="gradient"
        themeOptions={{
          bgColor: "bg-gradient-to-r from-purple-500 to-pink-600",
          textColor: "text-white",
          border: "border-none",
          radius: "rounded-xl",
        }}
        className="mb-6"
        label="رمز عبور"
        placeholder="رمز عبور قوی انتخاب کنید"
        lang="fa"
        minLength={8}
        requireUppercase={true}
        requireLowercase={true}
        requireNumbers={true}
        requireSpecialChar={true}
        showStrengthIndicator={true}
        showToggleVisibility={true}
        className="mb-6"
        label="رمز عبور"
        placeholder="رمز عبور قوی انتخاب کنید"
        lang="fa"
        minLength={8}
        requireUppercase={true}
        requireLowercase={true}
        requireNumbers={true}
        requireSpecialChar={true}
        showStrengthIndicator={true}
        showToggleVisibility={true}
      />
      <button
        type="submit"
        className="w-full py-3 px-4 bg-blue-600 text-white rounded-lg font-medium hover:bg-blue-700 transition-colors"
      >
        ثبت نام
      </button>
    </div>
  );
}
```

## TypeScript Support

Validin is built with TypeScript and provides full type definitions:

```typescript
import { EmailInput, PasswordInput, ThemeOptions } from "validin";

interface FormData {
  email: string;
  password: string;
}

const customTheme: ThemeOptions = {
  bgColor: "bg-white/10",
  backdrop: "backdrop-blur-md",
  border: "border border-white/20",
  textColor: "text-white",
  focusColor: "focus:ring-purple-500",
  radius: "rounded-lg",
};

function TypedForm() {
  const [formData, setFormData] = useState<FormData>({
    email: "",
    password: "",
  });

  const handleEmailValidation = (isValid: boolean, value: string) => {
    // Handle email validation
  };

  const handlePasswordValidation = (
    isValid: boolean,
    value: string,
    strength: string
  ) => {
    // Handle password validation
  };

  return (
    <div>
      <EmailInput
        theme="glassmorphism"
        themeOptions={customTheme}
        onValidation={handleEmailValidation}
      />
      <PasswordInput
        theme="glassmorphism"
        themeOptions={customTheme}
        onValidation={handlePasswordValidation}
      />
    </div>
  );
}
```

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

## Support

For support, please open an issue on our GitHub repository or contact us at support@validin.com.