orio-ui 1.27.0 → 1.28.0

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

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

@@ -0,0 +1,73 @@
+---
+kind: composable
+category: Composables
+purpose: control size tokens, sizing tokens for form controls, control variant sizing
+short: provide/inject `ControlSize` (sm/md/lg/xl) and read a CSS-var token bag for the active size
+invariants: true
+---
+
+# useControlSize — agent-only invariants
+
+This composable owns the **CSS variable bag** that maps a `ControlSize`
+(`sm` / `md` / `lg` / `xl`) to concrete padding, font, gap, radius, and
+icon-size tokens. Used internally by ControlElement and friends.
+
+## Invariants
+
+- **Two exports**: `provideControlSize(size)` and `useControlTokens(explicit?, fallback?)`.
+  Most consumers don't need either — ControlElement wires them — but you
+  can use them to size custom controls.
+- **Provide key is a module-local `Symbol`** — there is exactly one
+  channel per app. `provideControlSize(ref("lg"))` from a parent scopes
+  every nested `useControlTokens()` call to that size.
+- **`useControlTokens(explicit, fallback = "md")`** returns:
+  - `size: ComputedRef<ControlSize>` — resolved size (explicit ?? injected
+    ?? fallback).
+  - `tokens: ComputedRef<Record<string, string>>` — the CSS-var bag for
+    that size. Spread it onto a `style` binding to apply the sizing.
+- **Token keys** include `--control-font-size`, `--control-label-font-size`,
+  `--control-py`, `--control-px`, `--control-gap`, `--control-radius`,
+  `--control-icon-size`, `--control-inner-block-start`, `--control-inner-block-end`,
+  `--control-label-block-start`. Adding new tokens requires extending
+  every size in `sizeTokens`.
+- **`sizeTokens` is exported** as the raw record — useful for previews or
+  ad-hoc lookups outside Vue.
+
+## Gotchas
+
+- **`useControlTokens` works outside an `<orio-control-element>`** — it
+  falls back to `md` (or the provided fallback) when no provider exists.
+  No error is thrown.
+- **The `explicit` argument wins over the injection.** Use it when the
+  caller takes an own `size` prop and wants it to override an ambient
+  one.
+- **Style binding requires the `tokens` value, not the ref.** Spread it
+  on `:style`:
+  ```vue
+  <div :style="tokens">...</div>
+  ```
+
+## Quick reference — custom control consuming the tokens
+
+```ts
+import { computed, toRef } from "vue";
+import { useControlTokens } from "../composables/useControlSize";
+import type { ControlSize } from "../components/ControlElement.vue";
+
+interface Props { size?: ControlSize }
+const props = defineProps<Props>();
+const { tokens } = useControlTokens(toRef(props, "size"));
+```
+
+```vue
+<template>
+  <div :style="tokens" class="my-control">…</div>
+</template>
+```
+
+## Related
+
+- `<orio-control-element>` — provides and consumes this composable.
+- `<orio-selector>` — uses `useControlTokens(size)` to size the
+  dropdown popover content.
+- Public API reference: `docs/composables/use-control-size.md`.

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

