# Checkbox

## Description

Customizable checkbox input component with support for controlled and uncontrolled states, various sizes, label positioning, and form integration. Includes proper accessibility features and validation support.

## Aliases

- Check Box
- Tick Box
- Selection Box
- Boolean Input
- Toggle Checkbox

## Props Breakdown

**Extends:** `InputHTMLAttributes<HTMLInputElement>` (excluding 'type', 'size') + `ControlledFormComponentProps<boolean>`

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `children` | `ReactNode` | - | No | Label content for the checkbox |
| `size` | `'Small' \| 'Medium' \| 'Large'` | `'Medium'` | No | Size variant of the checkbox |
| `type` | `'Default' \| 'Inverse'` | `'Default'` | No | Visual theme of the checkbox |
| `defaultChecked` | `boolean` | `false` | No | Default checked state for uncontrolled usage |
| `labelAlignment` | `'Left' \| 'Right'` | - | No | Position of the label relative to the checkbox |
| `initialValue` | `boolean` | - | No | Initial value for controlled form usage |
| `checked` | `boolean` | - | No | Controlled checked state |
| `value` | `boolean` | - | No | Current value for controlled form usage |
| `onValueChange` | `(value: boolean) => void` | - | No | Callback when checkbox value changes |
| `disabled` | `boolean` | `false` | No | Whether the checkbox is disabled |
| `required` | `boolean` | `false` | No | Whether the checkbox is required |
| `invalid` | `boolean` | `false` | No | Whether the checkbox value is invalid |
| `id` | `string` | - | No | HTML id attribute |
| `className` | `string` | - | No | Additional CSS class names |
| `name` | `string` | - | No | HTML name attribute |

*Note: In addition to the props listed above, this component inherits all HTML input attributes (except 'type' and 'size') such as `onChange`, `onFocus`, `onBlur`, `aria-*`, `data-*`, etc. It also includes controlled form component properties for integration with form libraries.*

## Examples

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

function BasicExample() {
  const [checked, setChecked] = useState(false);

  return (
    <Checkbox
      checked={checked}
      onValueChange={setChecked}
    >
      Accept terms and conditions
    </Checkbox>
  );
}
```

### Checkbox Sizes
```tsx
function SizesExample() {
  return (
    <div className="checkbox-sizes">
      <Checkbox size="Small">Small checkbox</Checkbox>
      <Checkbox size="Medium">Medium checkbox</Checkbox>
      <Checkbox size="Large">Large checkbox</Checkbox>
    </div>
  );
}
```

### Label Alignment
```tsx
function AlignmentExample() {
  return (
    <div className="checkbox-alignment">
      <Checkbox labelAlignment="Left">
        Label on the left
      </Checkbox>
      
      <Checkbox labelAlignment="Right">
        Label on the right
      </Checkbox>
    </div>
  );
}
```

### Checkbox Types
```tsx
function TypesExample() {
  return (
    <div className="checkbox-types">
      <Checkbox type="Default">
        Default theme
      </Checkbox>
      
      {/* Use inverse for dark backgrounds */}
      <div className="dark-background">
        <Checkbox type="Inverse">
          Inverse theme
        </Checkbox>
      </div>
    </div>
  );
}
```

### Disabled and Invalid States
```tsx
function StatesExample() {
  return (
    <div className="checkbox-states">
      <Checkbox disabled>
        Disabled checkbox
      </Checkbox>
      
      <Checkbox disabled checked>
        Disabled checked
      </Checkbox>
      
      <Checkbox invalid>
        Invalid checkbox
      </Checkbox>
      
      <Checkbox required>
        Required checkbox
      </Checkbox>
    </div>
  );
}
```

### Uncontrolled Usage
```tsx
function UncontrolledExample() {
  const handleChange = (event) => {
    console.log('Checkbox changed:', event.target.checked);
  };

  return (
    <div className="uncontrolled-checkboxes">
      <Checkbox 
        defaultChecked={false}
        onChange={handleChange}
        name="newsletter"
      >
        Subscribe to newsletter
      </Checkbox>
      
      <Checkbox 
        defaultChecked={true}
        onChange={handleChange}
        name="notifications"
      >
        Enable notifications
      </Checkbox>
    </div>
  );
}
```

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

function FormExample() {
  const handleSubmit = (values, setError) => {
    if (!values.terms) {
      setError('terms', 'You must accept the terms and conditions');
      return;
    }
    
    console.log('Form submitted:', values);
  };

  return (
    <Form onSubmit={handleSubmit}>
      <FormField 
        name="terms" 
        required
        message="Please accept the terms to continue"
      >
        <Checkbox>
          I accept the <a href="/terms">terms and conditions</a>
        </Checkbox>
      </FormField>
      
      <FormField name="newsletter">
        <Checkbox>
          Subscribe to our newsletter for updates
        </Checkbox>
      </FormField>
      
      <FormField name="marketing">
        <Checkbox>
          Receive marketing communications
        </Checkbox>
      </FormField>
      
      <Button actionType="submit">
        Submit
      </Button>
    </Form>
  );
}
```

### Multi-Selection List
```tsx
function MultiSelectionExample() {
  const [selectedItems, setSelectedItems] = useState([]);
  
  const options = [
    { id: 'react', label: 'React' },
    { id: 'vue', label: 'Vue.js' },
    { id: 'angular', label: 'Angular' },
    { id: 'svelte', label: 'Svelte' }
  ];

  const handleItemToggle = (itemId, checked) => {
    setSelectedItems(prev => 
      checked 
        ? [...prev, itemId]
        : prev.filter(id => id !== itemId)
    );
  };

  return (
    <div className="multi-selection">
      <h3>Select your preferred frameworks:</h3>
      {options.map(option => (
        <Checkbox
          key={option.id}
          checked={selectedItems.includes(option.id)}
          onValueChange={(checked) => handleItemToggle(option.id, checked)}
        >
          {option.label}
        </Checkbox>
      ))}
      
      <p>Selected: {selectedItems.join(', ')}</p>
    </div>
  );
}
```

### Select All Pattern
```tsx
function SelectAllExample() {
  const [items, setItems] = useState([
    { id: 1, name: 'Item 1', selected: false },
    { id: 2, name: 'Item 2', selected: false },
    { id: 3, name: 'Item 3', selected: false },
  ]);

  const allSelected = items.every(item => item.selected);
  const someSelected = items.some(item => item.selected);

  const handleSelectAll = (checked) => {
    setItems(items.map(item => ({ ...item, selected: checked })));
  };

  const handleItemToggle = (itemId, checked) => {
    setItems(items.map(item => 
      item.id === itemId ? { ...item, selected: checked } : item
    ));
  };

  return (
    <div className="select-all-pattern">
      <Checkbox
        checked={allSelected}
        // Show indeterminate state when some but not all are selected
        ref={checkbox => {
          if (checkbox) {
            checkbox.indeterminate = someSelected && !allSelected;
          }
        }}
        onValueChange={handleSelectAll}
      >
        Select All
      </Checkbox>
      
      <hr />
      
      {items.map(item => (
        <Checkbox
          key={item.id}
          checked={item.selected}
          onValueChange={(checked) => handleItemToggle(item.id, checked)}
        >
          {item.name}
        </Checkbox>
      ))}
    </div>
  );
}
```