orio-ui 1.27.0 → 1.28.1

package/dist/runtime/components/EmptyState.USAGE.md

@@ -0,0 +1,65 @@
+---
+kind: component
+category: Buttons & indicators
+purpose: empty state, no-results placeholder, blank slate, empty list
+short: centered empty-list placeholder with optional icon, title, description, and action slot
+invariants: true
+---
+
+# EmptyState — agent-only invariants
+
+`<orio-empty-state>` is a centered placeholder for empty lists, no-search-
+results screens, and similar blank slates.
+
+## Invariants
+
+- **`title` is required.** Renders as `<orio-view-text type="title">` —
+  size scales with the empty-state `size` (large → medium title, others →
+  small title).
+- **`description` is optional**, max-width `30ch`. Wraps after that.
+- **`icon` is optional.** Rendered as `<orio-icon>` above the title with
+  reduced opacity (`0.5`). Icon size scales with `size`:
+  `small` → 2rem, `medium` → 3rem, `large` → 4rem.
+- **Default slot is rendered after the description** — typically a CTA
+  button.
+- **Always vertically stacked, centered, text-centered.** No prop to
+  switch to horizontal.
+- **`size`**: `"small"` / `"medium"` (default) / `"large"`. Affects
+  padding, gap, and icon size — not title color or weight.
+
+## Gotchas
+
+- **`title` and `description` are plain strings.** Pass i18n keys
+  through `$t()` from the parent; no `#title` / `#description` slot.
+  For inline `<strong>` or links inside copy, build a custom empty
+  state from view primitives.
+- **Slot CTA spacing**: the default slot inherits the column gap
+  (`0.25` / `0.5` / `1rem` per size). Buttons sit tight against the
+  description — add margin if you need separation.
+- **Used internally by `<orio-selector>` as the `no-options` default.**
+  When overriding via the `#no-options` slot, keep the layout similar
+  for visual consistency.
+
+## Quick reference
+
+```vue
+<template>
+  <orio-empty-state
+    icon="inbox"
+    :title="$t('inbox.empty.title')"
+    :description="$t('inbox.empty.description')"
+    size="large"
+  >
+    <orio-button @click="createMessage">
+      {{ $t("inbox.empty.compose") }}
+    </orio-button>
+  </orio-empty-state>
+</template>
+```
+
+## Related
+
+- `<orio-view-text>` — used internally for title/description.
+- `<orio-banner>` — for inline notice strips instead of full-block
+  empty states.
+- Public API reference: `docs/components/empty-state.md`.

package/dist/runtime/components/Form.USAGE.md