@@ -0,0 +1,72 @@
+---
+kind: composable
+category: Composables
+purpose: locale-aware number formatting, decimal parser, currency-safe parser
+short: parse numeric strings (US or EU separator) and format via Intl.NumberFormat with locale defaults
+invariants: true
+---
+
+# useDecimalFormatter — agent-only invariants
+
+Returns `{ toNumber, formatDecimal }`. Stateless, no Vue reactivity —
+call it once and reuse the two helpers.
+
+## Invariants
+
+- **`toNumber(input: string | number)`**:
+  - Numbers pass through as-is (non-finite → `null`).
+  - Strings are stripped of any character except digits, `,`, `.`, `-`.
+  - **Decimal separator auto-detected** by checking the position of the
+    last `,` and last `.`:
+    - If last `,` is after last `.` → European format. Strip `.` (thousands)
+      and convert `,` to `.` (decimal).
+    - Otherwise → US format. Strip `,` and keep `.`.
+  - Returns `null` for empty / unparseable input.
+- **`formatDecimal(input, options?)`**:
+  - `locale`: defaults to `navigator.languages[0] ?? navigator.language`
+    on client, `"de-DE"` on server.
+  - `decimals`: shortcut that sets both `minimumFractionDigits` and
+    `maximumFractionDigits` (default `2`).
+  - Explicit `minimumFractionDigits` / `maximumFractionDigits` override
+    the `decimals` shortcut.
+  - Returns `null` if `toNumber` fails.
+- **Uses `Intl.NumberFormat`** under the hood — output respects the
+  locale's group separator and decimal mark.
+
+## Gotchas
+
+- **Auto-separator detection is heuristic.** `"1,000"` is ambiguous; the
+  parser treats it as US (1000), not EU (1.0). For unambiguous behavior,
+  strip separators before passing.
+- **No currency symbol handling.** `"$1,234.56"` is stripped to
+  `"1234.56"` and parsed. To format as currency, build your own with
+  `Intl.NumberFormat(locale, { style: "currency", currency: "USD" })`.
+- **SSR fallback locale is `"de-DE"`**, not `"en-US"`. EU number
+  formatting in SSR pre-hydration may surprise US consumers — pass
+  `locale` explicitly to avoid hydration mismatches.
+- **Negative numbers**: `-` is allowed in the cleaning regex anywhere in
+  the string. `"100-50"` becomes `"100-50"` then `Number("100-50") = NaN`
+  → null. No expression evaluation.
+
+## Quick reference
+
+```ts
+import { useDecimalFormatter } from "../composables/useDecimalFormatter";
+
+const { toNumber, formatDecimal } = useDecimalFormatter();
+
+toNumber("1.234,56");      // 1234.56  (EU)
+toNumber("1,234.56");      // 1234.56  (US)
+toNumber("abc");           // null
+
+formatDecimal(1234.5, { locale: "de-DE" });      // "1.234,50"
+formatDecimal(1234.5, { locale: "en-US" });      // "1,234.50"
+formatDecimal(1234.567, { decimals: 0 });        // "1,235"
+formatDecimal("$1,234.567", { maximumFractionDigits: 1 }); // "1,234.6"
+```
+
+## Related
+
+- `<orio-number-input>` — uses similar fraction-digit semantics via its
+  `decimalPlaces` prop.
+- Public API reference: `docs/composables/use-decimal-formatter.md`.

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

