orio-ui 1.27.0 → 1.28.1

package/dist/runtime/components/NumberInput/USAGE.md

@@ -0,0 +1,74 @@
+---
+kind: component
+category: Form inputs
+purpose: number input, numeric input, custom-control numeric stepper
+short: numeric input base with overlay controls slot; pair with Horizontal/Vertical variants for ready-made spinners
+invariants: true
+---
+
+# NumberInput — agent-only invariants
+
+`<orio-number-input>` is the **base** numeric input. By itself it renders a
+`<input type="number">` with no spinner. Custom step controls go in the
+`#controls` slot. For ready-made stepper UIs, use
+`<orio-number-input-horizontal>` or `<orio-number-input-vertical>`.
+
+## Invariants
+
+- **Extends `NumberInputProps`** (exported from this file): `ControlProps`
+  minus `layout`, plus `layout?: InputLayout`, `min`, `max`, `step`,
+  `decimalPlaces`. Same `"inner"` layout trick as Input/Textarea.
+- **v-model is `number`** (default `0`). Native input value is coerced via
+  Vue's `v-model.number` semantics.
+- **Validation runs on blur and on every increase/decrease.** Value is
+  clamped to `[min, max]` (if finite) and then rounded to `decimalPlaces`
+  via `toFixed`. Typing an out-of-range value is allowed *during* edit;
+  blur snaps it back.
+- **`decimalPlaces` defaults to `0`.** Decimal input requires both
+  `decimalPlaces` and a matching `step` (e.g. `:decimalPlaces="2" :step="0.01"`).
+- **Native webkit/firefox spin buttons are hidden** via CSS. Always
+  `appearance: textfield`.
+- **`#controls` slot overlays the input absolutely** with `pointer-events:
+  none` on the container and `:deep(button) { pointer-events: auto }`.
+  Only buttons receive clicks; the rest of the overlay passes through to
+  the input.
+- **`#controls` slot props**: `{ increase, decrease, isAtMax, isAtMin }`.
+  `increase`/`decrease` apply `step` and run validation; `isAtMax`/`isAtMin`
+  are `false` when `min`/`max` are undefined.
+- **`min`, `max`, `step`, `decimalPlaces` are stripped from `controlProps`**
+  before forwarding to ControlElement — they do not pollute the wrapper's
+  prop bag.
+- **`$attrs` is spread before `control`** on the inner `<input>`, same as
+  Input.
+
+## Gotchas
+
+- **No spinner UI without the slot or a variant.** A bare
+  `<orio-number-input v-model="n" />` renders nothing in the controls area.
+- **`min`/`max` of `0` are honored** because the check uses `Number.isFinite`,
+  not truthiness.
+- **Blur normalization rewrites the model.** Even if the user types a value
+  that is already valid, it gets re-`toFixed`d on blur — `"3"` becomes
+  `"3.00"` displayed when `decimalPlaces: 2`.
+- **Negative `step` is not blocked.** Passing `step: -1` makes increase
+  decrement.
+
+## Quick reference — custom controls slot
+
+```vue
+<template>
+  <orio-number-input v-model="quantity" :min="1" :max="99" :label="$t('cart.qty')">
+    <template #controls="{ increase, decrease, isAtMax, isAtMin }">
+      <orio-button :disabled="isAtMin" @click="decrease">−</orio-button>
+      <orio-button :disabled="isAtMax" @click="increase">+</orio-button>
+    </template>
+  </orio-number-input>
+</template>
+```
+
+## Related
+
+- `<orio-number-input-horizontal>` — pre-styled minus/plus on either side.
+- `<orio-number-input-vertical>` — pre-styled chevron stack on the right.
+- `<orio-input>` — when you want raw text, not a number.
+- Public API reference: `docs/components/number-input.md`.

package/dist/runtime/components/NumberInput/Vertical.USAGE.md

