# Forms

## Field

The standard wrapper for a form control. Combines `Label` + input + error message.

```tsx
import { Field } from '@theorchard/suite-components';
```

Use `Field` for every labelled form input. Do NOT manually compose `Label` + input unless you need non-standard layout.

### Example

```tsx
<Field label="Artist Name" required error="Name is required">
  <SearchInput value={name} onChange={setName} />
</Field>
```

---

## Form

Groups related form controls with consistent spacing.

```tsx
import { Form } from '@theorchard/suite-components';
```

### Example

```tsx
<Form onSubmit={handleSubmit}>
  <Field label="Title"><SearchInput /></Field>
  <Field label="Genre"><Select options={genres} /></Field>
  <Button type="submit" variant="primary">Save</Button>
</Form>
```

---

## Label

Caption for a form control with optional/required and help indicators.

```tsx
import { Label } from '@theorchard/suite-components';
```

### Key Props

| Prop | Type | Description |
|---|---|---|
| `optional` | boolean | Shows "(optional)" text |
| `helpMessage` | string | Shows a `HelpTooltip` beside the label |
| `htmlFor` | string | Links label to input by id |

---

## Checkbox

Square toggle for selecting one or more items from a set.

```tsx
import { Checkbox } from '@theorchard/suite-components';
```

### Key Props

| Prop | Type | Description |
|---|---|---|
| `checked` | boolean | Controlled checked state |
| `onChange` | function | Change handler |
| `disabled` | boolean | Disables the checkbox |
| `label` | string | Inline label text |
| `indeterminate` | boolean | Shows indeterminate (–) state |

### When to use

- Selecting multiple independent options from a list.
- Selecting all / none with an indeterminate parent state.

Do NOT use `Checkbox` for binary on/off settings — use `Switch` instead.

---

## Radio

Round toggle for selecting exactly one option from a mutually exclusive set.

```tsx
import { Radio } from '@theorchard/suite-components';
```

### When to use

- Selecting one option from a visible list of 2–6 choices.
- When all choices must be visible at once.

Do NOT use `Radio` when there are more than 6 options — use `Select` instead.

---

## Switch

Binary on/off toggle for settings.

```tsx
import { Switch } from '@theorchard/suite-components';
```

### Key Props

| Prop | Type | Description |
|---|---|---|
| `checked` | boolean | Controlled on/off state |
| `onChange` | function | Change handler |
| `disabled` | boolean | Disables the switch |
| `label` | string | Inline label |

Use `Switch` for enabling/disabling a feature. Use `Checkbox` for selecting items from a list.

---

## NumberInput

Numeric input with increment and decrement controls.

```tsx
import { NumberInput } from '@theorchard/suite-components';
```

### Key Props

| Prop | Type | Description |
|---|---|---|
| `value` | number | Controlled value |
| `onChange` | function | Change handler |
| `min` | number | Minimum value |
| `max` | number | Maximum value |
| `step` | number | Increment step |
| `disabled` | boolean | Disables the input |

---

## SearchInput

Single-line text input with a search icon for filtering or free-text search.

```tsx
import { SearchInput } from '@theorchard/suite-components';
```

### Key Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | string | — | Controlled value |
| `onChange` | function | — | Change handler |
| `placeholder` | string | — | Placeholder text |
| `onClear` | function | — | Clear button handler |
| `disabled` | boolean | — | Disables input |

---

## Slider

Range selector on a continuous scale.

```tsx
import { Slider } from '@theorchard/suite-components';
```

Use for numeric range inputs where the approximate value matters more than precision. For exact values use `NumberInput`.

---

## SegmentedInput

Visually connected group of input fields.

```tsx
import { SegmentedInput } from '@theorchard/suite-components';
```

Use when multiple inputs have a logical connection (e.g. date components, currency + amount). Replaces deprecated `InputGroup`.

---

## EditableMetadata

Inline-editable string value, toggling between display and edit mode.

```tsx
import { EditableMetadata } from '@theorchard/suite-components';
```

Use for metadata fields on detail pages where inline editing is preferred over a separate form.

---

## UploadArea

File upload area that accepts clicks or drag-and-drop.

```tsx
import { UploadArea } from '@theorchard/suite-components';
```

### Key Props

| Prop | Type | Description |
|---|---|---|
| `onDrop` | function | Called with dropped/selected files |
| `accept` | string | Accepted MIME types |
| `multiple` | boolean | Allow multiple file selection |
| `disabled` | boolean | Disables upload |

## Common Mistakes

- Do NOT use raw `<input type="text">` — use `SearchInput` or a `Field`-wrapped input.
- Do NOT use `Checkbox` for on/off settings — use `Switch`.
- Do NOT use `Radio` for more than 6 options — use `Select`.
- MUST wrap inputs in `Field` when they need labels, or in `Form` when part of a larger form.