orio-ui 1.24.0 → 1.28.0

package/dist/runtime/components/SwitchButton.vue

@@ -1,6 +1,5 @@
 <script setup>
 const props = defineProps({
-  disabled: { type: Boolean, required: false, default: false },
   appearance: { type: String, required: false },
   error: { type: [String, null], required: false },
   group: { type: Boolean, required: false },
@@ -8,7 +7,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, default: false },
+  required: { type: Boolean, required: false },
+  name: { type: String, required: false },
+  ariaLabel: { type: String, required: false }
 });
 const modelValue = defineModel({ type: Boolean, ...{ required: false } });
 function toggle() {
@@ -18,13 +23,11 @@ function toggle() {
 </script>
 
 <template>
-  <orio-control-element v-slot="{ id }" v-bind="props">
+  <orio-control-element v-slot="{ control }" v-bind="props">
     <button
-      :id
-      v-bind="$attrs"
+      v-bind="{ ...$attrs, ...control }"
       class="switch-button"
-      :class="{ active: modelValue, disabled }"
-      :disabled="disabled"
+      :class="{ active: modelValue, disabled: props.disabled }"
       @click="toggle"
       @keydown.enter.prevent="toggle"
       @keydown.space.prevent="toggle"

package/dist/runtime/components/SwitchButton.vue.d.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;
 };

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`.

package/dist/runtime/components/TaggableSelector.vue

@@ -12,7 +12,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 modelValue = defineModel({ type: Array });
 </script>

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

@@ -0,0 +1,72 @@
+---
+kind: component
+category: Form inputs
+purpose: textarea, multi-line text, long text input
+short: multi-line text input wrapping ControlElement; supports inner-floating label and vertical resize
+invariants: true
+---
+
+# Textarea — agent-only invariants
+
+`<orio-textarea>` is the multi-line counterpart to `<orio-input>`. Same
+ControlElement wrapping, same layout modes, same slot-bag flow. Read
+`ControlElement.USAGE.md` and `Input.USAGE.md` first — most of the contract
+lives there.
+
+## Invariants
+
+- **Extends `ControlProps`** with one override: `layout?: InputLayout`
+  where `InputLayout = ControlLayout | "inner"`. The `"inner"` mode floats
+  the label inside the textarea chrome (same trick as Input).
+- **`layout="inner"` translates to `vertical`** on the inner ControlElement
+  and adds an `.inner` class. The label reposition is driven by `:deep()`
+  styles, not a duplicate label DOM.
+- **v-model is `string`** (default `""`).
+- **`rows="4"` is the hard default** rendered on the `<textarea>`. Override
+  via `$attrs` — `<orio-textarea :rows="2">` flows through.
+- **`resize: vertical`** is set in CSS. The user can drag the bottom edge
+  but cannot resize horizontally.
+- **Horizontal layout aligns the label to the top.** When `layout="horizontal"`,
+  the `.control-label` is padded with `--control-py` and the row uses
+  `align-items: flex-start` — so the label sits next to the top of a tall
+  textarea, not centered vertically.
+- **`$attrs` is spread before the control bag** on the inner `<textarea>`:
+  `v-bind="{ ...$attrs, ...control }"`. Native attrs (`placeholder`,
+  `maxlength`, `rows`, `wrap`) work on `<orio-textarea>` and reach the
+  underlying element.
+
+## Gotchas
+
+- **Resize handle ignores `layout="inner"`.** The drag handle still appears
+  bottom-right — the inner label can overlap an aggressively resized
+  textarea's content. Cap `max-height` if that matters.
+- **`rows` only sets the initial height** (in line-heights). After the
+  user resizes, the manual height wins. To reset, re-mount the component.
+- **The textarea is `width: 100%`** of the slot wrapper, which itself
+  follows the wrapper border. Setting `cols` has no effect on rendered
+  width.
+
+## Quick reference
+
+```vue
+<script setup lang="ts">
+const note = defineModel<string>({ default: "" });
+</script>
+
+<template>
+  <orio-textarea
+    v-model="note"
+    :label="$t('order.notes.label')"
+    :placeholder="$t('order.notes.placeholder')"
+    layout="inner"
+    :rows="6"
+    maxlength="500"
+  />
+</template>
+```
+
+## Related
+
+- `<orio-input>` — single-line text. Same contract.
+- `<orio-control-element>` — the wrapper; owns label/error/a11y.
+- Public API reference: `docs/components/textarea.md`.

package/dist/runtime/components/Textarea.vue

@@ -8,18 +8,28 @@ const props = defineProps({
   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 }
 });
 </script>
 
 <template>
   <orio-control-element
-    v-slot="{ id }"
+    v-slot="{ control }"
     v-bind="props"
     :layout="layout === 'inner' ? 'vertical' : layout"
     :class="{ inner: layout === 'inner' }"
   >
-    <textarea :id v-model="modelValue" rows="4" v-bind="$attrs" />
+    <textarea
+      v-model="modelValue"
+      rows="4"
+      v-bind="{ ...$attrs, ...control }"
+    />
   </orio-control-element>
 </template>
 

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

@@ -0,0 +1,84 @@
+---
+kind: component
+category: Layout & containers
+purpose: tooltip, hover hint, focus hint, label-on-hover
+short: hover/focus-triggered tooltip teleported to body, with delay, arrow, and four placements
+invariants: true
+---
+
+# Tooltip — agent-only invariants
+
+`<orio-tooltip>` wraps a trigger in an `inline-flex` div and shows a small
+floating bubble on hover or focus. It is not for click-driven menus — use
+`<orio-popover>` for that.
+
+## Invariants
+
+- **Trigger wrapper is `display: inline-flex`** (centered). The slot lives
+  inside it. Block-level children are coerced into the flex layout.
+- **Mouse + keyboard both trigger.** `@mouseenter`/`@focus` show,
+  `@mouseleave`/`@blur` hide. Touch is not supported.
+- **`delay` (default 500 ms) gates open only.** Hide is immediate. Setting
+  `delay: 0` makes it instant.
+- **`disabled` watcher closes an open tooltip.** Flipping to disabled mid-
+  display hides it. Re-enabling does not reopen — the user has to re-hover.
+- **Two content sources, slot wins.** `#content` slot renders if provided,
+  otherwise the `text` prop. Both being empty renders an empty bubble.
+- **Teleported to body only while visible.** Unlike Popover, the tooltip is
+  mounted/unmounted around the visible window — no leftover DOM at rest.
+- **No placement fallback.** `placement` (`top`/`bottom`/`left`/`right`) is
+  honored as-is. If the bubble overflows the viewport, it stays offscreen.
+  Compare with Popover, which auto-flips.
+- **Position is recalculated on scroll/resize** while visible (capture-phase
+  listeners catch nested scrollers).
+- **`pointer-events: none` on the bubble.** It never intercepts the cursor —
+  so leaving the trigger always closes it.
+- **Has a CSS-triangle arrow** (`.orio-tooltip-arrow-{placement}`) anchored
+  on the appropriate edge.
+- **Styles are intentionally unscoped** in the second `<style>` block,
+  because teleported nodes escape scoped CSS. Class names use the
+  `orio-tooltip-` prefix to avoid collisions. Consumers **can** override
+  them globally — useful for theming, dangerous if not namespaced.
+- **`white-space: nowrap`** on the bubble. Long `text` does not wrap. For
+  multi-line, render `#content` with your own line-breaking CSS.
+- **A11y is partial.** The bubble has `role="tooltip"` and `aria-hidden`,
+  but the trigger does **not** receive `aria-describedby`. Screen readers
+  may not announce the tooltip. Wire `aria-describedby` on the trigger
+  child yourself if it matters.
+
+## Gotchas
+
+- **`text` defaults to English.** Project convention: pass an i18n key —
+  `:text="$t('action.delete.hint')"`.
+- **`inline-flex` wrapper can change layout.** Wrapping a block-level
+  element (a card, a list row) in a Tooltip squashes it. Wrap a smaller
+  trigger (button, icon) instead.
+- **`delay` does not debounce reopens.** Rapid hover toggles can still
+  flash the tooltip on the second mount if the first delay completed.
+- **Z-index is `9999`** on the bubble — less than Popover (`999999`) and
+  Modal. Tooltips above an open popover may render behind it.
+- **No click-to-dismiss.** Clicking the trigger does not close the bubble.
+  The user has to move focus or hover away.
+
+## Quick reference
+
+```vue
+<template>
+  <orio-tooltip :text="$t('action.delete.hint')" placement="top" :delay="200">
+    <orio-button icon-only icon="trash" @click="onDelete" />
+  </orio-tooltip>
+
+  <orio-tooltip placement="right">
+    <span>Hover me</span>
+    <template #content>
+      <strong>Custom</strong> content with <em>markup</em>.
+    </template>
+  </orio-tooltip>
+</template>
+```
+
+## Related
+
+- `<orio-popover>` — click-driven anchored panel; do not reach for Tooltip
+  for menus.
+- Public API reference: `docs/components/tooltip.md`.

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

@@ -0,0 +1,108 @@
+---
+kind: component
+category: Layout & containers
+purpose: pinch/scroll zoom viewport, pan-zoom canvas, infinite board, image inspector
+short: pan + pinch/wheel zoom viewport with inertia, momentum, space-to-grab and bounds clamping
+invariants: true
+---
+
+# ZoomableContainer — agent-only invariants
+
+`<orio-zoomable-container>` is a pan-zoom viewport that transforms a "world"
+(its slot) inside a fixed-size viewport. Pinch on touch, ctrl/cmd+wheel on
+mouse, drag-to-pan with space-or-middle-button.
+
+## Invariants
+
+- **Viewport sizes to its parent.** The viewport is `width: 100%; height:
+  100%`. **A parent with explicit dimensions is required** — without it,
+  the viewport collapses to 0 and nothing is visible.
+- **World is the slot.** It is `position: absolute; transform-origin: 0 0`.
+  The container measures it via `ResizeObserver`, so the slot can be any
+  size — fixed, content-driven, or dynamic.
+- **First-mount auto-center is one-shot.** Once viewport and world both
+  have non-zero dimensions, the world centers exactly once. Later size
+  changes call `applyBounds` only — they do **not** re-center. Use the
+  exposed `centerWorld()` to re-center on demand.
+- **Drag-to-pan needs space, middle button, OR clicking the viewport background.**
+  Pointer-down on slot content does **not** pan by default. Hold `Space`
+  (cursor becomes `grab`/`grabbing`) or click an area outside the world to
+  pan. This is `shouldPan(e)` — confirm interactive children inside the
+  slot stop propagation if needed.
+- **Touch gestures use `usePinchZoom`**, mouse/pen uses pointer-capture
+  drag. Wheel does pan; **ctrl/cmd + wheel** zooms at cursor; **shift +
+  vertical wheel** pans horizontally.
+- **`v-model:scale` works; `v-model:translate` does NOT.** `update:scale`
+  emits one value, but `update:translate` emits `(x, y)` as two args — not
+  a tuple. Bind a callback to read translate, or read it via `ref` on the
+  exposed `tx`/`ty`.
+- **Exposed methods (via `defineExpose`)**: `scale`, `tx`, `ty`,
+  `setScaleAt(target, px, py)`, `panBy(dx, dy)`, `resetView()`,
+  `centerWorld()`. Get a `ref` on the component to call them.
+- **Pan bounds let the world drift halfway off either edge.** Clamp is
+  `tx ∈ [vw/2 − worldW, vw/2]`, so the world can move until its trailing
+  edge reaches viewport center. Intentional — keeps something always
+  reachable.
+- **`touch-action: none` and `user-select: none`** are set on the viewport.
+  Children inside cannot select text or trigger native touch scrolling.
+- **Context menu is suppressed** inside the viewport (`@contextmenu.prevent`).
+- **Global keydown listener for Space.** `useEventListener("keydown", ...)`
+  binds to `document`, so holding space in a text input elsewhere on the
+  page still flips `spaceHeld` — be aware when composing with form inputs.
+
+## Gotchas
+
+- **Slot prop shape**: `<template v-slot="{ scale, tx, ty }">`. Use these
+  for overlays that need to track the world transform (rulers, minimaps).
+- **No `v-model:translate` shortcut.** Wire it as
+  `@update:translate="(x, y) => { ... }"`.
+- **Pinch zoom resets `dragId` on `onPinchStart`** to cancel any in-flight
+  single-pointer drag. If you mix touch + pen on a hybrid device, the drag
+  state can drop mid-gesture.
+- **`zoomSpeed` is exponential**, not linear. `factor = exp(-deltaY *
+  zoomSpeed)`. Default `0.0015` is tuned for typical mousewheel deltas;
+  trackpad wheel events with tiny deltas barely zoom — bump to ~0.005 if
+  your audience is trackpad-heavy.
+- **`minScale` / `maxScale` are clamped, not normalized.** Setting
+  `initialScale` outside the range still applies the clamp on the first
+  zoom interaction.
+
+## Quick reference
+
+```vue
+<script setup lang="ts">
+import { ref, useTemplateRef } from "vue";
+
+const board = useTemplateRef<{ resetView: () => void; centerWorld: () => void }>("board");
+const scale = ref(1);
+const translate = ref({ x: 0, y: 0 });
+</script>
+
+<template>
+  <div style="width: 100%; height: 80vh">
+    <orio-zoomable-container
+      ref="board"
+      v-model:scale="scale"
+      :min-scale="0.25"
+      :max-scale="4"
+      @update:translate="(x, y) => (translate = { x, y })"
+    >
+      <template #default="{ scale: worldScale }">
+        <div class="board-world" :style="{ width: '2000px', height: '1500px' }">
+          <p>Zoom: {{ worldScale.toFixed(2) }}×</p>
+        </div>
+      </template>
+    </orio-zoomable-container>
+  </div>
+
+  <orio-button @click="board?.resetView()">Reset</orio-button>
+</template>
+```
+
+## Related
+
+- `usePinchZoom` — pinch gesture composable used internally.
+- `useInertia` — momentum/decay used for release-after-drag.
+- `<orio-canvas>` — when you need a tool-driven editor, not just a pan-zoom
+  viewport. Canvas is built on the same gestures with extras.
+- Public API reference: `docs/components/zoomable-container.md`.

package/dist/runtime/components/date/Picker.USAGE.md

@@ -0,0 +1,52 @@
+---
+kind: component
+category: Date
+purpose: date input, single date picker, "pick a date"
+short: single date picker built from Calendar plus PickerTrigger
+invariants: true
+---
+
+# date/Picker — agent-only invariants
+
+`<orio-date-picker>` is the single-date picker: a `<orio-date-picker-trigger>`
+button that opens a popover containing `<orio-calendar>`. For ranges use
+`<orio-date-range-picker>`.
+
+## Invariants
+
+- **Extends `ControlProps`.** Pass `label`, `error`, `size`, `disabled`,
+  `required` straight through — they reach the trigger via ControlElement.
+  See `ControlElement.USAGE.md`.
+- **v-model is `string | null`** in ISO `YYYY-MM-DD` form. `null` means
+  unpicked.
+- **`min` / `max`** are ISO strings. They merge with the consumer's
+  `isDisabled(iso)` callback — Picker's `calendarIsDisabled` returns true
+  when either the min/max bound is violated OR the consumer says so.
+- **Selecting a day closes the popover** automatically (`toggle(false)` is
+  called inside the `@select` handler). Do not wire your own close.
+- **Markers + getMarker** are forwarded to the inner Calendar unchanged.
+  See `Calendar.USAGE.md` for the matching rules.
+- **Placeholder text** falls back to the i18n key `datePicker.placeholder`
+  if no `placeholder` prop is given.
+
+## Gotchas
+
+- The trigger displays the date via `formatDate(value, locale)` from
+  `../../utils/date`. If you need a custom display format, wrap the
+  picker — the prop is not exposed.
+- `<orio-date-picker-trigger>` is the popover host. Wiring up your own
+  trigger means re-creating popover focus management — prefer composing
+  with the existing trigger via its `#default` scoped slot if you need
+  custom calendar content (this is exactly how Picker itself works).
+
+## Quick reference
+
+```vue
+<orio-date-picker
+  v-model="checkInDate"
+  label="Check-in"
+  :min="todayIso"
+  :max="maxBookingIso"
+  :is-disabled="(iso) => blockedDates.has(iso)"
+/>
+```

package/dist/runtime/components/date/Picker.vue

@@ -16,7 +16,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 value = defineModel({ type: [String, null], ...{ default: null } });
 const { locale, t } = useI18n();

package/dist/runtime/components/date/PickerTrigger.USAGE.md

@@ -0,0 +1,65 @@
+---
+kind: component
+category: Date
+purpose: date picker trigger button, date input button, popover-anchored date trigger
+short: shared button + popover trigger used by date Picker and RangePicker; default slot renders the picker body
+invariants: true
+---
+
+# date/PickerTrigger — agent-only invariants
+
+`<orio-date-picker-trigger>` is the trigger button shared by
+`<orio-date-picker>` and `<orio-date-range-picker>`. You usually do not
+use it directly — pick those higher-level pickers unless you are building
+a new date primitive.
+
+## Invariants
+
+- **Renders a `<button>` inside `<orio-control-element>` and an
+  `<orio-popover>`** with `position="bottom-right"`, `offset: 5`.
+- **`text` prop is the visible display text.** When empty, `placeholder`
+  renders muted.
+- **`text` and `placeholder` are stripped from `controlProps`** — they
+  don't leak to the ControlElement wrapper.
+- **Default slot is the popover content** and receives `{ toggle }`. Call
+  `toggle(false)` to close after a user picks.
+- **Calendar icon (`name="calendar"`) is hardcoded** on the right of the
+  button. No prop to swap it.
+- **`aria-expanded` reflects popover state** for screen reader support.
+- **Inherits all ControlElement contract**: `label`, `error`, `size`,
+  `layout`, etc. The control bag is bound to the inner `<button>`.
+
+## Gotchas
+
+- **Not for general "click-to-open" needs.** For a non-date trigger, use
+  `<orio-popover>` directly — this one is calendar-themed (icon, padding,
+  i18n placeholder).
+- **No multi-popover stacking story.** Both single and range pickers use
+  this same component, with the same `bottom-right` placement. Side-by-
+  side pickers may collide.
+
+## Quick reference
+
+You normally consume this through `<orio-date-picker>` or
+`<orio-date-range-picker>`. Direct use:
+
+```vue
+<template>
+  <orio-date-picker-trigger
+    :text="display"
+    :placeholder="$t('date.placeholder')"
+    :label="$t('date.label')"
+  >
+    <template #default="{ toggle }">
+      <orio-calendar v-model:anchor="anchor" @select="onSelect($event, toggle)" />
+    </template>
+  </orio-date-picker-trigger>
+</template>
+```
+
+## Related
+
+- `<orio-date-picker>` — single-date picker built on this trigger.
+- `<orio-date-range-picker>` — range picker built on this trigger.
+- `<orio-popover>` — for non-date trigger needs.
+- Public API reference: `docs/components/date/`.

package/dist/runtime/components/date/PickerTrigger.vue

@@ -10,7 +10,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 controlProps = computed(() => {
   const { text, placeholder, ...rest } = props;
@@ -19,11 +25,11 @@ const controlProps = computed(() => {
 </script>
 
 <template>
-  <orio-control-element v-slot="{ id }" v-bind="controlProps">
+  <orio-control-element v-slot="{ control }" v-bind="controlProps">
     <orio-popover position="bottom-right" :offset="5">
       <template #default="{ toggle, isOpen }">
         <button
-          :id
+          v-bind="control"
           type="button"
           class="date-trigger"
           :aria-expanded="isOpen"