@@ -0,0 +1,55 @@
+---
+kind: component
+category: Form inputs
+purpose: number input vertical, chevron stepper, stacked-arrow numeric input
+short: number input variant with chevron up/down stacked on the right and press-and-hold repeat
+invariants: true
+---
+
+# NumberInput/Vertical — agent-only invariants
+
+`<orio-number-input-vertical>` is a pre-styled wrapper around
+`<orio-number-input>` that renders stacked chevron up/down buttons on the
+right edge. Read `NumberInput/USAGE.md` first — this variant inherits all
+of its contract.
+
+## Invariants
+
+- **Accepts the full `NumberInputProps` interface** plus a `disabled` prop
+  for the buttons. Forwarded via `v-bind="$props"`.
+- **Buttons use `usePressAndHold`** — `@mousedown` starts auto-repeat,
+  `@mouseup`/`@mouseleave` stops.
+- **Chevron up = `increase`, chevron down = `decrease`.** Standard
+  direction; do not swap them in a consumer.
+- **Buttons are stacked vertically** in a column flex (`flex-direction:
+  column; justify-content: space-around`) anchored to `right: 3px`.
+- **Input remains left-aligned** — text stays at its natural alignment;
+  only the controls move.
+
+## Gotchas
+
+- **Padding-right may need a bump on long values.** The chevron stack
+  overlaps the input's right edge. For decimal values with many digits,
+  numbers may render under the buttons. Pad the input or switch to
+  `<orio-number-input-horizontal>`.
+- **No keyboard auto-repeat.** Same limitation as the horizontal variant.
+
+## Quick reference
+
+```vue
+<template>
+  <orio-number-input-vertical
+    v-model="zoomPercent"
+    :min="10"
+    :max="400"
+    :step="5"
+    :label="$t('editor.zoom')"
+  />
+</template>
+```
+
+## Related
+
+- `<orio-number-input>` — base; use for custom controls.
+- `<orio-number-input-horizontal>` — minus/plus variant.
+- `usePressAndHold` — composable behind auto-repeat.

package/dist/runtime/components/NumberInput/Vertical.vue

@@ -31,6 +31,8 @@ const { pressAndHold, stop } = usePressAndHold();
         appearance="minimal"
         icon="chevron-up"
         variant="subdued"
+        size="xs"
+        pill
         :disabled="isAtMax || disabled"
         @mousedown="pressAndHold(increase)"
         @mouseup="stop"
@@ -40,6 +42,8 @@ const { pressAndHold, stop } = usePressAndHold();
         appearance="minimal"
         icon="chevron-down"
         variant="subdued"
+        size="xs"
+        pill
         :disabled="isAtMin || disabled"
         @mousedown="pressAndHold(decrease)"
         @mouseup="stop"
@@ -52,10 +56,14 @@ const { pressAndHold, stop } = usePressAndHold();
 <style scoped>
 .vertical :deep(.controls) {
   flex-direction: column;
-  justify-content: space-around;
+  justify-content: center;
+  gap: 0;
   right: 3px;
   left: auto;
 }
+.vertical :deep(.controls button) {
+  padding-block: 0;
+}
 .vertical :deep(.slot-wrapper) {
   line-height: 0;
 }

package/dist/runtime/components/Popover.USAGE.md

