orio-ui 1.24.0 → 1.28.0

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/date/RangePicker.vue

@@ -22,7 +22,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 range = defineModel({ type: Object, ...{
   default: () => ({ start: null, end: null })

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

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

@@ -0,0 +1,57 @@
+---
+kind: component
+category: Media & misc
+purpose: separator, divider, horizontal rule, divider line
+short: horizontal separator line with configurable border style, size in px, and block margin in rem
+invariants: false
+---
+
+# view/Separator — agent-only invariants
+
+`<orio-view-separator>` is a horizontal rule rendered as a `<div>` with a
+`border-block-end`. It is **not** an `<hr>` element.
+
+## Invariants
+
+- **`style` prop** is the CSS border style: `"solid"` (default),
+  `"dotted"`, `"dashed"`, `"double"`, `"groove"`, `"ridge"`.
+- **`size`** (number, default `1`) is the border width in **pixels**.
+- **`margin`** (number, default `1`) is the **rem** spacing above and
+  below via `margin-block`. So `margin: 1` → `1rem` top + `1rem`
+  bottom.
+- **Color is `var(--color-border)`** — not themable per-instance. Use
+  CSS overrides if you need a different color.
+- **Block-direction aware**: `border-block-end` and `margin-block`
+  respect the writing mode. In a horizontal writing mode it's a bottom
+  border + vertical margins; in vertical writing modes it flips.
+
+## Gotchas
+
+- **Renders a `<div>`, not an `<hr>`.** Screen readers may not announce
+  a section break. For semantic separation, add `role="separator"` via
+  `$attrs`.
+- **`size` is unitless number → px** by template binding. Strings get
+  used verbatim (`"2px"` works, but loses the type signal).
+- **No vertical orientation.** For a vertical divider, write a custom
+  `<div>` with `border-inline-start` rather than using this component.
+
+## Quick reference
+
+```vue
+<template>
+  <p>First section</p>
+
+  <orio-view-separator />
+
+  <p>Second section</p>
+
+  <orio-view-separator style="dashed" :size="2" :margin="2" />
+
+  <p>Third section</p>
+</template>
+```
+
+## Related
+
+- Public API reference: `docs/components/view/separator.md` (if
+  present).

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

@@ -0,0 +1,68 @@
+---
+kind: component
+category: Media & misc
+purpose: read-only text display, formatted view, typography primitive, label
+short: typed text primitive (text/title/subtitle/italics) with size, uppercase, line-clamp, and inline icon
+invariants: true
+---
+
+# view/Text — agent-only invariants
+
+`<orio-view-text>` is the typography primitive for read-only labels and
+text blocks. Use it instead of bare `<p>` / `<span>` / `<h*>` for inline
+icons, theming, and line-clamping.
+
+## Invariants
+
+- **`type`**: `"text"` (default) / `"title"` (bold) / `"subtitle"`
+  (semi-bold, muted) / `"italics"` (italic, muted). Affects font-weight,
+  style, and color.
+- **`size`**: `"small"` / `"medium"` (default) / `"large"` /
+  `"extra-large"`. Maps to `--font-sm` … `--font-xl` tokens.
+- **`uppercase: true`** applies `text-transform: uppercase`.
+- **`icon` prop** renders `<orio-icon>` inline before the text/slot. The
+  wrapper is `display: flex; align-items: center; gap: 0.25rem` so the
+  icon sits inline with the text.
+- **`lineClamp` (number or string)** enables `-webkit-line-clamp` line
+  truncation with ellipsis. Defaults to 1 line when the prop is present
+  but unset.
+- **Content sources**: default slot or `v-model:modelValue` string. Slot
+  wins. v-model is bound so the component plays nicely with
+  `<orio-form>` auto-bind by `name`.
+- **`--view-text-color` CSS var** overrides the type's default color
+  without changing the type prop. Useful for accent/error states from
+  the consumer.
+- **No `inheritAttrs: false`** — attrs flow to the wrapper `<div>`.
+
+## Gotchas
+
+- **The wrapper is a `<div>`, not a heading element.** Title type does
+  not produce an `<h1>` / `<h2>` etc. For semantic headings, write
+  `<h2><orio-view-text type="title">...</orio-view-text></h2>` or use a
+  plain heading element.
+- **`lineClamp` requires multi-line content** to show the ellipsis. A
+  single-line value with `lineClamp: 2` simply renders as one line.
+- **`white-space: pre-wrap`** is set globally on the wrapper —
+  whitespace and newlines from the source are preserved.
+
+## Quick reference
+
+```vue
+<template>
+  <orio-view-text type="title" size="large">
+    {{ $t("article.title") }}
+  </orio-view-text>
+
+  <orio-view-text type="subtitle" :line-clamp="3" icon="info">
+    {{ description }}
+  </orio-view-text>
+
+  <orio-view-text type="italics" uppercase v-model="badgeLabel" />
+</template>
+```
+
+## Related
+
+- `<orio-view-dates>` — locale-aware date range display built on top.
+- `<orio-empty-state>` — uses this internally for title and description.
+- Public API reference: `docs/components/view/text.md` (if present).

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

@@ -0,0 +1,64 @@
+---
+kind: composable
+category: Composables
+purpose: fetch, API client, HTTP request, JSON fetch
+short: thin typed wrapper around ofetch's `$fetch` for GET/POST/PUT/DELETE/PATCH requests
+invariants: false
+---
+
+# useApi — agent-only invariants
+
+`useApi` is a typed async function (not a reactive composable) that
+wraps `ofetch`'s `$fetch`. It returns a `Promise<T>` — no loading/error
+refs, no Vue lifecycle.
+
+## Invariants
+
+- **Not a Vue composable.** It is a plain typed async function, safe to
+  call anywhere — outside `setup`, inside event handlers, in route
+  middleware.
+- **Two overloads**: `useApi<T>(url)` for GET, `useApi<T>(url, options)`
+  for everything else.
+- **`ApiOptions`** fields:
+  - `method`: `"GET"` (default), `"POST"`, `"PUT"`, `"DELETE"`, `"PATCH"`.
+  - `body`: `Record<string, unknown>` — JSON object. Not FormData, not
+    a string.
+  - `query`: `Record<string, unknown>` — appended as query params.
+  - `signal`: `AbortSignal` for cancellation.
+- **Return type is `T`** — pass the generic for type safety. Without
+  it, you get `unknown`.
+
+## Gotchas
+
+- **No retry, no caching, no de-dupe.** Bring `@tanstack/vue-query` or
+  similar if you need those.
+- **`body` does not handle non-JSON payloads.** For file uploads,
+  use `fetch` directly or extend the composable.
+- **Errors throw.** Wrap calls in try/catch — `ofetch` throws on non-2xx
+  responses.
+
+## Quick reference
+
+```ts
+import { useApi } from "../composables/useApi";
+
+interface User { id: string; name: string }
+
+const user = await useApi<User>("/api/users/123");
+
+const created = await useApi<User>("/api/users", {
+  method: "POST",
+  body: { name: "Vlad" },
+});
+
+const controller = new AbortController();
+const results = await useApi<User[]>("/api/users", {
+  query: { search: "vl" },
+  signal: controller.signal,
+});
+controller.abort(); // cancels the request
+```
+
+## Related
+
+- Public API reference: `docs/composables/use-api.md` (if present).