orio-ui 1.27.0 → 1.28.0

package/dist/runtime/composables/useListKeyboard.USAGE.md

@@ -0,0 +1,97 @@
+---
+kind: composable
+category: Composables
+purpose: arrow-key flat list navigation, listbox keyboard, dropdown keys
+short: arrow / Home / End / Enter / Space / Esc handling for a flat indexable list with auto scroll-into-view
+invariants: true
+---
+
+# useListKeyboard — agent-only invariants
+
+`useListKeyboard` wires keyboard navigation for a flat list (listbox,
+menu, dropdown). It owns the highlighted index, scrolls the highlighted
+item into view, and emits open/close/select callbacks. Used internally by
+`<orio-selector>`.
+
+## Invariants
+
+- **`options.count()` is called on every navigation** — pass a function,
+  not a number. Lists that change size during interaction stay correct.
+- **`options.onSelect(index)`** fires on Enter or Space when the list is
+  open and a row is highlighted (`highlightedIndex >= 0`).
+- **`options.onOpen()`** fires when the user presses Arrow Down/Up,
+  Enter, or Space while the list is closed. Optional — without it,
+  closed-state key presses are no-ops.
+- **`options.onClose()`** fires on Escape (plus resets the highlight to
+  `-1`). Optional.
+- **`options.initialIndex()`** is called by `reset()` to set the
+  highlight on (re)open — typically returns the currently selected row.
+  Defaults to `0` when not provided.
+- **Returned `listRef` MUST be attached to the list container** (the
+  `<ul>` / `<ol>`) so `scrollIntoView` can find the highlighted child.
+  Without it, the highlight still moves but never scrolls.
+- **`onKeydown(e, isOpen)`** is the handler to wire on the trigger or
+  list. The caller passes `isOpen` because the composable does not own
+  open state.
+- **Every matched key calls `e.preventDefault()`.** Unmatched keys
+  bubble. Space is registered as `" "` (single space string).
+- **Highlight clamps to `[0, count - 1]`.** `highlight(-1)` lands on 0,
+  `highlight(99)` on `count - 1`.
+
+## Gotchas
+
+- **Children must be direct descendants of the `listRef` element** for
+  scrollIntoView to target the correct row. Nested wrappers (a `<li>`
+  with deep children) break the index → `ul.children[index]` lookup.
+- **Space (`" "`) selection collides with form behaviors.** Inside a
+  text input or button that already handles space, the preventDefault
+  may swallow it. Wire `onKeydown` on the listbox container or wrapping
+  focusable element, not on inputs.
+- **`reset()` calls `scrollIntoView` on `nextTick`** — the list element
+  must be in the DOM by then. Calling `reset()` before mounting the
+  list won't scroll until after the next tick.
+- **No type-ahead** ("press 'a' to jump to next item starting with a").
+  Implement upstream if needed.
+
+## Quick reference
+
+```ts
+import { ref } from "vue";
+import { useListKeyboard } from "../composables/useListKeyboard";
+
+const isOpen = ref(false);
+const items = ref<string[]>(["Alpha", "Bravo", "Charlie"]);
+const selected = ref<string | null>(null);
+
+const { highlightedIndex, listRef, onKeydown, reset } = useListKeyboard({
+  count: () => items.value.length,
+  onSelect: (index) => {
+    selected.value = items.value[index];
+    isOpen.value = false;
+  },
+  onOpen: () => {
+    isOpen.value = true;
+    reset();
+  },
+  onClose: () => (isOpen.value = false),
+  initialIndex: () => items.value.indexOf(selected.value ?? ""),
+});
+```
+
+```vue
+<template>
+  <button @keydown="onKeydown($event, isOpen)" @click="onOpen">Open</button>
+  <ul v-if="isOpen" ref="listRef">
+    <li v-for="(item, index) in items" :key="item"
+        :class="{ highlighted: index === highlightedIndex }">
+      {{ item }}
+    </li>
+  </ul>
+</template>
+```
+
+## Related
+
+- `<orio-selector>` — uses this composable internally.
+- `useRovingGrid` — 2D arrow-key roving focus.
+- Public API reference: `docs/composables/use-list-keyboard.md`.

