# SilkeToggle

A switch component for toggling boolean values on and off. Use toggles for settings that take effect immediately without requiring a save action.

## Features

- **On/Off states**: Clear visual feedback for boolean values
- **Label support**: Display label and help text
- **Size variants**: Normal and small sizes
- **Form integration**: Works with SilkeForm
- **Invert mode**: Flip the visual state
- **Validation**: Built-in required validation

## Basic Usage

```js
const [enabled, setEnabled] = React.useState(false);

<SilkeToggle value={enabled} onChange={setEnabled} />;
```

## With Label

```js
const [enabled, setEnabled] = React.useState(true);

<SilkeToggle label="Enable notifications" value={enabled} onChange={setEnabled} />;
```

## With Help Text

Provide additional context with the `help` prop:

```js
const [enabled, setEnabled] = React.useState(false);

<SilkeToggle
  label="Dark mode"
  help="Enable dark theme for the application"
  value={enabled}
  onChange={setEnabled}
/>;
```

## States

```js
const [on, setOn] = React.useState(true);
const [off, setOff] = React.useState(false);

<SilkeBox column gap="s">
  <SilkeToggle label="Toggle ON" value={on} onChange={setOn} />
  <SilkeToggle label="Toggle OFF" value={off} onChange={setOff} />
</SilkeBox>;
```

## Size Variants

Use `small` for a compact toggle:

```js
const [normal, setNormal] = React.useState(true);
const [small, setSmall] = React.useState(true);

<SilkeBox column gap="m">
  <SilkeToggle label="Normal size toggle" value={normal} onChange={setNormal} />
  <SilkeToggle small label="Small size toggle" value={small} onChange={setSmall} />
</SilkeBox>;
```

## Disabled State

```js
<SilkeBox column gap="s">
  <SilkeToggle disabled label="Disabled (ON)" value={true} onChange={() => {}} />
  <SilkeToggle disabled label="Disabled (OFF)" value={false} onChange={() => {}} />
  <SilkeToggle disabled small label="Disabled small (ON)" value={true} onChange={() => {}} />
  <SilkeToggle disabled small label="Disabled small (OFF)" value={false} onChange={() => {}} />
</SilkeBox>
```

## Required Validation

Show error when required toggle is off:

```js
const [agreed, setAgreed] = React.useState(false);

<SilkeBox column gap="s">
  <SilkeToggle required label="I agree to the terms" value={agreed} onChange={setAgreed} />
  <SilkeText size="s" color={agreed ? 'success-50' : 'error-50'}>
    {agreed ? 'Thank you for agreeing' : 'You must agree to continue'}
  </SilkeText>
</SilkeBox>;
```

## Inverted Mode

Use `invert` to flip the visual state (toggle appears ON when value is false):

```js
const [disabled, setDisabled] = React.useState(false);

<SilkeBox column gap="s">
  <SilkeToggle invert label="Disable feature" help="When on, this feature is disabled" value={disabled} onChange={setDisabled} />
  <SilkeText size="s">Feature is: {disabled ? 'DISABLED' : 'ENABLED'}</SilkeText>
</SilkeBox>;
```

## Form Integration

Use within SilkeForm:

```js
const [settings, setSettings] = React.useState({
  notifications: true,
  autoSave: false,
  darkMode: false,
});

<SilkeForm value={settings} onChange={setSettings}>
  <SilkeBox column gap="m">
    <SilkeToggle name="notifications" label="Push notifications" />
    <SilkeToggle name="autoSave" label="Auto-save" help="Automatically save changes" />
    <SilkeToggle name="darkMode" label="Dark mode" />
  </SilkeBox>
</SilkeForm>;
```

## Settings Panel Example

```js
const [settings, setSettings] = React.useState({
  emailNotifications: true,
  smsNotifications: false,
  marketingEmails: false,
  twoFactor: true,
});

<SilkeBox column gap="m" style={{ maxWidth: 400 }}>
  <SilkeText kind="title" size="s">Notification Settings</SilkeText>
  <SilkeToggle
    label="Email notifications"
    help="Receive updates via email"
    value={settings.emailNotifications}
    onChange={(v) => setSettings({ ...settings, emailNotifications: v })}
  />
  <SilkeToggle
    label="SMS notifications"
    help="Receive updates via text message"
    value={settings.smsNotifications}
    onChange={(v) => setSettings({ ...settings, smsNotifications: v })}
  />
  <SilkeDivider space="s" />
  <SilkeText kind="title" size="s">Security</SilkeText>
  <SilkeToggle
    label="Two-factor authentication"
    help="Require code when signing in"
    value={settings.twoFactor}
    onChange={(v) => setSettings({ ...settings, twoFactor: v })}
  />
</SilkeBox>;
```

## Props

| Prop       | Type                       | Default | Description                              |
| ---------- | -------------------------- | ------- | ---------------------------------------- |
| `value`    | `boolean`                  | -       | Current toggle state                     |
| `onChange` | `(value: boolean) => void` | -       | Called when toggle is switched           |
| `label`    | `string`                   | -       | Label text                               |
| `help`     | `React.ReactNode`          | -       | Help text displayed below label          |
| `name`     | `string`                   | -       | Field name for form integration          |
| `small`    | `boolean`                  | `false` | Use smaller toggle size                  |
| `disabled` | `boolean`                  | `false` | Disable the toggle                       |
| `readOnly` | `boolean`                  | `false` | Prevent changes                          |
| `required` | `boolean`                  | `false` | Mark as required (shows error if false)  |
| `invert`   | `boolean`                  | `false` | Invert visual state (ON when false)      |
| `error`    | `string`                   | -       | Error message to display                 |

Also accepts standard HTML input attributes and form field props.