@@ -0,0 +1,102 @@
+---
+kind: component
+category: Form inputs
+purpose: form wrapper, submission, validation surface, auto-bind form model
+short: form wrapper that auto-binds child controls by `name` prop to a single object v-model
+invariants: true
+---
+
+# Form — agent-only invariants
+
+`<orio-form>` is a form wrapper that walks its slot vnodes and **auto-binds
+child controls to a single object v-model** by matching each child's
+`name` prop to a key (or dot path) in the model. Generic over `T extends
+object`.
+
+## Invariants
+
+- **v-model is an object `T`.** Each child with a `name="..."` prop
+  receives `modelValue` and `onUpdate:modelValue` cloned in via
+  `cloneVNode`. The user's hand-written v-model on that child is
+  overridden if `name` matches a field.
+- **Auto-bind requires both `name` and a matching field path.** Children
+  without `name`, or with a `name` that doesn't resolve via `getByPath`,
+  render unchanged. Auto-bind is silent — no warning when a name doesn't
+  match.
+- **Dot-paths supported**: `name="user.email"` writes to `model.user.email`.
+  The intermediate path must already exist (`setByPath` no-ops if the
+  parent is missing).
+- **Children must follow the `modelValue` / `update:modelValue` contract.**
+  Auto-bind injects these props directly; v-model sugar is not used. Any
+  child that doesn't honor that pair is silently un-bound. All orio
+  form components do; custom children need to follow the contract.
+- **Slot walking is recursive.** Vnode children, slot functions, and slot
+  objects are all descended. Wrappers (`<div>` groupers, layout columns)
+  are transparent.
+- **`disabled` wraps the children in `<fieldset disabled>`** with
+  `display: contents` so nothing visual changes. The native `disabled`
+  attribute on the fieldset gates every form control inside (browser-
+  native behavior).
+- **`loading` adds `pointer-events: none`** plus 0.6 opacity on the form.
+  Visual + interaction lock without disabling form values.
+- **`novalidate` is set on the `<form>`** — HTML5 native validation
+  bubbles are off. Pair with `useValidation` for declarative checks.
+- **`@submit` emits a single `submit` event** after `preventDefault`. The
+  emit is gated by `disabled || loading`. There is **no** built-in submit
+  button — render `<orio-button type="submit">` (or similar) inside.
+
+## Gotchas
+
+- **No per-field error wiring.** `error` props on children are still
+  user-managed. The Form is only a binder, not a validator.
+- **Reactivity through `setByPath` requires mutable nested objects.** A
+  frozen / readonly model breaks silently. Use a plain ref'd object.
+- **Auto-bind clones the vnode** — keyed lists work, but if a child also
+  emits something other than `update:modelValue` via the same `onUpdate`
+  pattern, the clone replaces only the listed handlers.
+- **Slot is descended into every render** — performance scales linearly
+  with slot depth. For very large forms (hundreds of fields), consider
+  splitting into nested `<orio-form>`s by section.
+- **`name` collisions silently overwrite.** Two children with the same
+  `name` both bind to the same field; both updates write to the same
+  spot. Order is undefined.
+
+## Quick reference
+
+```vue
+<script setup lang="ts">
+interface Profile {
+  name: string;
+  email: string;
+  preferences: { newsletter: boolean };
+}
+
+const profile = ref<Profile>({
+  name: "",
+  email: "",
+  preferences: { newsletter: false },
+});
+
+function save() {
+  // Submit profile.value to API
+}
+</script>
+
+<template>
+  <orio-form v-model="profile" :loading="saving" @submit="save">
+    <orio-input name="name" :label="$t('profile.name')" />
+    <orio-input name="email" :label="$t('profile.email')" type="email" />
+    <orio-check-box name="preferences.newsletter">
+      {{ $t("profile.newsletter") }}
+    </orio-check-box>
+
+    <orio-button type="submit">{{ $t("common.save") }}</orio-button>
+  </orio-form>
+</template>
+```
+
+## Related
+
+- `useValidation` — declarative validation rules for form fields.
+- `<orio-control-element>` — wraps every form input with label/error.
+- Public API reference: `docs/components/form.md`.

package/dist/runtime/components/Icon.USAGE.md

@@ -0,0 +1,61 @@
+---
+kind: component
+category: Buttons & indicators
+purpose: icon, SVG renderer, glyph, symbol
+short: SVG icon renderer that pulls from `utils/icon-registry` and renders via v-html
+invariants: true
+---
+
+# Icon — agent-only invariants
+
+`<orio-icon>` renders an SVG icon from `utils/icon-registry` into a
+`<span>` via `v-html`. Unknown icon names render empty.
+
+## Invariants
+
+- **`name` is required.** Either a registered `IconName` (typed) or any
+  string. Unregistered names render as empty string (no visible
+  output, no warning).
+- **`size`**: `string | number`. A number is treated as pixels (`"24px"`).
+  A string is used verbatim (`"1.5em"`, `"2rem"`, `"100%"`). When
+  `undefined`, falls back to the CSS var `--control-icon-size` (default
+  `1.5em`).
+- **`color` defaults to `"currentColor"`** — the icon inherits parent
+  text color. Pass a CSS color string to override.
+- **`v-html` is used to inject the raw SVG markup.** The icon registry
+  is the trust boundary — never render dynamic / user-controlled SVG
+  strings through it.
+- **SVGs inside use `fill: currentColor`** so the `color` prop / parent
+  color flows through.
+- **`flex-shrink: 0`** is set on the span. The icon never shrinks inside
+  a flex layout — important for inline labels with overflow.
+- **The wrapper is `display: inline-flex; align-items: center; justify-content: center`**
+  so the SVG is centered when the size exceeds the SVG viewBox.
+
+## Gotchas
+
+- **Bypass-XSS surface is the registry.** Anything in `utils/icon-registry`
+  is rendered as raw HTML. Do not extend the registry with strings
+  derived from user input.
+- **Sizing a string `100%` requires a sized parent.** The span goes to
+  the size you pass; the inner SVG fills 100% of that.
+- **`color` is applied via inline style**, so it beats class-based
+  styling. To recolor via CSS class, omit the `color` prop.
+- **Spelling errors silently render nothing.** If an icon is missing
+  during dev, check the registry — there's no console warning.
+
+## Quick reference
+
+```vue
+<template>
+  <orio-icon name="check" :size="24" />
+  <orio-icon name="warning" size="1.5rem" color="var(--color-alert)" />
+  <orio-icon name="search" />
+</template>
+```
+
+## Related
+
+- `<orio-loading-spinner>` — thin wrapper for the `loading-loop` icon.
+- `utils/icon-registry` — the source of all available icon names.
+- Public API reference: `docs/components/icon.md`.