@@ -0,0 +1,120 @@
+---
+kind: composable
+category: Composables
+purpose: named filter group, v-bind bags for pickers, active chips, URL-synced filters, filter state
+short: named filter group with v-bind bags, $-helpers, $active chips, $clearAll, optional URL sync via lazy import
+invariants: true
+---
+
+# useFilter — agent-only invariants
+
+`useFilter` defines or retrieves a **named filter group** stored in a
+module-level registry. Any component that knows the `id` can read and
+mutate the same reactive state — independent of the component tree.
+
+There's a dedicated `use-filter-onboarder` subagent that owns the canonical
+integration patterns. Trigger it for non-trivial setups (filter bars,
+chip rows, URL-synced filters).
+
+## Invariants
+
+- **Two overloads**:
+  - `useFilter(id, config, options?)` — defines a group.
+  - `useFilter(id)` — retrieves an existing group. Throws if no group
+    by that id has been defined.
+- **Module-level `registry`** — calls with the same `id` return the
+  same `FilterGroup` reference. Defining twice warns and returns the
+  existing group (the new config is ignored).
+- **`FilterDefinition.value` is both the initial value AND the
+  "empty" baseline.** Used to compute `isActive` (deep `!== initial`)
+  and to reset via `clear()`.
+- **`structuredClone`** copies the initial values so mutating the
+  returned `value` does not mutate the baseline.
+- **`isEqual`** is a hand-rolled deep equality (`===` for primitives,
+  recursive for arrays and plain objects). Custom classes / Date /
+  Map / Set fall back to `===` → likely a false negative.
+- **Each filter exposes a v-bind bag** via `filters[name]`:
+  ```ts
+  { modelValue, "onUpdate:modelValue": (v) => state[name] = v }
+  ```
+  Spread on any `v-model`-compatible component:
+  `<orio-selector v-bind="filters.category" />`.
+- **`filters.$.<name>`** has helpers per filter: `value`, `initial`,
+  `isActive`, `clear()`.
+- **`filters.$active`** is a `ComputedRef<ActiveFilter[]>` — array of
+  `{ name, value, clear }` for filters whose value differs from the
+  initial. Use for chip rows.
+- **`filters.$clearAll()`** resets every filter to its initial value.
+- **`filters.$state`** is the raw `Ref<Record<string, unknown>>` —
+  serialize for API calls or persist externally.
+- **URL sync (`options.url: true`)** lazy-imports `./useUrlSync`. The
+  Nuxt `#imports` dep is **not** loaded unless this flag is set,
+  keeping `useFilter` runnable in non-Nuxt contexts.
+- **URL-synced watcher lives in a detached `effectScope`** owned by
+  the registry, not by the component that defined the group — the
+  watcher outlives the defining component.
+- **`disposeFilter(id)`** removes the group and stops its URL-sync
+  effect scope. Use in SPAs to clear page-scoped filter groups on
+  route change.
+
+## Gotchas
+
+- **Filter names become top-level URL keys** when `url: true`.
+  Collisions across multiple URL-synced groups on the same page
+  silently overwrite each other.
+- **`structuredClone` doesn't handle Functions, DOM nodes, or class
+  instances** — passing them in `value` will throw at define time.
+- **`$active` recomputes on every state change**, doing a deep
+  comparison per filter. For large filter groups with deep objects,
+  consider shallow representations.
+- **Lazy URL sync arrives one microtask late** — the initial render
+  may flash the default values before the URL values land. Acceptable
+  for chips/dropdowns; not for visibly-important first paint.
+- **Retrieving an undefined group throws** — always define first
+  somewhere in the tree (layout / page setup) before retrieving in
+  children.
+
+## Quick reference — define + bind + chips
+
+```ts
+const filters = useFilter(
+  "appointments",
+  {
+    category: { value: null as string | null },
+    status:   { value: [] as string[] },
+    dateRange:{ value: { from: null, to: null } as { from: string | null; to: string | null } },
+  },
+  { url: true },
+);
+```
+
+```vue
+<template>
+  <orio-selector v-bind="filters.category" :options="categories" />
+  <orio-taggable-selector v-bind="filters.status" :options="statuses" />
+
+  <orio-tag
+    v-for="active in filters.$active"
+    :key="active.name"
+    :text="active.name"
+    variant="accent"
+  />
+  <orio-button v-if="filters.$active.length" @click="filters.$clearAll">
+    Clear all
+  </orio-button>
+</template>
+```
+
+## Quick reference — retrieve elsewhere
+
+```ts
+const filters = useFilter("appointments"); // same instance
+```
+
+## Related
+
+- `useUrlSync` — lazy-loaded when `url: true`.
+- `use-filter-onboarder` subagent — canonical patterns for filter
+  bars, chip rows, URL sync, and splitting filter UI across the page
+  tree.
+- Public API reference: `docs/composables/use-filter.md`.

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

@@ -0,0 +1,68 @@
+---
+kind: composable
+category: Composables
+purpose: fuzzy search, client-side filter, in-memory search, search-as-you-type
+short: typed Fuse.js wrapper that returns a computed list of matched items (strings or objects)
+invariants: false
+---
+
+# useFuzzySearch — agent-only invariants
+
+`useFuzzySearch(dataSource, search, options?)` is a thin wrapper around
+`@vueuse/integrations/useFuse`. It accepts either a `string[]` (no options)
+or a `T[]` of objects (with `FuseOptions<T>`) and returns a `ComputedRef`
+of matches — items only, no scores.
+
+## Invariants
+
+- **Two overloads**:
+  - `useFuzzySearch(dataSource: MaybeRef<string[]>, search: MaybeRef<string>)`
+    → matches against the strings directly.
+  - `useFuzzySearch<T>(dataSource: MaybeRef<T[]>, search: MaybeRef<string>, options: FuseOptions<T>)`
+    → matches against keys you specify in `options.keys`.
+- **`matchAllWhenSearchEmpty: true`** is forced — when `search` is `""`,
+  the returned list equals the full dataSource. No empty results on
+  empty query.
+- **Returns a `ComputedRef`**, so it updates as `search` or `dataSource`
+  changes (when passed as refs).
+- **The result is item-only**, not Fuse's `{ item, score }` records.
+  Score data is not exposed — if you need it, use `useFuse` directly.
+
+## Gotchas
+
+- **No debouncing.** Every keystroke runs the match against the full
+  dataset. For very large lists (10k+ items) or expensive options,
+  debounce `search` upstream.
+- **No highlighting of matched substrings.** Use `useFuse` directly if
+  you need the match indices for highlighting.
+- **`MaybeRef` means raw arrays work too** — but they won't be
+  reactive. Wrap in `ref` / `computed` if the underlying data changes.
+
+## Quick reference — string list
+
+```ts
+import { ref } from "vue";
+import { useFuzzySearch } from "../composables/useFuzzySearch";
+
+const query = ref("");
+const colors = ["red", "green", "blue", "yellow"];
+const matches = useFuzzySearch(colors, query);
+```
+
+## Quick reference — object list
+
+```ts
+interface User { id: string; name: string; email: string }
+const users = ref<User[]>([...]);
+const query = ref("");
+const matches = useFuzzySearch(users, query, {
+  keys: ["name", "email"],
+  threshold: 0.3,
+});
+```
+
+## Related
+
+- `<orio-selector>` — pair with this composable + the `#options-addon`
+  slot to build a filterable dropdown.
+- Public API reference: `docs/composables/use-fuzzy-search.md`.

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