@@ -0,0 +1,103 @@
+---
+kind: component
+category: Layout & containers
+purpose: popover, anchored floating panel, dropdown menu base, contextual menu
+short: anchored floating panel teleported to body with auto-flip placement and click-outside dismissal
+invariants: true
+---
+
+# Popover — agent-only invariants
+
+`<orio-popover>` anchors a floating panel to a trigger element. The trigger
+is the default slot; the panel content is the `#content` slot.
+
+## Invariants
+
+- **Two slots, both get `{ toggle, isOpen }`.** Default slot wraps the
+  trigger; `#content` is the floating panel. You **must** call `toggle`
+  yourself — the component does not auto-attach a click handler to the
+  trigger.
+- **Panel is teleported to `<body>`**. Parent CSS scoping does not reach
+  it. Use `:deep()` from a parent, global styles, or scope the panel via
+  classes you control.
+- **`toggle(force?)`** — `toggle(true)` forces open, `toggle(false)` forces
+  close, `toggle()` flips. While `disabled` is true, all three are no-ops.
+- **`position` syntax is `main-sub`, not "diagonal".** `top-left` means
+  *above the trigger* with the panel's **right edge** aligned to the
+  trigger's right edge — NOT "above and to the left of the trigger".
+  `left-top` means *left of the trigger* with **top** edges aligned.
+  Single-word values (`"top"`, `"left"`, …) center on the cross axis.
+- **Placement auto-flips.** If the requested position doesn't fit in the
+  viewport, the component tries the opposite-main, then center variants,
+  then perpendicular axes — first fit wins. `currentPosition` is the
+  resolved value. No way to disable the fallback.
+- **`offset` is gap in px between trigger and panel.** Default `10`.
+- **Click outside closes**, with `triggerRef` in the ignore list.
+- **Reposition on scroll/resize** uses capture-phase listeners on `window`,
+  so it catches nested scrolling ancestors. Panel resizes via
+  `useElementBounding` also trigger reposition.
+- **No keyboard support.** No Esc-to-close, no focus trap, no return-focus.
+  If you need those, wire them at the consumer level on the `#content`
+  slot.
+- **No visual chrome.** The wrapper is `background: transparent; border: 0;
+  position: fixed; z-index: 999999`. The `#content` slot must render its
+  own surface (card, panel, menu).
+
+## Gotchas
+
+- **Trigger must accept the slot props.** Use `v-slot="{ toggle, isOpen }"`
+  on the default slot — without it, the trigger has no way to open the
+  popover.
+- **No arrow / caret.** Add your own pseudo-element on the content slot if
+  needed; the wrapper offers no anchor point.
+- **First-paint flicker is avoided via `visibility: hidden`** during
+  measurement, but only briefly. If your trigger animates while opening,
+  the trigger rect read on `nextTick` may be mid-animation — measure after
+  the animation, or open without animating the trigger.
+- **`appear` transition fires only on first paint.** Reopening the same
+  popover does not re-trigger `appear` — only the standard enter
+  transition. Make sure your `animate-fade-slide` styles cover both.
+- **z-index is hard-coded to `999999`.** Stacking with other body-teleports
+  (Modal at the same z-index) is order-dependent — the later-mounted
+  element wins. Mount-order is not stable across HMR.
+- **No `v-model:show`.** State is internal. Drive it through `toggle` (via
+  the slot prop) or by mounting/unmounting the component with `v-if`.
+
+## Quick reference
+
+```vue
+<template>
+  <orio-popover position="bottom-left" :offset="8">
+    <template #default="{ toggle, isOpen }">
+      <orio-button @click="toggle()">
+        Menu {{ isOpen ? "▴" : "▾" }}
+      </orio-button>
+    </template>
+
+    <template #content="{ toggle }">
+      <div class="menu-panel">
+        <button @click="onEdit(); toggle(false)">Edit</button>
+        <button @click="onDelete(); toggle(false)">Delete</button>
+      </div>
+    </template>
+  </orio-popover>
+</template>
+
+<style scoped>
+.menu-panel {
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: var(--border-radius-md);
+  padding: 0.5rem;
+  display: flex;
+  flex-direction: column;
+}
+</style>
+```
+
+## Related
+
+- `<orio-tooltip>` — for hover/focus hints; do not use Popover for tooltips.
+- `<orio-modal>` — when you need a backdrop, focus trap, and centered
+  dialog.
+- Public API reference: `docs/components/popover.md`.

package/dist/runtime/components/RadioButton.USAGE.md