package/dist/runtime/components/Input.USAGE.md

@@ -1,3 +1,11 @@
+---
+kind: component
+category: Form inputs
+purpose: text input, single-line input
+short: text input wrapping ControlElement; supports inner-floating label layout
+invariants: true
+---
+
 # Input — agent-only invariants
 
 `<orio-input>` is the text input wrapping `ControlElement`. Read

package/dist/runtime/components/ListItem.USAGE.md

@@ -0,0 +1,84 @@
+---
+kind: component
+category: Media & misc
+purpose: list row, list item, selectable row, list entry
+short: `<li>` row with start/end slots and optional selectable checkbox-style behavior
+invariants: true
+---
+
+# ListItem — agent-only invariants
+
+`<orio-list-item>` is a `<li>` row with three content zones (start /
+center / end) and an optional selectable mode. It is also the row
+primitive used internally by `<orio-selector>`.
+
+## Invariants
+
+- **Renders an `<li>`.** Must be a child of `<ul>` / `<ol>` for valid
+  HTML. Rendering it loose works but breaks list semantics.
+- **`selectable` prop** turns the row into an interactive checkbox-style
+  control:
+  - `tabindex="0"` (keyboard focusable).
+  - `role="checkbox"` + `aria-checked` reflect `selected`.
+  - Click and Enter / Space toggle the v-model.
+  - `cursor: pointer`.
+- **v-model is `selected: boolean`.** Updates on toggle. Without
+  `selectable`, the model is still bound but no toggle handler runs.
+- **Three slots**:
+  - `#start` — left zone. **Only renders** when the slot is provided
+    OR `selectable` is true. When selectable and no slot, defaults to
+    `<orio-check-box :model-value="selected">`.
+  - `#default` — center content. Always renders, `flex-grow: 1`.
+  - `#end` — right zone. Only renders when the slot is provided.
+- **Selected state** uses `--color-accent` background and
+  `--color-accent-soft-darker` text. Hover swaps to surface bg when
+  not selected.
+- **Used internally by `<orio-selector>`** as `role="option"` rows. In
+  that usage the role gets overridden via `$attrs`.
+
+## Gotchas
+
+- **No multi-selection grouping.** A single ListItem holds one
+  selected boolean. For grouped list selection, wire each item's
+  `v-model:selected` to a parent array.
+- **Default `<orio-check-box>` in `#start`** uses bare props — it has
+  no label, no accent state of its own. If the row is `selected`, the
+  checkbox shows checked.
+- **Keyboard `Enter` and `Space` `.preventDefault()`** — Space won't
+  scroll the page, Enter won't submit a form. Useful, but
+  unconfigurable.
+- **Without `selectable`**, the row is still clickable but no toggle /
+  focus / role is applied. To make it a button-like row without a
+  checkbox-style toggle, wrap content in a real `<button>` inside
+  `#default`.
+
+## Quick reference
+
+```vue
+<template>
+  <ul>
+    <orio-list-item
+      v-for="item in items"
+      :key="item.id"
+      v-model:selected="item.selected"
+      selectable
+    >
+      <template #start>
+        <orio-icon :name="item.icon" />
+      </template>
+
+      {{ item.label }}
+
+      <template #end>
+        <orio-tag :text="item.badge" variant="accent" />
+      </template>
+    </orio-list-item>
+  </ul>
+</template>
+```
+
+## Related
+
+- `<orio-selector>` — uses this as listbox rows.
+- `<orio-check-box>` — default `#start` content when selectable.
+- Public API reference: `docs/components/list-item.md`.