package/dist/runtime/composables/useModal.USAGE.md

@@ -0,0 +1,82 @@
+---
+kind: composable
+category: Composables
+purpose: programmatic modal control, open modal from code, modal binding bag
+short: returns a `modalProps` bag (show, origin, update handler) plus `openModal(event?)` that derives origin from a click target
+invariants: true
+---
+
+# useModal — agent-only invariants
+
+`useModal` returns a binding bag for `<orio-modal>` plus an `openModal`
+helper that captures the click target's rect for the open-from-origin
+animation. Spread `modalProps` on the Modal — no manual `v-model:show`,
+no `:origin` wiring.
+
+## Invariants
+
+- **`modalProps` ref** has shape:
+  ```ts
+  {
+    show: boolean;
+    origin: OriginRect | null;
+    "onUpdate:show": (state: boolean) => void;
+  }
+  ```
+  Designed to be spread on `<orio-modal v-bind="modalProps">`. The
+  `"onUpdate:show"` listener is wired internally so the modal's close
+  button / backdrop click syncs back to the bag.
+- **`OriginRect`** (exported): `{ x, y, width, height }` — derived from
+  `getBoundingClientRect()` of the event target.
+- **`openModal(event?)`**:
+  - With an event: reads `event.target.getBoundingClientRect()` and
+    sets `origin` so the modal animates from the target. Sets `show`
+    to true.
+  - Without an event: clears `origin` to `null` and opens with a plain
+    fade.
+- **No close helper** is returned — `modalProps.show = false` works, or
+  use the modal's built-in close button.
+
+## Gotchas
+
+- **`event.target` is the clicked DOM node**, which may be a child of
+  the actual button (e.g. an icon inside). The rect then comes from
+  the icon, not the button — the animation origin will be tiny. To
+  capture the button itself, use `event.currentTarget` semantics by
+  reading the rect manually before calling `openModal`:
+  ```ts
+  function onClick(event: MouseEvent) {
+    const rect = (event.currentTarget as HTMLElement).getBoundingClientRect();
+    modalProps.value.origin = rect;
+    modalProps.value.show = true;
+  }
+  ```
+- **Only one modal per call site.** For multiple modals, call
+  `useModal()` once per modal — they don't share state.
+- **No `v-model:show`** on the returned bag — the bag uses the explicit
+  `onUpdate:show` listener form because spreading an object cannot
+  declare v-model sugar.
+
+## Quick reference
+
+```vue
+<script setup lang="ts">
+import { useModal } from "../composables/useModal";
+
+const { modalProps, openModal } = useModal();
+</script>
+
+<template>
+  <orio-button @click="openModal">Open</orio-button>
+
+  <orio-modal v-bind="modalProps" title="Settings">
+    <p>Modal body…</p>
+  </orio-modal>
+</template>
+```
+
+## Related
+
+- `<orio-modal>` — the consumer of this bag; supports `v-model:show`
+  and `origin` as plain props if you prefer manual wiring.
+- Public API reference: `docs/composables/use-modal.md`.

package/dist/runtime/composables/usePinchZoom.USAGE.md