@@ -0,0 +1,72 @@
+---
+kind: component
+category: Form inputs
+purpose: radio, radio button, single-choice from group
+short: single radio option wrapping ControlElement; group by sharing the same v-model
+invariants: true
+---
+
+# RadioButton — agent-only invariants
+
+`<orio-radio-button>` is one radio option. There is **no `RadioGroup`** —
+grouping is done by sharing the same v-model across multiple instances.
+
+## Invariants
+
+- **`value` is the option's payload.** It is what gets written to v-model
+  when this radio is selected. Comparison is strict (`===`).
+- **v-model is `unknown`** (typically `string` / `number` / object id) —
+  the selected value. Two `<orio-radio-button>`s with the same v-model
+  form a group; whichever value matches the model is checked.
+- **`text` prop _or_ default slot** for the inline label. Slot wins.
+  Render nothing if both are absent.
+- **`hideLabel` prop** applies `.sr-only` to the text — visually hidden,
+  still announced by screen readers. Use for icon-only radios that still
+  need an accessible name.
+- **Visual is a CSS-only rounded box** with `::after` for the inner dot
+  when checked.
+- **Native `<input type="radio">` has `tabindex="-1"`** in the template.
+  Default tab order skips it; clicking the label still toggles. If you
+  need keyboard arrow-key roving across the group, layer that on top —
+  it is not provided.
+- **No `name` HTML attribute by default.** Two browser radios with the
+  same DOM `name` form a native group; this component groups via Vue
+  v-model only. Set `name` via `$attrs` if a `<form>` submission needs
+  the radio group serialized natively.
+
+## Gotchas
+
+- **Multiple instances bound to the same v-model are not visually grouped.**
+  Layout (column / row) is up to the consumer — wrap them in a div or
+  `<orio-control-element group>` with a shared label.
+- **Object values must be the same reference** as the one stored in the
+  model. Comparing `{ id: 1 }` to a new `{ id: 1 }` is false. Bind to
+  primitive ids when possible.
+- **No "deselect" behavior.** Once a radio is selected, clicking it again
+  does not clear. To allow clearing, expose a separate "None" radio with
+  `value: null`.
+- **`required` from `ControlProps`** flows through but only takes effect
+  inside a `<form>` that calls `reportValidity`.
+
+## Quick reference
+
+```vue
+<script setup lang="ts">
+const plan = defineModel<"basic" | "pro" | "team">();
+</script>
+
+<template>
+  <orio-control-element group :label="$t('billing.plan')">
+    <orio-radio-button v-model="plan" value="basic" :text="$t('billing.basic')" />
+    <orio-radio-button v-model="plan" value="pro"   :text="$t('billing.pro')" />
+    <orio-radio-button v-model="plan" value="team"  :text="$t('billing.team')" />
+  </orio-control-element>
+</template>
+```
+
+## Related
+
+- `<orio-control-element>` (group mode) — wrap multiple radios for an
+  accessible group label.
+- `<orio-switch-button>` — boolean on/off pill button.
+- Public API reference: `docs/components/radio-button.md`.

package/dist/runtime/components/Selector.USAGE.md

