orio-ui 1.24.0 → 1.28.0

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

@@ -6,14 +6,19 @@ defineProps({
   max: { type: Number, required: false, default: void 0 },
   step: { type: Number, required: false, default: 1 },
   decimalPlaces: { type: Number, required: false, default: 0 },
-  disabled: { type: Boolean, required: false, default: false },
   appearance: { type: String, required: false },
   error: { type: [String, null], required: false },
   group: { type: Boolean, required: false },
   id: { type: String, required: false },
   label: { type: String, required: false },
   size: { type: String, required: false },
-  fill: { type: Boolean, required: false }
+  fill: { type: Boolean, required: false },
+  tabindex: { type: [Number, String], required: false },
+  focusKey: { type: String, required: false },
+  disabled: { type: Boolean, required: false, default: false },
+  required: { type: Boolean, required: false },
+  name: { type: String, required: false },
+  ariaLabel: { type: String, required: false }
 });
 const modelValue = defineModel({ type: Number, ...{ default: 0 } });
 const { pressAndHold, stop } = usePressAndHold();

package/dist/runtime/components/NumberInput/index.d.vue.ts

@@ -6,7 +6,6 @@ export interface NumberInputProps extends Omit<ControlProps, "layout"> {
     max?: number;
     step?: number;
     decimalPlaces?: number;
-    disabled?: boolean;
 }
 type __VLS_Props = NumberInputProps;
 declare function increase(): void;
