# Choice

A single-select card — the model offers options, the user picks one and hits Submit, your app receives a typed action event.

<p class="kai-tag-sub">kai-choice</p>

A "pick one of N" card — set the options in JavaScript, the user chooses one, and your app receives a typed `kai-card` action event.

## Preview

> **tip:** 
Use `<kai-choice>` when the model needs the user to pick exactly one option before proceeding — plan selection, tone preference, next-step branching. Drop it standalone or let `<kai-cards>` dispatch it from a stream. Use `<kai-confirm>` for yes/no, `<kai-form>` for multi-field input.

## Usage

Set `data` in JavaScript (it's an object) and listen for the `kai-card` CustomEvent:

```html
<kai-choice id="ch" heading="Choose a plan"></kai-choice>

<script type="module">

  await customElements.whenDefined('kai-choice');

  const el = document.getElementById('ch');

  el.data = {
    prompt: 'Which plan fits your team?',
    options: [
      { id: 'free',  label: 'Free',     meta: '$0' },
      { id: 'pro',   label: 'Pro',      meta: '$12/seat', recommended: true },
      { id: 'biz',   label: 'Business', meta: '$29/seat' },
    ],
  };

  el.addEventListener('kai-card', (e) => {
    const ev = e.detail; // CardEvent
    if (ev.kind === 'action') console.log('chose:', ev.action, ev.payload);
  });
</script>
```

- **`data`** — required fields per option: `id` and `label`. Optional: `description`, `meta`, `recommended`, `media` + `imageAlt`, `disabled`, `payload`.
- **`allowOther`** appends an "Other…" row revealing an inline text input; submits as `action: '__other__'` with `payload: { text }`.
- **After submit** the card renders read-only. Restore a resolved state on reload via `el.resolution = { kind: 'action', action: 'option-id' }`.

## Examples

### Plans with Pricing

### Rows with Images

### Quick Replies with Free-Text Escape

`allowOther` appends an "Other…" row that reveals an inline text field when selected.

### Resolved (Read-only)

Pre-render the post-submit view — useful for restoring persisted choices on reload.

### Error State

A malformed definition (empty `options`) triggers the inline error view and emits `{ kind: 'error' }`.

## Props

## Methods

## Composed from