@@ -0,0 +1,80 @@
+---
+kind: composable
+category: Composables
+purpose: inertia, momentum decay for gestures, fling-and-decelerate, momentum scroll
+short: post-drag momentum loop that calls a tick callback with decaying velocity each frame
+invariants: true
+---
+
+# useInertia — agent-only invariants
+
+`useInertia(onTick, options?)` runs a `requestAnimationFrame` loop that
+decays velocity by `friction` each frame and calls `onTick(vx, vy)`. The
+consumer applies the delta to its own state (pan offset, scroll, etc.).
+
+## Invariants
+
+- **`onTick(dx, dy)`** is called every frame while velocity exceeds
+  `minVelocity` (default `0.5`). The consumer is responsible for
+  applying the delta to its state.
+- **`friction` defaults to `0.92`** — velocity multiplier per frame.
+  Lower = quicker decay.
+- **`trackMove(dx, dy)`** must be called on every pointermove during
+  the drag — it captures the velocity from the delta and time since
+  the last call (`16 / dt` factor to normalize to ~60fps).
+- **`resetTime()`** must be called at drag start (and on
+  resume-after-release) so the first `trackMove` doesn't compute a
+  velocity from a stale timestamp.
+- **`release()`** must be called on drag end. It starts the inertia
+  loop only if:
+  - The last `trackMove` was less than 50ms ago, AND
+  - The captured velocity exceeds `minVelocity`.
+  Otherwise it does nothing — slow / paused releases don't fling.
+- **`stop()`** cancels any in-flight inertia and zeroes velocity. Call
+  it on a new pointer-down to interrupt momentum.
+- **Time-gap larger than 100ms in `trackMove` resets velocity to 0** —
+  catching a pause mid-drag prevents a stale fling on release.
+
+## Gotchas
+
+- **The composable owns no DOM**. It's just math + RAF. The consumer
+  must wire `trackMove` to `pointermove`, `release` to `pointerup`,
+  `stop` to new `pointerdown`, `resetTime` to drag-start.
+- **Velocity units are "pixels per ~16ms frame"** because of the
+  `16 / dt` normalization. The `onTick` deltas can be directly applied
+  to translate values without further scaling.
+- **No max-velocity clamp.** Very fast flings produce very fast inertia
+  — clamp upstream if needed.
+- **No multi-axis independence**: friction is symmetric. To decay axes
+  at different rates, scale `dx` / `dy` inside `onTick`.
+
+## Quick reference
+
+```ts
+import { useInertia } from "../composables/useInertia";
+
+const tx = ref(0);
+const ty = ref(0);
+
+const inertia = useInertia(
+  (dx, dy) => {
+    tx.value += dx;
+    ty.value += dy;
+  },
+  { friction: 0.9, minVelocity: 0.3 },
+);
+
+function onPointerDown() { inertia.stop(); inertia.resetTime(); }
+function onPointerMove(dx: number, dy: number) {
+  tx.value += dx;
+  ty.value += dy;
+  inertia.trackMove(dx, dy);
+}
+function onPointerUp() { inertia.release(); }
+```
+
+## Related
+
+- `<orio-zoomable-container>` — uses this for post-pan momentum.
+- `<orio-canvas>` — same.
+- Public API reference: `docs/composables/use-inertia.md`.