# Input

## Description

Text input component with validation, icons, and form integration support. Provides a flexible foundation for collecting user text input with proper accessibility and styling.

## Aliases

- Text Input
- Text Field
- Input Field
- Form Input

## Props Breakdown

**Extends:** `InputHTMLAttributes<HTMLInputElement>` (excluding `type` and `value`) + `ControlledFormComponentProps<string>`

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `inputType` | `'Text' \| 'Number' \| 'Email' \| 'Password'` | `'Text'` | No | Type of input field |
| `leadingIcon` | `ReactNode` | - | No | Icon displayed before the input text |
| `trailingIcon` | `ReactNode` | - | No | Icon displayed after the input text |
| `component-variant` | `string` | - | No | Override styling variant |
| `initialValue` | `string` | - | No | Initial value for controlled form usage |
| `value` | `string` | - | No | Controlled value |
| `onValueChange` | `(value: string) => void` | - | No | Callback when input value changes |
| `disabled` | `boolean` | `false` | No | Whether the input is disabled |
| `required` | `boolean` | `false` | No | Whether the input is required |
| `invalid` | `boolean` | `false` | No | Whether the input value is invalid |
| `id` | `string` | - | No | HTML id attribute |
| `placeholder` | `string` | - | No | Placeholder text |
| `className` | `string` | - | No | Additional CSS class names |

Plus all standard HTML input attributes (name, autoComplete, autoFocus, min, max, step, pattern, etc.) except `type` and `value`.

## Examples

### Basic Usage
```tsx
import { Input } from '@delightui/components';

function BasicExample() {
  const [value, setValue] = useState('');

  return (
    <Input
      placeholder="Enter your name"
      value={value}
      onValueChange={setValue}
    />
  );
}
```

### Input Types
```tsx
function InputTypesExample() {
  return (
    <div className="input-types">
      <Input 
        inputType="Text"
        placeholder="Enter text"
      />
      
      <Input 
        inputType="Email"
        placeholder="Enter email address"
      />
      
      <Input 
        inputType="Password"
        placeholder="Enter password"
      />
      
      <Input 
        inputType="Number"
        placeholder="Enter number"
      />
    </div>
  );
}
```

### With Icons
```tsx
import { 
  UserIcon, 
  EnvelopeIcon, 
  LockClosedIcon,
  MagnifyingGlassIcon,
  EyeIcon
} from '@heroicons/react/24/outline';

function IconsExample() {
  return (
    <div className="input-icons">
      <Input 
        leadingIcon={<UserIcon />}
        placeholder="Username"
      />
      
      <Input 
        leadingIcon={<EnvelopeIcon />}
        inputType="Email"
        placeholder="Email address"
      />
      
      <Input 
        leadingIcon={<LockClosedIcon />}
        trailingIcon={<EyeIcon />}
        inputType="Password"
        placeholder="Password"
      />
      
      <Input 
        leadingIcon={<MagnifyingGlassIcon />}
        placeholder="Search..."
      />
    </div>
  );
}
```

### Form Integration
```tsx
import { Input, Form, FormField, Button } from '@delightui/components';

function FormExample() {
  const handleSubmit = (values, setError) => {
    // Validate email
    if (!values.email || !values.email.includes('@')) {
      setError('email', 'Please enter a valid email address');
      return;
    }
    
    // Validate password
    if (!values.password || values.password.length < 8) {
      setError('password', 'Password must be at least 8 characters');
      return;
    }
    
    console.log('Form submitted:', values);
  };

  return (
    <Form onSubmit={handleSubmit}>
      <FormField 
        name="firstName" 
        label="First Name"
        required
      >
        <Input 
          placeholder="Enter your first name"
          leadingIcon={<UserIcon />}
        />
      </FormField>

      <FormField 
        name="lastName" 
        label="Last Name"
        required
      >
        <Input 
          placeholder="Enter your last name"
          leadingIcon={<UserIcon />}
        />
      </FormField>

      <FormField 
        name="email" 
        label="Email Address"
        required
      >
        <Input 
          inputType="Email"
          placeholder="Enter your email"
          leadingIcon={<EnvelopeIcon />}
        />
      </FormField>

      <FormField 
        name="password" 
        label="Password"
        required
      >
        <Input 
          inputType="Password"
          placeholder="Enter password"
          leadingIcon={<LockClosedIcon />}
        />
      </FormField>

      <Button actionType="submit">
        Create Account
      </Button>
    </Form>
  );
}
```

