@ryanhelsing/ry-ui/docs/components/forms.md

Framework-agnostic, Light DOM web components. CSS is the source of truth.

# Form Components

## `<ry-field>`

Wraps native `<input>` / `<textarea>` / `<select>` with auto-generated label, error, and hint. Handles accessibility linking (aria-describedby, aria-invalid) automatically.

| Attribute | Values | Description |
|-----------|--------|-------------|
| `label` | string | Label text |
| `error` | string | Error message (hides hint when set) |
| `hint` | string | Helper text shown below input |

```html
<ry-field label="Email" hint="We'll never share your email">
  <input type="email" placeholder="you@example.com">
</ry-field>

<ry-field label="Password" error="Must be at least 8 characters">
  <input type="password">
</ry-field>

<!-- Setting error="" clears the error and shows hint again -->
```

## `<ry-select>`

| Attribute | Values | Description |
|-----------|--------|-------------|
| `placeholder` | string | Placeholder text |
| `name` | string | Form field name |

Events: `ry:change` — `e.detail.value`, `e.detail.label`
API: `.value`, `.open()`, `.close()`

```html
<ry-select placeholder="Country" name="country">
  <ry-option value="us">United States</ry-option>
  <ry-option value="uk">United Kingdom</ry-option>
</ry-select>
```

JS:
```js
const select = document.querySelector('ry-select');
select.addEventListener('ry:change', (e) => {
  console.log(e.detail.value); // "us"
  console.log(e.detail.label); // "United States"
});
select.value = 'uk';
```

## `<ry-switch>`

| Attribute | Values | Description |
|-----------|--------|-------------|
| `name` | string | Form field name |
| `checked` | boolean | Initially on |
| `disabled` | boolean | Disable |

Events: `ry:change` — detail shape:

| Property | Type   | Example   | Description |
|----------|--------|-----------|-------------|
| `value`  | string | `"true"`  | `"true"` or `"false"` (string, not boolean — `"false"` is truthy in JS!) |
| `label`  | string | `"on"`    | `"on"` or `"off"` |

API: `.checked` (boolean)

```html
<ry-switch name="notifications" checked>Email notifications</ry-switch>
```

JS:
```js
const sw = document.querySelector('ry-switch');
sw.addEventListener('ry:change', (e) => {
  const isOn = e.detail.value === 'true'; // compare string, not boolean
  console.log(isOn, e.detail.label);      // true, "on"
});
sw.checked = false;
```

## Checkbox & Radio

Standard HTML, auto-styled by ry-ui theme. No custom elements needed.

```html
<ry-stack gap="sm">
  <label><input type="checkbox" checked> Accept terms</label>
  <label><input type="checkbox"> Newsletter</label>
</ry-stack>

<ry-stack gap="sm">
  <label><input type="radio" name="plan" value="free" checked> Free</label>
  <label><input type="radio" name="plan" value="pro"> Pro</label>
</ry-stack>
```