orio-ui 1.27.0 → 1.28.0

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

@@ -1,3 +1,11 @@
+---
+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>`

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/RangePicker.USAGE.md

@@ -0,0 +1,97 @@
+---
+kind: component
+category: Date
+purpose: date range, from-to picker, date range input, calendar range
+short: two-month range picker with hover-preview, min/max bounds, and ISO `{ start, end }` model
+invariants: true
+---
+
+# date/RangePicker — agent-only invariants
+
+`<orio-date-range-picker>` is the date range picker: a
+`<orio-date-picker-trigger>` opens a popover containing **two side-by-side
+calendars** (left = start month, right = start month + 1). Read
+`Calendar.USAGE.md` and `date/Picker.USAGE.md` first.
+
+## Invariants
+
+- **v-model is `DateRange = { start: string | null; end: string | null }`**
+  (ISO date strings). `DateRange` is re-exported from this file. Both
+  fields can be null (no selection) or just `start` (mid-pick).
+- **Click sequence is "set start → set end".** First click clears `end`,
+  writes `start`. Second click writes `end`. If the second pick is
+  earlier than the existing start, start and end **swap automatically**.
+- **The popover closes on range completion** (second pick), via
+  `toggle(false)`. A single click leaves it open.
+- **Two-month anchored display** — `leftAnchor` = first of start's month,
+  `rightAnchor` = `leftAnchor + 1 month`. They re-sync when the model's
+  start changes to a month not currently visible.
+- **Hover preview**: hovering a day in the popover renders an "accent"
+  range marker from `start` to the hovered day (or hovered day to start
+  if the hover is earlier). Requires `start` to be already picked.
+- **`min` / `max` are ISO strings** that gate selection via the calendar's
+  `isDisabled`. Consumer's own `isDisabled(iso)` predicate ORs in.
+- **`getMarker(iso)` is the consumer's marker provider.** The preview
+  marker **wins** over consumer markers for days inside the previewed
+  range.
+- **Built on `<orio-calendar>` × 2**, side-by-side in a flex row with
+  0.75rem gap.
+- **i18n key**: `dateRangePicker.placeholder` for the empty-display label.
+- **Display string**: `"start – end"` when both exist (en-dash, spaces).
+  Just `start` or just `end` if only one. Empty string if both null.
+
+## Gotchas
+
+- **The picked `start` does NOT render a marker by itself** when no `end`
+  and no hover — `previewMarker` requires both `previewStart` and
+  `previewEnd`. There is no visible feedback that a start was picked
+  until the user hovers or clicks an end. If you need a "just-start"
+  indicator, pass it via `markers` from the consumer.
+- **Both calendars share the same `markers`, `get-marker`, and
+  `is-disabled` props.** Consumer markers spanning across months draw
+  correctly because they're date-based, not anchor-based.
+- **Hover state clears on `mouseleave` of the popover content**, not on
+  picking. Quick double-click sequences clear hover only after the
+  second click.
+- **No keyboard support for range selection** — arrow-key roving inside
+  Calendar still works, but Enter on the keyboard-focused day picks one
+  end at a time, mirroring mouse behavior.
+- **Min/max bounds are ISO string comparisons**: `iso < min` works
+  because ISO dates sort lexicographically. Pass YYYY-MM-DD strings, not
+  arbitrary Date objects.
+
+## Quick reference
+
+```vue
+<script setup lang="ts">
+import type { DateRange } from "../components/date/RangePicker.vue";
+
+const range = defineModel<DateRange>({
+  default: () => ({ start: null, end: null }),
+});
+
+const bookedDays = ["2026-06-15", "2026-06-16"];
+function isDisabled(iso: string) {
+  return bookedDays.includes(iso);
+}
+</script>
+
+<template>
+  <orio-date-range-picker
+    v-model="range"
+    :label="$t('booking.dates')"
+    min="2026-06-10"
+    max="2026-12-31"
+    :is-disabled="isDisabled"
+  />
+</template>
+```
+
+## Related
+
+- `<orio-calendar>` — the underlying grid; rendered twice.
+- `<orio-date-picker>` — single-date variant.
+- `<orio-date-picker-trigger>` — the shared trigger button.
+- `utils/date` — `DateRange`, `parseISO`, `formatISO`, `addMonths`,
+  `startOfMonth`, `formatDate`.
+- Public API reference: `docs/components/date/`.

package/dist/runtime/components/gallery/Carousel.USAGE.md

@@ -0,0 +1,98 @@
+---
+kind: component
+category: Media & misc
+purpose: carousel, image slider, gallery, lightbox slider, image viewer
+short: image carousel with swipe gestures, prev/next buttons, dynamic sizing, and per-image slot
+invariants: true
+---
+
+# gallery/Carousel — agent-only invariants
+
+`<orio-gallery-carousel>` cycles through a list of images with swipe and
+prev/next buttons. Pair it with `<orio-gallery-carousel-preview>` for a
+thumbnail strip that binds to the same `activeImage` model.
+
+## Invariants
+
+- **v-model name is `activeImage`** and the type is `string` (the image
+  URL or id), **not** an index. Bind via `v-model:active-image="..."`.
+- **`size` prop is a `"W:H"` string** parsed as `width:height` in
+  pixels:
+  - `"400:550"` → fixed 400×550.
+  - `"400:"` (empty after colon) → fixed width, **dynamic height** —
+    measured from the slot content via a hidden `.carousel-measure`
+    container.
+  - `":550"` → fixed height, dynamic width.
+- **`fit`**: `"contain"` (default), `"fill"`, `"cover"`, `"scale-down"`.
+  Applied as `object-fit` to the inner image via `v-bind(fit)` CSS
+  binding.
+- **`appearance`**: `"default"` (border + background) or `"minimal"` (no
+  border, no background; prev/next buttons appear only on hover).
+- **Swipe threshold is 10px** of horizontal pointer movement. Drag-right
+  → `previousImage`, drag-left → `nextImage`. Below threshold = no
+  change.
+- **Looping is implicit.** `nextImage` past the last → first, `previousImage`
+  before the first → last. No flag to disable.
+- **Only 3 items are visible at once**: previous (translated −100%),
+  active (0), next (translated +100%). All others have `opacity: 0;
+  pointer-events: none`.
+- **`#image` slot** overrides the default `<img>` render. Receives `{ image }`.
+  Use for videos, captions, complex viewer markup. Slotted content is
+  also rendered into the hidden measure container when `size` has a
+  dynamic dimension.
+- **Auto-init on mount**: if `activeImage` is unbound or empty, it is
+  set to `images[0]`.
+- **Switch buttons only render when `images.length > 1`.**
+- **Transitions**: opacity + transform, 0.5s ease-in-out.
+- **`max-height` clamp**: when both dimensions are fixed, the carousel
+  scales down to `carouselWidth / aspectRatio` to respect the parent
+  width while preserving the aspect.
+
+## Gotchas
+
+- **Image URLs must be unique** — they are used as v-for keys and the
+  active-image model. Duplicate URLs collapse to one logical slide.
+- **No keyboard arrow nav.** Swipe + click only. Add `@keydown` on a
+  parent if needed.
+- **Switch buttons use `mix-blend-mode: difference`** on supporting
+  browsers (not Safari) to remain visible over any image. Custom themes
+  may need to override the `.switch-button :deep(.icon)` styles.
+- **Dynamic sizing causes a one-frame measurement flicker** while the
+  hidden measure container resolves. For non-changing content, prefer a
+  fixed `size` like `"400:550"`.
+- **The carousel `<img>` has `alt="image-url"`** by default — visually
+  fine but bad for accessibility. Override via `#image` slot to render
+  proper alt text.
+
+## Quick reference
+
+```vue
+<script setup lang="ts">
+const images = [
+  "/photos/1.jpg",
+  "/photos/2.jpg",
+  "/photos/3.jpg",
+];
+const active = ref(images[0]);
+</script>
+
+<template>
+  <orio-gallery-carousel
+    v-model:active-image="active"
+    :images="images"
+    size="600:"
+    fit="contain"
+  />
+  <orio-gallery-carousel-preview
+    v-model:active-image="active"
+    :images="images"
+  />
+</template>
+```
+
+## Related
+
+- `<orio-gallery-carousel-preview>` — thumbnail strip bound to the same
+  active-image model.
+- `<orio-modal>` — wrap a carousel for lightbox viewing.
+- Public API reference: `docs/components/gallery/`.

