orio-ui 1.27.0 → 1.28.1

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/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

@@ -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).