### Validation States
```tsx
import { Text } from '@delightui/components';

function ValidationExample() {
  const [email, setEmail] = useState('');
  const [isValid, setIsValid] = useState(true);

  const validateEmail = (value) => {
    const isValidEmail = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
    setIsValid(isValidEmail);
    return isValidEmail;
  };

  const handleEmailChange = (value) => {
    setEmail(value);
    if (value) {
      validateEmail(value);
    } else {
      setIsValid(true);
    }
  };

  return (
    <div className="validation-example">
      <Input
        inputType="Email"
        value={email}
        onValueChange={handleEmailChange}
        invalid={!isValid && email.length > 0}
        placeholder="Enter email address"
        leadingIcon={<EnvelopeIcon />}
      />
      
      {!isValid && email.length > 0 && (
        <Text type="BodySmall" className="error-message">
          Please enter a valid email address
        </Text>
      )}
    </div>
  );
}
```

### Disabled State
```tsx
function DisabledExample() {
  return (
    <div className="disabled-inputs">
      <Input 
        disabled
        placeholder="Disabled input"
        value="Cannot edit this"
      />
      
      <Input 
        disabled
        leadingIcon={<UserIcon />}
        placeholder="Disabled with icon"
      />
    </div>
  );
}
```

### Number Input with Validation
```tsx
import { Text } from '@delightui/components';

function NumberInputExample() {
  const [age, setAge] = useState('');
  const [error, setError] = useState('');

  const handleAgeChange = (value) => {
    setAge(value);
    
    const numValue = parseInt(value);
    if (value && (isNaN(numValue) || numValue < 0 || numValue > 120)) {
      setError('Please enter a valid age (0-120)');
    } else {
      setError('');
    }
  };

  return (
    <div className="number-input">
      <Input
        inputType="Number"
        value={age}
        onValueChange={handleAgeChange}
        invalid={!!error}
        placeholder="Enter your age"
        min="0"
        max="120"
      />
      
      {error && (
        <Text type="BodySmall" className="error-message">{error}</Text>
      )}
    </div>
  );
}
```

### Controlled vs Uncontrolled
```tsx
import { Button, Text } from '@delightui/components';

function ControlledExample() {
  // Controlled input
  const [controlledValue, setControlledValue] = useState('');
  
  // Uncontrolled input
  const uncontrolledRef = useRef(null);

  const getUncontrolledValue = () => {
    alert(`Uncontrolled value: ${uncontrolledRef.current?.value}`);
  };

  return (
    <div className="controlled-comparison">
      <div>
        <Text type="Heading4">Controlled Input</Text>
        <Input
          value={controlledValue}
          onValueChange={setControlledValue}
          placeholder="Controlled input"
        />
        <Text>Current value: {controlledValue}</Text>
      </div>

      <div>
        <Text type="Heading4">Uncontrolled Input</Text>
        <Input
          ref={uncontrolledRef}
          defaultValue="Initial value"
          placeholder="Uncontrolled input"
        />
        <Button onClick={getUncontrolledValue}>
          Get Value
        </Button>
      </div>
    </div>
  );
}
```

### Custom Styling
```tsx
function CustomStylingExample() {
  return (
    <div className="custom-styling">
      <Input
        component-variant="primary"
        placeholder="Primary variant"
        leadingIcon={<StarIcon />}
      />
      
      <Input
        component-variant="secondary"
        placeholder="Secondary variant"
        className="custom-input-class"
      />
    </div>
  );
}
```