package/dist/runtime/components/gallery/CarouselPreview.USAGE.md

@@ -0,0 +1,51 @@
+---
+kind: component
+category: Media & misc
+purpose: carousel preview, thumbnails strip, image picker strip, gallery thumbnails
+short: horizontal thumbnail strip for the Carousel; clicking a thumb updates the shared `activeImage` model
+invariants: true
+---
+
+# gallery/CarouselPreview — agent-only invariants
+
+`<orio-gallery-carousel-preview>` renders a horizontal scrollable strip of
+thumbnails for `<orio-gallery-carousel>`. Bind both components to the same
+`v-model:active-image` and they stay in sync.
+
+## Invariants
+
+- **v-model name is `activeImage`** (same as the Carousel) and the type
+  is `string`. Share the same ref between them.
+- **Hidden when `images.length ≤ 1`.** Single-image galleries don't
+  render a strip.
+- **Each thumbnail is a `<button>`** with `aria-pressed` (true when
+  active) and `aria-label` `"Show image N of M"` for screen readers.
+- **Thumbnails are 3.5rem × 3.5rem** with `object-fit` driven by `fit`
+  (default `"cover"`, unlike Carousel's `"contain"` default).
+- **`#image` slot** overrides the default `<img>` render. Receives
+  `{ image }`. Same signature as the Carousel slot.
+- **Strip scrolls horizontally** with `overflow-x: auto`. No
+  auto-scroll-to-active — clicking a thumb that's offscreen won't
+  scroll it into view.
+- **Active thumb gets**: opacity 1, accent border. Inactive: opacity
+  0.6 with a hover bump to 0.85.
+
+## Gotchas
+
+- **No keyboard arrow nav between thumbs.** Tab moves between buttons;
+  Enter / Space activates. Add roving-focus if needed.
+- **No auto-scroll on active change.** If the consumer changes
+  `activeImage` from elsewhere, the strip doesn't follow — scroll it
+  into view yourself via `element.scrollIntoView()`.
+- **Alt is `""`** on thumbnails by default — they're treated as
+  decorative because the `<button>` carries the accessible name.
+
+## Quick reference
+
+See `<orio-gallery-carousel>` USAGE.md.
+
+## Related
+
+- `<orio-gallery-carousel>` — the main viewer; share the
+  `activeImage` model.
+- Public API reference: `docs/components/gallery/`.

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

@@ -0,0 +1,91 @@
+---
+kind: component
+category: Media & misc
+purpose: upload, file picker, drop-to-upload, file input, headless file upload
+short: headless file upload — provides drop-zone state and file-dialog opener via slot props; consumer renders the UI
+invariants: true
+---
+
+# upload — agent-only invariants
+
+`<orio-upload>` is a **headless** file-upload component. It owns drag-drop
+detection and file-dialog opening; the consumer renders all UI through the
+default slot. There is no built-in look.
+
+## Invariants
+
+- **Template is essentially `<div><slot :is-over-drop-zone :open-dialog /></div>`.**
+  No styling, no built-in drop hint, no preview list.
+- **Slot props**:
+  - `isOverDropZone: boolean` — true while a dragged file is over the
+    zone (and the component is not disabled).
+  - `openDialog: () => void` — opens the native file picker.
+- **v-model is `File[]`** (default `[]`). Drops and dialog selections
+  **append** to it; the array is then sliced to `maxFiles` if set.
+- **`maxFiles`**:
+  - `undefined` (default) → unlimited.
+  - `> 1` → multi-select mode (drop & dialog).
+  - `1` → single-file mode; new selections replace the array (capped to
+    length 1 by the slice).
+- **`allowedTypes`** is forwarded as `dataTypes` to `useDropZone`
+  (drop filter) and as `accept` (comma-joined) to the native dialog.
+  Be explicit — passing MIME-type strings (`"image/png"`) vs.
+  extensions (`".png"`) is the consumer's choice.
+- **`disabled`** blocks both drop and `openDialog` calls. `isOverDropZone`
+  is also forced `false` while disabled so the slot UI doesn't flash an
+  "active" state during a no-op.
+- **The whole template div is the drop zone.** The slot content sits
+  inside it; the consumer's hit area equals whatever they render.
+
+## Gotchas
+
+- **No UI at all by default.** A bare `<orio-upload v-model="files" />`
+  renders an empty `<div>` — clicking does nothing. You must provide a
+  default slot that calls `openDialog`.
+- **Drops append**, including duplicates. Same-named files are added
+  again; dedupe in the consumer if needed.
+- **`maxFiles` only enforces on append**. If the model is pre-populated
+  with more files than `maxFiles`, they stick around until the next
+  drop / dialog truncates them.
+- **`useFileDialog` uses native input.** It's not styleable. The "dialog"
+  is the OS chooser; styling lives on the trigger element you render in
+  the slot.
+- **No progress / upload semantics.** This component only collects File
+  objects. Uploading them to a server is the consumer's job.
+- **`accept` attribute on the dialog vs. drop filter divergence**: the
+  drop filter is enforced by browser drag-drop semantics; the dialog's
+  `accept` is a hint, not a hard filter — users can choose any file via
+  the chooser depending on OS.
+
+## Quick reference
+
+```vue
+<script setup lang="ts">
+const files = ref<File[]>([]);
+</script>
+
+<template>
+  <orio-upload
+    v-model="files"
+    :max-files="5"
+    :allowed-types="['image/png', 'image/jpeg']"
+  >
+    <template #default="{ isOverDropZone, openDialog }">
+      <orio-dashed-container
+        :icon="isOverDropZone ? 'drop' : 'upload'"
+        :text="$t(isOverDropZone ? 'upload.drop' : 'upload.choose')"
+        @click="openDialog"
+      />
+    </template>
+  </orio-upload>
+
+  <ul>
+    <li v-for="(file, index) in files" :key="index">{{ file.name }}</li>
+  </ul>
+</template>
+```
+
+## Related
+
+- `<orio-dashed-container>` — common UI shell for upload tiles.
+- Public API reference: `docs/components/upload.md` (if present).

package/dist/runtime/components/view/Dates.USAGE.md

@@ -0,0 +1,67 @@
+---
+kind: component
+category: Media & misc
+purpose: read-only date display, formatted date range, date range view
+short: locale-aware read-only date or date range display; inline `<orio-view-text>` for start/end
+invariants: true
+---
+
+# view/Dates — agent-only invariants
+
+`<orio-view-dates>` renders a `DateRange` (`{ start, end }`) as inline
+formatted text using the active vue-i18n locale.
+
+## Invariants
+
+- **`dates` is required** and typed `DateRange` (ISO strings).
+- **Format options**:
+  - Default: `{ day: "numeric", month: "short", year: "numeric" }` →
+    `"10 Jun 2026"`.
+  - `month: true` → omits the day → `"Jun 2026"`. Use for
+    month-resolution ranges (subscription periods, etc.).
+- **Uses `formatDate(iso, locale, options)` from `utils/date`**. Output
+  follows the locale — `en` vs `uk` will render different month
+  abbreviations.
+- **Separator**: literal `" - "` rendered between start and end when
+  both are present. No en-dash, no localization.
+- **Renders two `<orio-view-text>`** with `type` and `size` forwarded
+  (defaults `type: "italics"`, `size: "small"`).
+- **`* { display: inline }`** on the wrapper forces both view-text
+  blocks inline so they read as one sentence.
+
+## Gotchas
+
+- **Only start, only end, or both**: rendering gracefully handles a
+  missing `end` (no separator, no second block). A missing `start` with
+  an `end` renders the separator alone — degraded UX.
+- **No relative formatting** (e.g. "yesterday", "3 days ago"). For
+  relative output, format in the consumer and pass via
+  `<orio-view-text>` instead.
+- **`size` is forwarded to view-text** but the wrapper itself has no
+  size. Custom CSS that targets the wrapper won't see a size class.
+
+## Quick reference
+
+```vue
+<script setup lang="ts">
+const period = { start: "2026-06-01", end: "2026-06-30" };
+</script>
+
+<template>
+  <orio-view-dates :dates="period" />
+
+  <orio-view-dates
+    :dates="{ start: subscriptionStart, end: subscriptionEnd }"
+    month
+    type="title"
+    size="medium"
+  />
+</template>
+```
+
+## Related
+
+- `<orio-view-text>` — used internally for each end of the range.
+- `<orio-date-range-picker>` — picker that produces `DateRange` values.
+- `utils/date` — `formatDate`, `DateRange` type.
+- Public API reference: `docs/components/view/dates.md` (if present).

package/dist/runtime/components/view/KeyBinds.USAGE.md

@@ -0,0 +1,58 @@
+---
+kind: component
+category: Media & misc
+purpose: keyboard bindings hint display, shortcut display, kbd renderer
+short: parses a backtick-delimited shortcut string and renders each key as `<kbd>` with separators inline
+invariants: true
+---
+
+# view/KeyBinds — agent-only invariants
+
+`<orio-view-key-binds>` parses a backtick-delimited string like
+`` "`Ctrl` + `Z`" `` and renders each backticked token as a `<kbd>`
+element with the surrounding text as separator.
+
+## Invariants
+
+- **`bind` is the single string prop.** Tokens between backticks (`` `…` ``)
+  become `<kbd>` elements; everything else renders as a `.separator`
+  `<span>`.
+- **Regex is `/`([^`]+)`/g`** — non-greedy match inside backticks.
+  Empty backticks (`` `` ``) and unmatched openings are passed through
+  as plain text.
+- **No tokenization beyond backticks.** `"+"`, `" "`, `","`, `"or"`
+  between keys all render as plain separator text. Style them via the
+  `.separator` class.
+- **Output structure**: one `<span class="keybinds">` wrapper, with
+  `<kbd>` and `<span class="separator">` children inline. Wrapper is
+  `inline-flex` with 0.2rem gap.
+- **Kbd styling** is fixed: rgba white background tint, small font,
+  border. Designed for dark surfaces — over a light background, the
+  contrast may be poor; override `kbd` styles via global CSS.
+
+## Gotchas
+
+- **The string is rendered as-is.** No localization, no key-symbol
+  substitution (e.g. `Cmd` does not become `⌘`). Build that mapping in
+  the consumer if needed.
+- **No `aria-label`.** Screen readers read each `<kbd>` token aloud
+  with the separator text — usually fine for `"Ctrl + Z"`, less great
+  for `" or "`-separated alternates.
+- **Mismatched backticks render as text.** `` "`Ctrl + Z" `` (missing
+  closing tick) becomes plain text starting from the unmatched
+  backtick.
+
+## Quick reference
+
+```vue
+<template>
+  <orio-view-key-binds bind="`Ctrl` + `Z`" />
+  <orio-view-key-binds bind="press `Esc` to close" />
+  <orio-view-key-binds bind="`Cmd` + `Shift` + `P` or `F1`" />
+</template>
+```
+
+## Related
+
+- Public API reference: `docs/components/view/key-binds.md` (if
+  present).