package/dist/runtime/components/LoadingSpinner.USAGE.md

@@ -0,0 +1,50 @@
+---
+kind: component
+category: Buttons & indicators
+purpose: spinner, loading indicator, loading icon, busy indicator
+short: thin wrapper that renders the bundled `loading-loop` icon; no props
+invariants: false
+---
+
+# LoadingSpinner — agent-only invariants
+
+`<orio-loading-spinner>` renders the bundled `loading-loop` icon. That's
+it. There are **no props**, no slots, no emits.
+
+## Invariants
+
+- **Zero-prop wrapper.** Template is literally
+  `<orio-icon name="loading-loop" />`.
+- **Animation lives in the icon SVG itself** (via the registry's
+  `loading-loop` entry). The component does not apply any CSS animation.
+- **Size and color follow `<orio-icon>` defaults** — `1.5em` from
+  `--control-icon-size`, `currentColor`. Override via parent CSS:
+  `font-size`, `color`, or by passing direct CSS to a wrapper.
+- **Used internally by `<orio-button :loading>`** — when wiring loading
+  states into buttons, prefer `:loading="..."` on the button to swapping
+  in this spinner manually.
+
+## Gotchas
+
+- **No way to change spin direction, speed, or thickness.** The SVG is
+  fixed. For a custom spinner, render `<orio-icon>` with your own icon
+  name + CSS animation.
+- **Aria semantics are absent.** No `role="status"`, no
+  `aria-label`. For screen-reader announcement, wrap in a `<span
+  role="status" aria-label="Loading">` at the consumer.
+
+## Quick reference
+
+```vue
+<template>
+  <orio-loading-spinner v-if="loading" />
+</template>
+```
+
+## Related
+
+- `<orio-icon>` — under the hood; use it directly for non-spinner
+  glyphs.
+- `<orio-button :loading>` — preferred way to show busy state on
+  buttons.
+- Public API reference: `docs/components/loading-spinner.md`.

package/dist/runtime/components/LocaleSwitcher.USAGE.md

@@ -0,0 +1,73 @@
+---
+kind: component
+category: Media & misc
+purpose: locale switcher, language toggle, i18n switcher
+short: preconfigured Selector that mutates vue-i18n's locale; defaults to English + Ukrainian with flag emojis
+invariants: true
+---
+
+# LocaleSwitcher — agent-only invariants
+
+`<orio-locale-switcher>` is a thin wrapper around `<orio-selector>` that
+reads and writes `useI18n().locale` directly. Drop it anywhere in the app
+to give users a language toggle.
+
+## Invariants
+
+- **Mutates `useI18n().locale` on selection.** No model is exposed —
+  the side effect is the API.
+- **Default `locales`**:
+  ```ts
+  [
+    { code: "en", flag: "🇬🇧", label: "English" },
+    { code: "uk", flag: "🇺🇦", label: "Українська" },
+  ]
+  ```
+  Override with the `locales` prop if your app supports a different set.
+- **`LocaleOption` shape** (exported): `{ code, flag, label }`. All three
+  are strings; `flag` is rendered verbatim (emoji or any unicode).
+- **Selector wiring**: `field: "code"`, `optionName: "label"`. Active
+  option matches by `code === currentLocale`. Falls back to the first
+  locale if the current i18n locale isn't in the list.
+- **Custom `#trigger-label` and `#option` slots** render `flag + label`
+  side-by-side with 0.5rem gap.
+- **Requires `useI18n` setup.** The component throws if called outside
+  a vue-i18n context.
+
+## Gotchas
+
+- **Direct locale mutation bypasses any persistence layer.** If your
+  app saves locale to cookies / localStorage / API, hook into
+  `useI18n().locale` from elsewhere — this component does not call
+  any side effect beyond the i18n update.
+- **Flag emojis depend on font support.** macOS / iOS render them
+  correctly; Windows often shows letter pairs (e.g. "GB", "UA"). For
+  cross-platform consistency, swap to icons via a custom `locales`
+  prop with icon names + a custom `#option`/`#trigger-label`.
+- **No client/server hydration story.** If the locale is mutated
+  before vue-i18n is hydrated on the client, mismatches can occur.
+  Best to initialize locale in your app setup and let this switcher
+  only handle user-driven changes.
+
+## Quick reference
+
+```vue
+<template>
+  <orio-locale-switcher />
+
+  <orio-locale-switcher
+    :locales="[
+      { code: 'en', flag: '🇺🇸', label: 'English' },
+      { code: 'es', flag: '🇪🇸', label: 'Español' },
+      { code: 'pt', flag: '🇧🇷', label: 'Português' },
+    ]"
+  />
+</template>
+```
+
+## Related
+
+- `<orio-selector>` — under the hood. Build your own switcher from
+  Selector if you need different side effects (e.g. routing).
+- Public API reference: `docs/components/locale-switcher.md` (if
+  present).