@@ -30,7 +29,6 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {}, {
     "onUpdate:modelValue"?: ((value: number) => any) | undefined;
 }>, {
     layout: InputLayout;
-    disabled: boolean;
     step: number;
     min: number;
     max: number;

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

@@ -6,14 +6,19 @@ const props = defineProps({
   max: { type: Number, required: false, default: void 0 },
   step: { type: Number, required: false, default: 1 },
   decimalPlaces: { type: Number, required: false, default: 0 },
-  disabled: { type: Boolean, required: false, default: false },
   appearance: { type: String, required: false },
   error: { type: [String, null], required: false },
   group: { type: Boolean, required: false },
   id: { type: String, required: false },
   label: { type: String, required: false },
   size: { type: String, required: false },
-  fill: { type: Boolean, required: false }
+  fill: { type: Boolean, required: false },
+  tabindex: { type: [Number, String], required: false },
+  focusKey: { type: String, required: false },
+  disabled: { type: Boolean, required: false },
+  required: { type: Boolean, required: false },
+  name: { type: String, required: false },
+  ariaLabel: { type: String, required: false }
 });
 const { min, max, step, decimalPlaces } = toRefs(props);
 const modelValue = defineModel({ type: Number, ...{ default: 0 } });
@@ -49,7 +54,6 @@ const controlProps = computed(() => {
     max: _max,
     step: _step,
     decimalPlaces: _decimalPlaces,
-    disabled: _disabled,
     ...rest
   } = props;
   return rest;
@@ -64,19 +68,17 @@ const slotExpose = computed(() => ({
 
 <template>
   <orio-control-element
-    v-slot="{ id }"
+    v-slot="{ control }"
     v-bind="controlProps"
     :layout="layout === 'inner' ? 'vertical' : layout"
     :class="{ inner: layout === 'inner' }"
   >
     <div class="wrapper">
       <input
-        v-bind="$attrs"
-        :id
+        v-bind="{ ...$attrs, ...control }"
         v-model="modelValue"
         type="number"
         class="number-input"
-        :disabled
         :min
         :max
         :step

package/dist/runtime/components/NumberInput/index.vue.d.ts

@@ -6,7 +6,6 @@ export interface NumberInputProps extends Omit<ControlProps, "layout"> {
     max?: number;
     step?: number;
     decimalPlaces?: number;
-    disabled?: boolean;
 }
 type __VLS_Props = NumberInputProps;
 declare function increase(): void;
@@ -30,7 +29,6 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {}, {
     "onUpdate:modelValue"?: ((value: number) => any) | undefined;
 }>, {
     layout: InputLayout;
-    disabled: boolean;
     step: number;
     min: number;
     max: number;

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/RadioButton.d.vue.ts

@@ -2,8 +2,6 @@ import type { ControlProps } from "./ControlElement.vue.js";
 export interface RadioButtonProps extends ControlProps {
     /** The value this radio represents; compared to v-model to determine checked state */
     value?: unknown;
-    /** HTML name attribute — groups radios together so only one is selected at a time */
-    name?: string;
     /** Inline label text (alternative to default slot) */
     text?: string;
     /** Visually hides the label while keeping it accessible to SR (screen readers) */

package/dist/runtime/components/RadioButton.vue

@@ -2,7 +2,6 @@
 const modelValue = defineModel({ type: null });
 const props = defineProps({
   value: { type: null, required: false },
-  name: { type: String, required: false },
   text: { type: String, required: false },
   hideLabel: { type: Boolean, required: false },
   appearance: { type: String, required: false },
@@ -12,17 +11,23 @@ const props = defineProps({
   label: { type: String, required: false },
   layout: { type: String, required: false },
   size: { type: String, required: false },
-  fill: { type: Boolean, required: false }
+  fill: { type: Boolean, required: false },
+  tabindex: { type: [Number, String], required: false },
+  focusKey: { type: String, required: false },
+  disabled: { type: Boolean, required: false },
+  required: { type: Boolean, required: false },
+  name: { type: String, required: false },
+  ariaLabel: { type: String, required: false }
 });
 </script>
 
 <template>
-  <orio-control-element v-bind="props" class="radio">
+  <orio-control-element v-slot="{ control }" v-bind="props" class="radio">
     <label class="radio-label">
       <input
         v-model="modelValue"
+        v-bind="control"
         type="radio"
-        :name="name"
         :value="value"
         class="radio-input"
         tabindex="-1"

package/dist/runtime/components/RadioButton.vue.d.ts

@@ -2,8 +2,6 @@ import type { ControlProps } from "./ControlElement.vue.js";
 export interface RadioButtonProps extends ControlProps {
     /** The value this radio represents; compared to v-model to determine checked state */
     value?: unknown;
-    /** HTML name attribute — groups radios together so only one is selected at a time */
-    name?: string;
     /** Inline label text (alternative to default slot) */
     text?: string;
     /** Visually hides the label while keeping it accessible to SR (screen readers) */

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/Selector.d.vue.ts

@@ -20,6 +20,7 @@ declare const __VLS_export: <T extends object>(__VLS_props: NonNullable<Awaited<
     slots: {
         trigger?: (props: {
             toggle: any;
+            control: any;
         }) => any;
     } & {
         'trigger-content'?: (props: {

package/dist/runtime/components/Selector.vue

@@ -17,7 +17,13 @@ const props = defineProps({
   label: { type: String, required: false },
   layout: { type: String, required: false },
   size: { type: String, required: false },
-  fill: { type: Boolean, required: false }
+  fill: { type: Boolean, required: false },
+  tabindex: { type: [Number, String], required: false },
+  focusKey: { type: String, required: false },
+  disabled: { type: Boolean, required: false },
+  required: { type: Boolean, required: false },
+  name: { type: String, required: false },
+  ariaLabel: { type: String, required: false }
 });
 const { field, optionName } = toRefs(props);
 const resolvedPlaceholder = computed(
@@ -107,12 +113,12 @@ const {
 </script>
 
 <template>
-  <orio-control-element v-bind="controlProps">
+  <orio-control-element v-slot="{ control }" v-bind="controlProps">
     <orio-popover position="bottom-right" :offset="5">
       <template #default="{ toggle, isOpen }">
-        <slot name="trigger" :toggle>
+        <slot name="trigger" :toggle :control>
           <button
-            :id="props.id"
+            v-bind="control"
             type="button"
             class="selector-trigger"
             aria-haspopup="listbox"

package/dist/runtime/components/Selector.vue.d.ts

@@ -20,6 +20,7 @@ declare const __VLS_export: <T extends object>(__VLS_props: NonNullable<Awaited<
     slots: {
         trigger?: (props: {
             toggle: any;
+            control: any;
         }) => any;
     } & {
         'trigger-content'?: (props: {

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/SwitchButton.d.vue.ts

@@ -1,8 +1,5 @@
 import type { ControlProps } from "./ControlElement.vue.js";
-interface Props extends ControlProps {
-    disabled?: boolean;
-}
-type __VLS_Props = Props;
+type __VLS_Props = ControlProps;
 type __VLS_ModelProps = {
     modelValue?: boolean;
 };