orio-ui 1.24.0 → 1.28.0

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/useFilter.d.ts

@@ -0,0 +1,91 @@
+import { type ComputedRef, type Ref } from "vue";
+/**
+ * Definition of a single filter inside a group.
+ *
+ * `value` is both the initial value and the "empty" baseline used to compute
+ * `isActive` and to reset to via `clear()`.
+ */
+export interface FilterDefinition<Value = unknown> {
+    value: Value;
+}
+export type FilterConfig = Record<string, FilterDefinition>;
+export interface FilterOptions {
+    /**
+     * When true, the group's state is mirrored to URL query params via
+     * `useUrlSync`. The dependency is loaded lazily — `useUrlSync` (and its
+     * `#imports` use of `useRoute`) is never touched unless this flag is set,
+     * keeping `useFilter` runnable outside of a Nuxt context.
+     *
+     * Filter names become top-level URL keys; avoid colliding names across
+     * multiple URL-synced groups on the same page.
+     */
+    url?: boolean;
+}
+/**
+ * Bindable prop bag — spread onto any `v-model`-compatible component:
+ *   `<orio-selector v-bind="filters.category" :options="..." />`
+ */
+export interface FilterBind<Value = unknown> {
+    modelValue: Value;
+    "onUpdate:modelValue": (value: Value) => void;
+}
+/** Per-filter helpers accessed via `filters.$.<name>`. */
+export interface FilterHelpers<Value = unknown> {
+    value: Value;
+    initial: Value;
+    isActive: boolean;
+    clear: () => void;
+}
+export interface ActiveFilter {
+    name: string;
+    value: unknown;
+    clear: () => void;
+}
+export type FilterGroup<Config extends FilterConfig> = {
+    [Key in keyof Config]: FilterBind<Config[Key]["value"]>;
+} & {
+    $: {
+        [Key in keyof Config]: FilterHelpers<Config[Key]["value"]>;
+    };
+    $active: ComputedRef<ActiveFilter[]>;
+    $clearAll: () => void;
+    $state: Ref<Record<string, unknown>>;
+};
+/**
+ * Define or retrieve a named filter group.
+ *
+ * Define once anywhere in the page (setup, layout, store). Retrieve the same
+ * instance elsewhere by id — any component that knows the id can read and
+ * mutate the same reactive state, regardless of where it lives in the tree.
+ *
+ * @example Define
+ * ```ts
+ * const filters = useFilter('appointments', {
+ *   category:  { value: null },
+ *   status:    { value: [] as string[] },
+ *   dateRange: { value: { from: null, to: null } },
+ * })
+ * ```
+ *
+ * @example Bind to any v-model component
+ * ```vue
+ * <orio-selector v-bind="filters.category" :options="categories" />
+ * ```
+ *
+ * @example Retrieve elsewhere
+ * ```ts
+ * const filters = useFilter('appointments')
+ * ```
+ *
+ * @example Mirror to URL (Nuxt only)
+ * ```ts
+ * const filters = useFilter('appointments', config, { url: true })
+ * ```
+ */
+export declare function useFilter<Config extends FilterConfig>(id: string, config: Config, options?: FilterOptions): FilterGroup<Config>;
+export declare function useFilter(id: string): FilterGroup<FilterConfig>;
+/**
+ * Remove a filter group from the registry. Use in SPAs where filter groups
+ * are page-scoped and should not leak between routes.
+ */
+export declare function disposeFilter(id: string): void;

package/dist/runtime/composables/useFilter.js

@@ -0,0 +1,111 @@
+import {
+  computed,
+  effectScope,
+  ref
+} from "vue";
+const registry = /* @__PURE__ */ new Map();
+const urlSyncScopes = /* @__PURE__ */ new Map();
+export function useFilter(id, config, options = {}) {
+  const existing = registry.get(id);
+  if (existing) {
+    if (config) {
+      console.warn(
+        `[useFilter] group "${id}" is already defined \u2014 ignoring new config.`
+      );
+    }
+    return existing;
+  }
+  if (!config) {
+    throw new Error(
+      `[useFilter] group "${id}" is not defined. Pass a config on the first call.`
+    );
+  }
+  const initial = {};
+  for (const [name, definition] of Object.entries(config)) {
+    initial[name] = clone(definition.value);
+  }
+  const state = ref({ ...initial });
+  if (options.url) {
+    const scope = effectScope(true);
+    urlSyncScopes.set(id, scope);
+    void import("./useUrlSync.js").then(({ useUrlSync }) => {
+      scope.run(() => useUrlSync(state, Object.keys(config)));
+    });
+  }
+  const handle = {};
+  const helpers = {};
+  for (const name of Object.keys(config)) {
+    helpers[name] = {
+      get value() {
+        return state.value[name];
+      },
+      get initial() {
+        return initial[name];
+      },
+      get isActive() {
+        return !isEqual(state.value[name], initial[name]);
+      },
+      clear() {
+        state.value[name] = clone(initial[name]);
+      }
+    };
+    Object.defineProperty(handle, name, {
+      enumerable: true,
+      value: {
+        get modelValue() {
+          return state.value[name];
+        },
+        "onUpdate:modelValue": (value) => {
+          state.value[name] = value;
+        }
+      }
+    });
+  }
+  Object.defineProperty(handle, "$", { value: helpers });
+  Object.defineProperty(handle, "$active", {
+    value: computed(
+      () => Object.keys(config).flatMap((name) => {
+        const helper = helpers[name];
+        return helper.isActive ? [{ name, value: helper.value, clear: helper.clear }] : [];
+      })
+    )
+  });
+  Object.defineProperty(handle, "$clearAll", {
+    value: () => {
+      for (const name of Object.keys(config)) {
+        state.value[name] = clone(initial[name]);
+      }
+    }
+  });
+  Object.defineProperty(handle, "$state", { value: state });
+  registry.set(id, handle);
+  return handle;
+}
+export function disposeFilter(id) {
+  urlSyncScopes.get(id)?.stop();
+  urlSyncScopes.delete(id);
+  registry.delete(id);
+}
+function clone(value) {
+  if (value === null || typeof value !== "object") return value;
+  return structuredClone(value);
+}
+function isEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object") return false;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((item, index) => isEqual(item, b[index]));
+  }
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  return keysA.every(
+    (key) => isEqual(
+      a[key],
+      b[key]
+    )
+  );
+}

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