@@ -0,0 +1,95 @@
+---
+kind: composable
+category: Composables
+purpose: pinch-to-zoom, two-finger touch zoom, pinch gesture
+short: touch-only pinch handler that tracks up to 2 pointers and exposes scale factor, midpoint, and midpoint delta
+invariants: true
+---
+
+# usePinchZoom — agent-only invariants
+
+`usePinchZoom(callbacks)` tracks **touch** pointers (up to 2) and emits a
+`scaleFactor` for two-finger gestures plus delegate callbacks for single-
+finger phases. The consumer wires the returned handlers to pointer events.
+
+## Invariants
+
+- **Touch-only.** `onPointerDown` returns `false` for non-touch (mouse,
+  pen) events. Mouse zoom needs separate wheel handling.
+- **Tracks at most 2 pointers.** A third touch is ignored.
+- **Callback shape**:
+  - `onPinchStart()` — fires when the second pointer goes down.
+  - `onPinchMove(scaleFactor, midX, midY, dx, dy)` — fires on each
+    two-finger move:
+    - `scaleFactor` = `currentDistance / startDistance` (cumulative
+      since pinch start).
+    - `midX`, `midY` = current viewport-coord midpoint between fingers.
+    - `dx`, `dy` = delta of the midpoint since the last move (for
+      pan-during-pinch).
+  - `onSingleDown(event)` — fires when the FIRST pointer goes down.
+  - `onSingleUp(remainingId, x, y)` — fires when one of two pointers
+    lifts, leaving one behind. Pass these to the caller's single-
+    pointer drag logic.
+  - `onAllUp()` — fires when the last pointer lifts.
+- **Pointer capture is set on `event.currentTarget`** for every down.
+  The consumer must wire `onPointerDown` to a real element so capture
+  works.
+- **`scaleFactor` is relative to pinch-start distance**, not the
+  previous frame. Multiply the consumer's "baseline scale at pinch
+  start" by `scaleFactor` to derive the new scale.
+- **`startDist` resets** when pointer count drops from 2 → 1 or 0.
+- **`pointers` is an exposed `Map`** keyed by pointerId — read it for
+  debugging.
+
+## Gotchas
+
+- **Single-pointer drag is the consumer's responsibility.** The
+  composable only signals down/up; you wire the actual move handling
+  outside.
+- **No pinch-axis lock.** Both x and y midpoint changes flow through;
+  diagonal pinch produces both zoom and pan. Filter in
+  `onPinchMove` if you want zoom-only.
+- **`scaleFactor` can exceed sensible ranges** on fast pinches. Clamp
+  upstream (e.g. against `minScale` / `maxScale`).
+- **PointerType check is exact `"touch"`.** Microsoft Surface pen
+  inputs and Apple Pencil have `pointerType: "pen"` — those won't
+  pinch via this composable.
+
+## Quick reference
+
+```ts
+import { usePinchZoom } from "../composables/usePinchZoom";
+
+let baseScale = 1;
+const scale = ref(1);
+const tx = ref(0);
+const ty = ref(0);
+
+const pinch = usePinchZoom({
+  onPinchStart() { baseScale = scale.value; },
+  onPinchMove(scaleFactor, midX, midY, dx, dy) {
+    scale.value = baseScale * scaleFactor;
+    tx.value += dx;
+    ty.value += dy;
+    // (also re-anchor scale around midpoint here)
+  },
+  onSingleDown(event) { /* hand off to single-pointer drag */ },
+  onSingleUp(id, x, y) { /* resume drag tracking on remaining finger */ },
+});
+```
+
+```vue
+<template>
+  <div
+    @pointerdown="pinch.onPointerDown"
+    @pointermove="pinch.onPointerMove"
+    @pointerup="pinch.onPointerUp"
+  />
+</template>
+```
+
+## Related
+
+- `<orio-zoomable-container>` — uses this for touch pinch.
+- `<orio-canvas>` — same.
+- Public API reference: `docs/composables/use-pinch-zoom.md`.

package/dist/runtime/composables/usePressAndHold.USAGE.md