@@ -0,0 +1,131 @@
+---
+kind: component
+category: Form inputs
+purpose: select, dropdown, combobox, listbox picker, single or multi-select
+short: button-triggered listbox in a popover; supports single and multi-select with string or object options
+invariants: true
+---
+
+# Selector — agent-only invariants
+
+`<orio-selector>` is a button-triggered listbox rendered inside an
+`<orio-popover>`. It is **not** a `<select>` element and **not** a
+combobox — there is no text input or filter. For free-text + filter,
+combine with `useFuzzySearch` and slot `#options-addon`. Generic over
+`T extends object`.
+
+## Invariants
+
+- **`options` accepts `string` or object items** (typed
+  `SelectableOption<T> = string | T`). Mixing is allowed but uncommon —
+  treat the array as homogenous.
+- **For object options, set `field`** (defaults to `"id"`) to the
+  uniqueness key, and **`optionName`** to the display label key. Without
+  `optionName`, objects render as `JSON.stringify(option)` — visible bug.
+- **v-model is required.** Type: `SelectableOption | SelectableOption[] |
+  null | undefined`. Single-select binds the option (or its primitive);
+  multi-select binds an array.
+- **`multiple: true` mutates the bound array in place** via
+  `modelValue.value.splice(...)` / `modelValue.value.push(...)`. The bound
+  ref must be a writable array — a deep `readonly` v-model blocks those
+  mutations: Vue warns in dev (`Set operation on key … failed: target is
+  readonly`) and fails silently in prod, so the selection won't update.
+- **Single-select closes the popover on choice**; multi-select keeps it
+  open. Wire your own close on multi-select via the `option` slot
+  `toggle` prop if needed.
+- **Built on `<orio-popover>` with `position="bottom-right"` offset 5**.
+  Same teleport/scroll/auto-flip caveats apply.
+- **Built on `<orio-list-item>` rows** with `role="option"` and
+  `aria-selected`. Listbox itself has `role="listbox"` and
+  `aria-multiselectable` when `multiple` is set.
+- **Keyboard via `useListKeyboard`**: arrow-down opens (or moves
+  highlight), Enter selects, Esc closes. `popoverToggleRef` is captured
+  lazily from the trigger slot — the first keydown after mount may
+  no-op if the popover hasn't initialized; subsequent keys work.
+- **i18n keys are required.** The component calls `useI18n()` and
+  references `selector.placeholder`, `selector.selected` ({count}), and
+  `selector.noOptions`. Consumers must have these keys in their locale
+  files.
+- **`useControlTokens(size)`** injects CSS vars (`--control-py`,
+  `--control-px`, etc.) onto the popover content — size prop on the
+  Selector flows through to dropdown padding.
+
+## Slots
+
+- `#trigger` — replaces the entire button. Receives `{ toggle, control }`.
+- `#trigger-content` — replaces the *inside* of the default button.
+  Receives `{ toggle, getOptionKey, getOptionLabel, attrs }`. Use to
+  customize the label/chevron without rebuilding the button shell.
+- `#trigger-label` — replaces only the label text. Receives same props.
+  Use to render tags for multi-select instead of "N selected".
+- `#option` — replaces each row's content. Receives `{ option, toggle,
+  selected, getOptionKey, getOptionLabel }`.
+- `#no-options` — replaces the default `<orio-empty-state>` when
+  `options.length === 0`.
+- `#options-addon` — extra content rendered **after** the list (e.g. a
+  "create new" button, a search input).
+
+## Gotchas
+
+- **No built-in search.** For filterable selectors, render an
+  `<orio-input>` in `#options-addon` and pass a filtered array to
+  `:options`.
+- **Multi-select trigger shows "N selected" by default.** Override via
+  `#trigger-label` to render tags — consider `<orio-tag>` chips. Removal
+  must call `toggleOption` (exposed via `#option` slot, not the trigger).
+- **String options bypass `field`/`optionName`.** Selection equality is
+  `===`. Object options compare via `field`.
+- **`placeholder` falls back to `t("selector.placeholder")`**. Pass an
+  explicit `placeholder` to override per-instance; do not assume English.
+- **`controlProps` strip is exhaustive** — `options`, `multiple`,
+  `field`, `optionName`, `placeholder` never reach the ControlElement
+  wrapper. Adding new selector-specific props requires adding them to the
+  strip list.
+- **Trigger is a `<button>`**, not a real `<select>`. Form serialization
+  and native submission do not include the value — handle submit
+  manually.
+
+## Quick reference — single-select with object options
+
+```vue
+<script setup lang="ts">
+interface Country { id: string; name: string }
+const countries: Country[] = [
+  { id: "uk", name: "United Kingdom" },
+  { id: "fi", name: "Finland" },
+];
+const country = defineModel<Country | null>({ default: null });
+</script>
+
+<template>
+  <orio-selector
+    v-model="country"
+    :options="countries"
+    field="id"
+    option-name="name"
+    :label="$t('settings.country')"
+  />
+</template>
+```
+
+## Quick reference — multi-select with tag chips
+
+```vue
+<template>
+  <orio-selector v-model="tags" :options="allTags" multiple field="id" option-name="label">
+    <template #trigger-label>
+      <orio-tag v-for="tag in tags" :key="tag.id" removable @remove="removeTag(tag)">
+        {{ tag.label }}
+      </orio-tag>
+    </template>
+  </orio-selector>
+</template>
+```
+
+## Related
+
+- `<orio-taggable-selector>` — pre-built multi-select with tag chips.
+- `<orio-list-item>` — the row primitive used inside the listbox.
+- `useListKeyboard` — keyboard nav composable.
+- `useFuzzySearch` — pair with `#options-addon` for a search filter.
+- Public API reference: `docs/components/selector.md`.