package/dist/runtime/components/Modal.USAGE.md

@@ -1,3 +1,11 @@
+---
+kind: component
+category: Layout & containers
+purpose: modal, dialog, popup overlay, lightbox
+short: teleported overlay dialog with open-from-origin animation
+invariants: true
+---
+
 # Modal — agent-only invariants
 
 `<orio-modal>` is the teleported overlay dialog.

package/dist/runtime/components/NavButton.USAGE.md

@@ -0,0 +1,80 @@
+---
+kind: component
+category: Buttons & indicators
+purpose: nav button, link-styled button, navigation item, sidebar item
+short: bare nav-styled button with `active` state and `aria-current="page"` for the current route
+invariants: true
+---
+
+# NavButton — agent-only invariants
+
+`<orio-nav-button>` is a transparent, text-styled button for navigation
+menus and tab bars. It is not a `<router-link>` — wrap it or wire
+navigation in the `click` handler yourself.
+
+## Invariants
+
+- **`active` prop is the "is this the current item" flag.** When true:
+  - Text becomes accent color, font-weight 600.
+  - `aria-current="page"` is set on the inner `<button>`.
+  - `undefined` (not removed) otherwise — so it doesn't appear in the
+    DOM at all when inactive.
+- **`icon` prop OR `#icon` slot** — same pattern as `<orio-button>`.
+- **Icon-only mode is auto-detected** (icon + no default slot) →
+  `border-radius: 50%`, `aspect-ratio: 1`, `padding: var(--control-py)`.
+- **No `variant` prop.** One look only — transparent background, text
+  color, no border.
+- **`disabled` blocks click** and applies 0.5 opacity + `cursor:
+  not-allowed`.
+- **Only emits `click`.** No mousedown/mouseup like `<orio-button>`.
+- **Focus ring**: `outline: 2px solid var(--color-accent)` with
+  `outline-offset: 2px`. Keyboard-only via `:focus-visible`.
+
+## Gotchas
+
+- **Not a router link.** No `to`, no `href`. Wire navigation in
+  `@click`. If a real anchor is needed for a11y / right-click-to-open,
+  fall back to your router's link component.
+- **Same `$attrs` duplication caveat as `<orio-button>`** — attrs may
+  land on both the wrapper and the inner `<button>`.
+- **Active state is purely visual + ARIA**; the component does not
+  detect the current route. Compute `active` from `useRoute()` or your
+  router state.
+- **`type` defaults to `submit`** (native default). Pass `type="button"`
+  if mounted inside a form to avoid accidental submits.
+
+## Quick reference
+
+```vue
+<script setup lang="ts">
+import { useRoute, useRouter } from "vue-router";
+
+const route = useRoute();
+const router = useRouter();
+</script>
+
+<template>
+  <nav>
+    <orio-nav-button
+      icon="home"
+      :active="route.path === '/'"
+      @click="router.push('/')"
+    >
+      {{ $t("nav.home") }}
+    </orio-nav-button>
+
+    <orio-nav-button
+      icon="settings"
+      :active="route.path === '/settings'"
+      @click="router.push('/settings')"
+    >
+      {{ $t("nav.settings") }}
+    </orio-nav-button>
+  </nav>
+</template>
+```
+
+## Related
+
+- `<orio-button>` — primary actions; use that for CTAs.
+- Public API reference: `docs/components/nav-button.md`.