@@ -0,0 +1,70 @@
+---
+kind: composable
+category: Composables
+purpose: long-press detection, press-and-hold, auto-repeat, mousedown-hold ramp
+short: fires a callback once immediately, then repeats every 50 ms after a 500 ms hold
+invariants: true
+---
+
+# usePressAndHold — agent-only invariants
+
+`usePressAndHold()` returns `{ pressAndHold, stop }` for press-and-hold
+auto-repeat. Used by `<orio-number-input-horizontal>` and
+`<orio-number-input-vertical>` to ramp values while a spinner button is
+held.
+
+## Invariants
+
+- **`pressAndHold(callback)` calls the callback once immediately**, then
+  starts a 500 ms timeout. After 500 ms, it begins calling the callback
+  every 50 ms via `setInterval`.
+- **`stop()` clears both the pending timeout and the active interval.**
+  Always call on `mouseup`, `mouseleave`, and `pointercancel` — leaks
+  fire forever otherwise.
+- **No reactivity, no state ref.** Just two functions. The internal
+  refs hold `setTimeout` / `setInterval` IDs only.
+- **No press duration / counter.** The composable only knows
+  "callback fires." Track elapsed time in the callback if needed.
+
+## Gotchas
+
+- **Timer leaks if `stop()` isn't called.** Common pitfall: forgetting
+  to wire `@mouseleave` means a user dragging off the button leaves
+  the interval running.
+- **Touch behavior is not handled.** `@mousedown` does fire on touch
+  in most browsers but not all. For reliable mobile press-and-hold,
+  consider also wiring `@touchstart` / `@touchend`.
+- **Re-entrancy not guarded.** Calling `pressAndHold(fn)` while a
+  previous press is active will create overlapping timers. Always
+  `stop()` before starting a new one.
+- **Fixed timing (500 ms delay, 50 ms repeat).** Not configurable. Fork
+  if you need different cadence.
+
+## Quick reference
+
+```vue
+<script setup lang="ts">
+import { usePressAndHold } from "../composables/usePressAndHold";
+
+const { pressAndHold, stop } = usePressAndHold();
+
+let count = ref(0);
+function increment() { count.value += 1; }
+</script>
+
+<template>
+  <button
+    @mousedown="pressAndHold(increment)"
+    @mouseup="stop"
+    @mouseleave="stop"
+  >
+    +1 ({{ count }})
+  </button>
+</template>
+```
+
+## Related
+
+- `<orio-number-input-horizontal>` — uses this for ± buttons.
+- `<orio-number-input-vertical>` — uses this for chevron buttons.
+- Public API reference: `docs/composables/use-press-and-hold.md`.

package/dist/runtime/composables/useRovingGrid.USAGE.md

@@ -0,0 +1,106 @@
+---
+kind: composable
+category: Composables
+purpose: roving-focus tabindex for 2D grids, grid keyboard navigation, calendar keyboard, table arrow nav
+short: 2D arrow-key roving focus for grid-like UIs; handles arrows, Home/End, PageUp/Down, Enter/Space, and edge-overflow callbacks
+invariants: true
+---
+
+# useRovingGrid — agent-only invariants
+
+`useRovingGrid` implements the WAI-ARIA roving-tabindex pattern for a 2D
+grid. Generic over `Cell`. Used internally by `<orio-calendar>`.
+
+## Invariants
+
+- **Only one cell has `tabindex="0"` at a time** — the active one. All
+  others get `-1`. The consumer wires this via `tabindexFor(key)`.
+- **Cells must carry a `focus-key="<key>"` attribute** matching
+  `options.getKey(cell)` — `focusActive()` queries
+  `[focus-key="..."]` with `CSS.escape` for the lookup.
+- **`rows`** is a `Ref` to a 2D array of cells. Rows may have
+  different column counts; navigation walks until it finds a valid
+  cell or hits an undefined.
+- **`activeKey`** is a `ComputedRef<string>`:
+  - If the user has focused a cell, returns that key.
+  - Otherwise returns `options.initial()` — the consumer's "default
+    focus target" (typically today's date in a calendar).
+- **`isNavigable(cell)`** (optional) — return `false` to skip cells
+  during arrow nav. Skipped cells are stepped past in the same
+  direction until a navigable cell is found, or the edge is hit.
+- **`onArrowOverflow(direction, activeKey)`** — fires when an arrow
+  would move past the rendered grid edge. Return a new `key` to focus
+  (e.g. after paging to the next month). Return `null` for no-op.
+- **`onPage(direction, bigJump, activeKey)`** — PageUp / PageDown.
+  `bigJump` is `event.shiftKey`. Same return contract as overflow.
+- **`onActivate(cell)`** fires on Enter or Space on the active cell.
+- **`onKeydown` calls `preventDefault` on every handled key**. Arrow,
+  Home, End, PageUp, PageDown, Enter, Space. Other keys bubble.
+- **`focusActive()` runs on `nextTick`** — the DOM must reflect the
+  active key by then. `scrollIntoView` with `block: nearest, inline:
+  nearest, behavior: smooth`. Focus uses `preventScroll: true` (the
+  scroll already happened).
+
+## Gotchas
+
+- **`getKey` must return strings** unique within the grid. Non-string
+  keys break the `focus-key` attribute lookup.
+- **No `aria-activedescendant` mode.** This is a roving-tabindex
+  implementation only. For activedescendant grids, build separately.
+- **`onArrowOverflow` must update backing state BEFORE returning the
+  new key.** The caller relies on the new key being findable in
+  `rows` on the next paint — usually the consumer mutates rows in
+  the same tick and returns the new key synchronously.
+- **`isNavigable: () => false` everywhere** would freeze arrow nav.
+  Always leave at least the active cell navigable.
+
+## Quick reference — calendar-style 2D grid
+
+```ts
+import { useRovingGrid } from "../composables/useRovingGrid";
+
+interface Day { iso: string; inMonth: boolean }
+
+const rows = ref<Day[][]>([...]); // 6 weeks × 7 days
+const gridRef = ref<HTMLElement | null>(null);
+
+const { activeKey, tabindexFor, onKeydown } = useRovingGrid({
+  rows,
+  gridRef,
+  getKey: (day) => day.iso,
+  initial: () => today.iso,
+  isNavigable: (day) => day.inMonth,
+  onActivate: (day) => emit("select", day.iso),
+  onArrowOverflow: (direction, activeKey) => {
+    pageMonth(direction); // mutates rows
+    return findNeighborIsoForOverflow(direction, activeKey);
+  },
+  onPage: (direction, bigJump) => {
+    pageMonth(direction, bigJump ? 12 : 1);
+    return today.iso;
+  },
+});
+```
+
+```vue
+<template>
+  <table ref="gridRef" @keydown="onKeydown">
+    <tr v-for="(week, weekIndex) in rows" :key="weekIndex">
+      <td
+        v-for="day in week"
+        :key="day.iso"
+        :focus-key="day.iso"
+        :tabindex="tabindexFor(day.iso)"
+      >
+        {{ day.iso }}
+      </td>
+    </tr>
+  </table>
+</template>
+```
+
+## Related
+
+- `<orio-calendar>` — uses this composable internally.
+- `useListKeyboard` — 1D version for flat lists.
+- Public API reference: `docs/composables/use-roving-grid.md`.