package/dist/runtime/components/SwitchButton.USAGE.md

@@ -0,0 +1,62 @@
+---
+kind: component
+category: Form inputs
+purpose: toggle, on/off switch, pill toggle, boolean button
+short: boolean on/off pill button (not a sliding switch) wrapping ControlElement; click/Enter/Space toggle
+invariants: true
+---
+
+# SwitchButton — agent-only invariants
+
+`<orio-switch-button>` is a **pill-shaped button** that toggles a boolean.
+Despite the name it is **not** a sliding toggle switch — it is a chip-style
+button that flips between active and inactive states.
+
+## Invariants
+
+- **Renders a `<button type=...>` element**, not a checkbox or sliding
+  knob. The "switch" is purely visual state via the `.active` class.
+- **v-model is `boolean`** (not required — renders as off when unbound).
+- **Click, Enter, and Space all toggle.** `Enter` and `Space` use
+  `.prevent` to avoid form submit / page scroll.
+- **`disabled` blocks toggling** and applies `.disabled` styles (0.5
+  opacity, `cursor: not-allowed`). Keyboard activation is also gated.
+- **Default slot is the button content** (label, icon, or both). Visual
+  active state changes background/border/color; the slot does not
+  receive any reactive prop.
+- **Wraps `<orio-control-element>`** — supports the standard `label`,
+  `error`, `layout`, `size`, etc. The control bag is spread on the
+  inner `<button>` along with `$attrs`.
+
+## Gotchas
+
+- **The component name is misleading.** If you want a sliding toggle
+  switch (knob that animates), this is not it. Build that yourself or
+  pick another primitive.
+- **No `aria-pressed`.** The active state is visual only. For correct
+  screen reader semantics, pass `:aria-pressed="modelValue"` via
+  `$attrs`.
+- **`@keydown.enter.prevent`** swallows form-submit Enter inside a
+  `<form>`. If the SwitchButton is inside a form, Enter on it will
+  toggle but not submit.
+
+## Quick reference
+
+```vue
+<template>
+  <orio-switch-button
+    v-model="notifications"
+    :label="$t('settings.notifications')"
+    :aria-pressed="notifications"
+  >
+    <orio-icon :name="notifications ? 'bell' : 'bell-off'" />
+    {{ notifications ? $t("common.on") : $t("common.off") }}
+  </orio-switch-button>
+</template>
+```
+
+## Related
+
+- `<orio-check-box>` — when you want a real checkbox.
+- `<orio-radio-button>` — single-choice from a group.
+- Public API reference: `docs/components/switch-button.md`.

package/dist/runtime/components/Tag.USAGE.md

