# FormField

## Description

A form field wrapper component that provides consistent labeling, validation messaging, and styling for form inputs. Integrates seamlessly with the Form component to provide a complete form field experience with error handling, required field indicators, and accessibility features.

## Aliases

- FormField
- FieldWrapper
- InputWrapper
- FormGroup
- Field

## Props Breakdown

**Extends:** `HTMLAttributes<HTMLDivElement>`

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `name` | `string` | - | Yes | Name of the form field |
| `label` | `string` | - | No | Label for the form field |
| `children` | `ReactNode` | - | Yes | Form input component to wrap |
| `message` | `string` | - | No | Message for the form field |
| `hasMessage` | `boolean` | `false` | No | Whether there is a message/error for the field |
| `infoIcon` | `ReactNode` | - | No | Info icon for the form field |
| `required` | `boolean` | `false` | No | Whether the form field is required |
| `validate` | `FieldValidationFunction` | - | No | Validation function for the form field |
| `disabled` | `boolean` | `false` | No | Whether the form field is disabled |
| `invalid` | `boolean` | `false` | No | Whether the form field is invalid |
| `id` | `string` | - | No | ID for the form field |

Plus all standard HTML div attributes (className, style, onClick, etc.).

## Examples

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

function BasicExample() {
  return (
    <FormField name="email" label="Email Address">
      <Input inputType="Email" placeholder="Enter your email" />
    </FormField>
  );
}
```

### Required Field
```tsx
function RequiredFieldExample() {
  return (
    <FormField name="firstName" label="First Name" required>
      <Input placeholder="Enter your first name" />
    </FormField>
  );
}
```

### Field with Validation Message
```tsx
function ValidationMessageExample() {
  const [email, setEmail] = useState('');
  const [isValid, setIsValid] = useState(true);

  const validateEmail = (value) => {
    const valid = /\S+@\S+\.\S+/.test(value);
    setIsValid(valid);
    return valid;
  };

  return (
    <FormField 
      name="email" 
      label="Email Address" 
      required
      invalid={!isValid}
      message={!isValid ? "Please enter a valid email address" : ""}
    >
      <Input 
        inputType="Email"
        value={email}
        onValueChange={(value) => {
          setEmail(value);
          validateEmail(value);
        }}
      />
    </FormField>
  );
}
```

### Field with Info Icon
```tsx
function InfoIconExample() {
  return (
    <FormField 
      name="password" 
      label="Password" 
      required
      infoIcon={
        <Tooltip target={<Icon icon="Info" size="Small" />}>
          Password must be at least 8 characters with uppercase, lowercase, and numbers
        </Tooltip>
      }
    >
      <Input inputType="Password" />
    </FormField>
  );
}
```

### Disabled Field
```tsx
function DisabledFieldExample() {
  return (
    <FormField 
      name="username" 
      label="Username" 
      disabled
      message="Username cannot be changed"
    >
      <Input value="john_doe" disabled />
    </FormField>
  );
}
```

### Different Input Types
```tsx
function InputTypesExample() {
  return (
    <div className="form-fields">
      <FormField name="name" label="Full Name" required>
        <Input placeholder="Enter your name" />
      </FormField>
      
      <FormField name="bio" label="Biography">
        <TextArea placeholder="Tell us about yourself" rows={4} />
      </FormField>
      
      <FormField name="country" label="Country" required>
        <Select>
          <Option value="us">United States</Option>
          <Option value="uk">United Kingdom</Option>
          <Option value="ca">Canada</Option>
        </Select>
      </FormField>
      
      <FormField name="newsletter" label="Email Preferences">
        <Checkbox>Subscribe to our newsletter</Checkbox>
      </FormField>
      
      <FormField name="plan" label="Subscription Plan" required>
        <RadioGroup>
          <RadioButton value="basic">Basic Plan</RadioButton>
          <RadioButton value="premium">Premium Plan</RadioButton>
          <RadioButton value="enterprise">Enterprise Plan</RadioButton>
        </RadioGroup>
      </FormField>
    </div>
  );
}
```

### Custom Validation
```tsx
function CustomValidationExample() {
  const validateAge = (setError, value) => {
    if (!value) {
      setError('Age is required');
      return false;
    }
    
    const age = parseInt(value);
    if (isNaN(age) || age < 18 || age > 120) {
      setError('Age must be between 18 and 120');
      return false;
    }
    
    return true;
  };

  return (
    <FormField 
      name="age" 
      label="Age" 
      required
      validate={validateAge}
    >
      <Input inputType="Number" placeholder="Enter your age" />
    </FormField>
  );
}
```

### Form Integration
```tsx
function FormIntegrationExample() {
  const handleSubmit = (values, setError) => {
    console.log('Form values:', values);
  };

  return (
    <Form onSubmit={handleSubmit}>
      <FormField name="firstName" label="First Name" required>
        <Input />
      </FormField>
      
      <FormField name="lastName" label="Last Name" required>
        <Input />
      </FormField>
      
      <FormField name="email" label="Email" required>
        <Input inputType="Email" />
      </FormField>
      
      <FormField name="phone" label="Phone Number">
        <Input inputType="Tel" />
      </FormField>
      
      <FormField name="message" label="Message">
        <TextArea rows={4} />
      </FormField>
      
      <Button actionType="submit">Submit</Button>
    </Form>
  );
}
```

### Conditional Fields
```tsx
function ConditionalFieldsExample() {
  const [hasCompany, setHasCompany] = useState(false);

  return (
    <Form>
      <FormField name="name" label="Full Name" required>
        <Input />
      </FormField>
      
      <FormField name="hasCompany" label="Employment">
        <Checkbox 
          checked={hasCompany}
          onValueChange={setHasCompany}
        >
          I am employed by a company
        </Checkbox>
      </FormField>
      
      {hasCompany && (
        <>
          <FormField name="companyName" label="Company Name" required>
            <Input placeholder="Enter company name" />
          </FormField>
          
          <FormField name="jobTitle" label="Job Title" required>
            <Input placeholder="Enter your job title" />
          </FormField>
        </>
      )}
      
      <Button actionType="submit">Submit</Button>
    </Form>
  );
}
```

### Field Groups
```tsx
function FieldGroupsExample() {
  return (
    <Form>
      <div className="form-section">
        <Text type="Heading5">Personal Information</Text>
        
        <FormField name="firstName" label="First Name" required>
          <Input />
        </FormField>
        
        <FormField name="lastName" label="Last Name" required>
          <Input />
        </FormField>
        
        <FormField name="dateOfBirth" label="Date of Birth">
          <DatePicker />
        </FormField>
      </div>
      
      <div className="form-section">
        <Text type="Heading5">Contact Information</Text>
        
        <FormField name="email" label="Email" required>
          <Input inputType="Email" />
        </FormField>
        
        <FormField name="phone" label="Phone">
          <Input inputType="Tel" />
        </FormField>
        
        <FormField name="address" label="Address">
          <TextArea rows={3} />
        </FormField>
      </div>
      
      <Button actionType="submit">Save</Button>
    </Form>
  );
}
```