package/dist/runtime/composables/useSound.USAGE.md

@@ -0,0 +1,74 @@
+---
+kind: composable
+category: Composables
+purpose: audio cue playback, sound effect, UI click sound, beep
+short: low-latency Web Audio playback with a shared module-level AudioContext and per-URL buffer cache
+invariants: true
+---
+
+# useSound — agent-only invariants
+
+`useSound` returns `{ play, prefetch }`. It uses the Web Audio API (not
+`<audio>` elements) for low-latency, gapless playback. State is
+module-level — every consumer shares the same `AudioContext` and buffer
+cache.
+
+## Invariants
+
+- **Module-level singleton `AudioContext`**, created lazily on first
+  call. Same instance is reused across every `useSound()` consumer in
+  the page.
+- **Module-level `bufferCache`** keyed by source URL. Multiple
+  consumers with the same `src` share decoded buffers.
+- **Default sound is a remote URL** —
+  `https://cdn.jsdelivr.net/gh/oriondor/orio-ui@main/docs/public/sounds/mechanical-switch.wav`.
+  No offline / bundled fallback. Calling `play()` without a custom
+  `src` requires network on first use (cached thereafter by the
+  browser).
+- **Default `volume` is `0.3`** (Web Audio Gain node). Range `0..1`;
+  values above clip ungracefully.
+- **`prefetch: true`** in options eagerly fetches + decodes the buffer
+  at construction. Without it, the first `play()` includes
+  fetch + decode latency.
+- **`play()` auto-resumes a suspended context.** Browsers gate audio on
+  a user gesture; the first call after a click/key event will resume
+  the context.
+- **Returned `prefetch` warms the cache** for the configured `src` —
+  same as constructor `prefetch: true`, callable on demand.
+
+## Gotchas
+
+- **Cross-origin / CDN dependency**: the default sound relies on
+  `cdn.jsdelivr.net`. For self-hosted apps, pass your own `src`.
+- **No volume reactivity**: changing `volume` after construction does
+  nothing. Recreate `useSound({ volume: 0.5 })` to change the level.
+- **Errors are swallowed** with `console.error`. There is no `loaded`
+  ref, no `error` ref, no promise resolution to await. `play()` returns
+  a resolved promise even if the buffer never loaded.
+- **No autoplay before user gesture.** Calling `play()` before any user
+  interaction will silently fail in most browsers — the resume call
+  succeeds but the buffer source won't produce audio. Wire to a click
+  or keydown.
+- **`AudioContext` is never closed.** Long-lived apps accumulate one
+  context; for very long sessions, this is usually fine because the
+  context is shared.
+
+## Quick reference
+
+```ts
+import { useSound } from "../composables/useSound";
+
+const { play, prefetch } = useSound({
+  src: "/sounds/click.wav",
+  volume: 0.4,
+  prefetch: true, // load + decode now, before first user interaction
+});
+
+// Later, on click:
+button.addEventListener("click", () => play());
+```
+
+## Related
+
+- `<orio-animated-container>` — exposes `play` via the slot prop bag.
+- Public API reference: `docs/composables/use-sound.md`.