package/dist/runtime/components/NumberInput/Horizontal.USAGE.md

@@ -0,0 +1,61 @@
+---
+kind: component
+category: Form inputs
+purpose: number input horizontal, minus-plus stepper, quantity stepper
+short: number input variant with minus/plus buttons flanking the field and press-and-hold repeat
+invariants: true
+---
+
+# NumberInput/Horizontal — agent-only invariants
+
+`<orio-number-input-horizontal>` is a pre-styled wrapper around
+`<orio-number-input>` that renders minus/plus buttons on either side of the
+field. Read `NumberInput/USAGE.md` first — this variant inherits all of its
+contract.
+
+## Invariants
+
+- **Accepts the full `NumberInputProps` interface** plus a `disabled` prop
+  for the buttons. All props are forwarded via `v-bind="$props"`.
+- **Buttons use `usePressAndHold`** — `@mousedown` starts the auto-repeat,
+  `@mouseup`/`@mouseleave` stops it. Hold to ramp through a range.
+- **`disabled` and the per-button bound state both apply.** A minus button
+  is disabled when `disabled || isAtMin`; a plus button when
+  `disabled || isAtMax`.
+- **Input text is centered** (`text-align: center` via `:deep(.number-input)`).
+- **Controls are full-width inside the wrapper**: `justify-content: space-between`
+  with 3px horizontal padding. Buttons sit at the edges.
+- **`layout="inner"` is supported** — the label centers between the two
+  buttons (`left: 0; right: 0; text-align: center`).
+- **No keyboard auto-repeat.** Press-and-hold listens to mouse events
+  only; holding Enter on a focused button does not ramp.
+
+## Gotchas
+
+- **Buttons are `<orio-button appearance="minimal" variant="subdued">`** —
+  they take theme tokens but are not slotted. To swap iconography, fall
+  back to the base `<orio-number-input>` with a custom `#controls` slot.
+- **Touch behavior**: press-and-hold uses `@mousedown`/`@mouseup`. On touch
+  devices these may not fire reliably across all browsers — confirm on
+  iOS Safari if mobile is a target.
+
+## Quick reference
+
+```vue
+<template>
+  <orio-number-input-horizontal
+    v-model="quantity"
+    :min="0"
+    :max="10"
+    :step="1"
+    :label="$t('cart.quantity')"
+  />
+</template>
+```
+
+## Related
+
+- `<orio-number-input>` — the base; use it when you need custom button
+  iconography or layout.
+- `<orio-number-input-vertical>` — chevron-stack variant.
+- `usePressAndHold` — composable behind the auto-repeat.

package/dist/runtime/components/NumberInput/Horizontal.vue

@@ -31,6 +31,7 @@ const { pressAndHold, stop } = usePressAndHold();
         appearance="minimal"
         icon="minus"
         variant="subdued"
+        size="sm"
         :disabled="isAtMin || disabled"
         @mousedown="pressAndHold(decrease)"
         @mouseup="stop"
@@ -40,6 +41,7 @@ const { pressAndHold, stop } = usePressAndHold();
         appearance="minimal"
         icon="plus"
         variant="subdued"
+        size="sm"
         :disabled="isAtMax || disabled"
         @mousedown="pressAndHold(increase)"
         @mouseup="stop"
@@ -65,4 +67,7 @@ const { pressAndHold, stop } = usePressAndHold();
   right: 0;
   text-align: center;
 }
+.horizontal :deep(.control-group) {
+  z-index: 2;
+}
 </style>