@@ -0,0 +1,51 @@
+---
+kind: component
+category: Buttons & indicators
+purpose: tag, chip, label, removable chip, category pill
+short: small text chip with neutral or accent variant; static display only (no remove behavior)
+invariants: true
+---
+
+# Tag — agent-only invariants
+
+`<orio-tag>` is a static text chip. No close button, no click handler, no
+removal behavior — display only.
+
+## Invariants
+
+- **`text` is required.** It is the only way to set the chip's visible
+  content — there is no default slot.
+- **`variant`**: `"neutral"` (default, gray) or `"accent"` (themed
+  accent). No `danger` / `alert` colors here — use `<orio-badge>` for
+  that.
+- **`id` is an optional uniqueness key** used by upstream components
+  (`<orio-taggable-selector>`) to match selected tags. Pass it whenever
+  the tag participates in selection state.
+- **`user-select: none`** — text inside the chip cannot be selected with
+  the cursor.
+
+## Gotchas
+
+- **No remove / close button.** The `TagProps` shape is intentionally
+  passive. For removable chips, wrap a custom button next to it or build
+  your own primitive.
+- **No icon support.** No `icon` prop, no slot. For icon+text chips,
+  build directly from a `<span>` with `<orio-icon>`.
+- **No size variants.** Padding (`0.25rem 0.6rem`) and font size
+  (`--font-sm`) are fixed.
+
+## Quick reference
+
+```vue
+<template>
+  <orio-tag :text="$t('category.urgent')" variant="accent" />
+  <orio-tag :text="$t('category.draft')" />
+</template>
+```
+
+## Related
+
+- `<orio-taggable-selector>` — uses `TagProps` as its option shape.
+- `<orio-badge>` — when you need a status pill with semantic color
+  variants.
+- Public API reference: `docs/components/tag.md`.

package/dist/runtime/components/TaggableSelector.USAGE.md

@@ -0,0 +1,73 @@
+---
+kind: component
+category: Form inputs
+purpose: multi-select with tag chips, taggable selector, chip picker
+short: multi-select Selector that renders chosen options as tag chips in the trigger
+invariants: true
+---
+
+# TaggableSelector — agent-only invariants
+
+`<orio-taggable-selector>` is a thin wrapper over `<orio-selector>` that
+forces `multiple` mode and renders the selection as a row of `<orio-tag>`
+chips inside the trigger. Read `Selector.USAGE.md` for the full contract.
+
+## Invariants
+
+- **Always multi-select.** The internal `<orio-selector>` is passed
+  `multiple` unconditionally; the prop cannot be turned off.
+- **`optionName` defaults to `"text"`** to align with `TagProps.text`. If
+  your option type uses a different label key, pass `option-name`.
+- **v-model type is `TagProps[]`** — `{ id?: string; text: string;
+  variant?: "neutral" | "accent" }[]`. Options must be tag-shaped or
+  augmented to satisfy this contract.
+- **Tags in the trigger are display-only.** Clicking a chip does **not**
+  remove the option. The user must reopen the dropdown and uncheck it.
+  This is a real usability tradeoff — for click-to-remove, fall back to
+  `<orio-selector>` with a custom `#trigger-label`.
+- **Trigger lays chips out as `flex-wrap`** with `0.5rem` gap, left-aligned.
+  Selecting many chips grows the trigger height; constrain it if your
+  layout depends on a fixed height.
+
+## Gotchas
+
+- **`field` (uniqueness key) still defaults to `"id"`** from the underlying
+  Selector. Each tag should have a stable `id` — without one, multi-select
+  add/remove will mis-match items with identical `text`.
+- **No empty-state placeholder by default in the trigger.** When the
+  selection is empty, the trigger is empty space. Pass a `placeholder` so
+  the dropdown shows a hint, but the trigger label itself will not show
+  it (the `#trigger-label` slot renders an empty chip list).
+- **Variant per chip is per-option.** Set `variant: "accent"` on individual
+  option objects to tint specific chips.
+
+## Quick reference
+
+```vue
+<script setup lang="ts">
+import type { TagProps } from "../components/Tag.vue";
+
+const allCategories: TagProps[] = [
+  { id: "fiction", text: "Fiction" },
+  { id: "non-fiction", text: "Non-fiction", variant: "accent" },
+  { id: "poetry", text: "Poetry" },
+];
+
+const selected = defineModel<TagProps[]>({ default: () => [] });
+</script>
+
+<template>
+  <orio-taggable-selector
+    v-model="selected"
+    :options="allCategories"
+    :label="$t('book.categories')"
+  />
+</template>
+```
+
+## Related
+
+- `<orio-selector>` — base; use with custom `#trigger-label` for
+  removable chips or different layouts.
+- `<orio-tag>` — the chip primitive rendered in the trigger.
+- Public API reference: `docs/components/taggable-selector.md`.