package/dist/runtime/composables/useTheme.USAGE.md

@@ -0,0 +1,76 @@
+---
+kind: composable
+category: Composables
+purpose: theme tokens, light/dark, theme switcher, color theme
+short: cookie-backed theme and mode (light/dark) accessor that writes `data-theme` and `data-mode` on `<html>`
+invariants: true
+---
+
+# useTheme — agent-only invariants
+
+Returns `{ theme, setTheme, mode, setMode }`. State lives in cookies
+(`COOKIE_NAMES.theme`, `COOKIE_NAMES.mode`) and is mirrored to
+`data-theme` / `data-mode` attributes on the document element so CSS
+selectors like `[data-theme="dark"]` work.
+
+## Invariants
+
+- **Backed by `useCookies` from `@vueuse/integrations`.** Cookies are
+  set at path `/`. SSR-friendly because `useCookies` reads request
+  cookies during render.
+- **Defaults come from `constants/theme.ts`** — `THEME_DEFAULTS.theme`
+  and `THEME_DEFAULTS.mode`. Override the defaults there, not at the
+  call site.
+- **`theme` and `mode` are computed refs** with `get` / `set`. Writing
+  to them updates the cookie immediately. The `data-*` attributes on
+  `<html>` only refresh when you call `setTheme` / `setMode`, not on
+  raw assignment.
+- **`onMounted(setHtmlAttrs)`** runs once per call site to apply
+  cookies to the document on the client.
+- **SSR-safe**: `setHtmlAttrs` early-returns when `document` is
+  undefined.
+
+## Gotchas
+
+- **Raw `theme.value = "dark"` writes the cookie but doesn't touch
+  `<html>` attrs.** Always go through `setTheme` / `setMode` if you
+  need the DOM to update in the same call.
+- **Multiple `useTheme()` consumers don't share an in-memory state** —
+  the cookie is the source of truth. Reactivity across components
+  requires reading the same cookie via `useCookies` again.
+- **Cookies are set at `path: "/"`.** If your app lives under a
+  sub-path, this still works but cookies are global to the domain. For
+  finer scoping, fork the composable.
+- **No system / OS preference detection.** No `prefers-color-scheme`
+  fallback. Wire that in the consumer if needed.
+- **`onMounted` per call** means N components → N attribute writes per
+  navigation. Cheap, but not idempotent at a single point.
+
+## Quick reference
+
+```ts
+import { useTheme } from "../composables/useTheme";
+
+const { theme, setTheme, mode, setMode } = useTheme();
+
+// Switch theme
+setTheme("ocean");
+setMode("dark");
+
+// Read current
+console.log(theme.value, mode.value);
+```
+
+```vue
+<template>
+  <orio-button @click="setMode(mode === 'dark' ? 'light' : 'dark')">
+    {{ mode === "dark" ? "☀" : "🌙" }}
+  </orio-button>
+</template>
+```
+
+## Related
+
+- `<orio-locale-switcher>` — sibling switch for vue-i18n locale.
+- `constants/theme.ts` — defaults and cookie names live here.
+- Public API reference: `docs/composables/use-theme.md`.