orio-ui 1.24.0 → 1.28.0

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

@@ -0,0 +1,57 @@
+---
+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
+`ControlElement.USAGE.md` first — most of the contract lives there.
+
+## Invariants
+
+- **Extends `ControlProps`** with one override: `layout?: InputLayout` where
+  `InputLayout = ControlLayout | "inner"`. The extra `"inner"` is an
+  Input-specific mode that floats the label inside the input chrome.
+- **`layout="inner"` translates internally** to `layout="vertical"` on
+  ControlElement and adds an `.inner` class on the wrapper. The label
+  reposition is driven by `:deep()` styles on ControlElement internals — no
+  duplicate label DOM is created.
+- **The `control` slot bag is spread onto the inner `<input>`** alongside
+  `$attrs`: `v-bind="{ ...$attrs, ...control }"`. Attrs like `type`,
+  `autocomplete`, `placeholder`, `inputmode` work on `<orio-input>` and land
+  on the underlying `<input>`.
+- **v-model is `string`** (default `""`). For numeric input use
+  `<orio-number-input>` instead.
+
+## Gotchas
+
+- The `.slot-wrapper` uses `display: flex; align-items: center;` so `before`
+  and `after` slots sit inline with the input. Don't add wrapping divs inside
+  those slots — they'll break alignment.
+- `:placeholder-shown` is used internally for the inner-label "empty" state.
+  If you pass an empty placeholder, the inner-label trick still works because
+  the wrapper sets `placeholder=" "` upstream when needed.
+- The default browser input border is removed; the visible border lives on
+  `.slot-wrapper`. Custom inputs swapped in via slots will not inherit it —
+  prefer `before`/`after` slots over replacing the input.
+
+## Quick reference
+
+```vue
+<orio-input
+  v-model="email"
+  label="Email"
+  layout="inner"
+  type="email"
+  autocomplete="email"
+  :error="emailError"
+>
+  <template #before>
+    <orio-icon name="mail" />
+  </template>
+</orio-input>
+```

package/dist/runtime/components/Input.vue

@@ -7,20 +7,30 @@ const props = defineProps({
   id: { type: String, required: false },
   label: { 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 modelValue = defineModel({ type: String, ...{ default: "" } });
 </script>
 
 <template>
   <orio-control-element
-    v-slot="{ id }"
+    v-slot="{ control }"
     v-bind="props"
     :layout="layout === 'inner' ? 'vertical' : layout"
     :class="{ inner: layout === 'inner' }"
   >
     <slot name="before" />
-    <input :id v-model="modelValue" type="text" v-bind="$attrs" />
+    <input
+      v-model="modelValue"
+      type="text"
+      v-bind="{ ...$attrs, ...control }"
+    />
     <slot name="after" />
   </orio-control-element>
 </template>

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

@@ -0,0 +1,72 @@
+---
+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.
+
+## Invariants
+
+- **Teleported to `<body>`.** Renders outside the parent DOM subtree. Any
+  CSS that targets `.modal` from a parent will not apply; scope styles via
+  `:deep()` from a parent or write global styles.
+- **`origin` prop drives the open animation.** Pass the `getBoundingClientRect`
+  of the element that triggered the open (e.g. the clicked button) to
+  animate the modal **from** that rect to centered. Pass `null` to fade in
+  at center with no scale-from.
+- **`v-model:show`** controls visibility. Backdrop click closes (`@click.self`
+  on the overlay). The default close button (rendered when no `header`
+  slot is supplied) also toggles `show`.
+- **Body scroll lock** is applied automatically while `show` is true, via
+  `useScrollLock` from `@vueuse/core`. SSR-safe: ref defaults to `false`
+  on the server.
+- **Header/footer are auto-hidden** when no `title` prop and no
+  `#header`/`#footer` slot is present. The content section (`#default`)
+  always renders.
+
+## Gotchas
+
+- Multiple modals stacked at once will all lock body scroll; closing one
+  releases the lock for all. If you nest modals, manage the lock yourself.
+- `origin`'s `width` / `height` should be the trigger's rendered size, not
+  the modal's. The animation derives the inverse scale from
+  `width / modalWidth` — wrong size = visible jump.
+- The component uses inline styles via direct `.style.transform`
+  assignment on the wrapper ref. Do not animate `transform` from outside;
+  the component will overwrite it on the next open.
+
+## Quick reference
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+const open = ref(false);
+const origin = ref<DOMRect | null>(null);
+
+function trigger(event: MouseEvent) {
+  origin.value = (event.currentTarget as HTMLElement).getBoundingClientRect();
+  open.value = true;
+}
+</script>
+
+<template>
+  <orio-button @click="trigger">Open settings</orio-button>
+
+  <orio-modal v-model:show="open" :origin="origin" title="Settings">
+    <p>Modal body…</p>
+    <template #footer>
+      <orio-button @click="open = false">Done</orio-button>
+    </template>
+  </orio-modal>
+</template>
+```
+
+## Related
+
+- `useModal` composable — programmatic open/close API without managing
+  `show` yourself. See `docs/composables/use-modal.md`.

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

@@ -1,7 +1,6 @@
 import type { ControlProps } from "./ControlElement.vue.js";
 interface Props extends ControlProps {
     icon?: string;
-    disabled?: boolean;
     active?: boolean;
 }
 declare var __VLS_8: {}, __VLS_15: {};

package/dist/runtime/components/NavButton.vue

@@ -2,7 +2,6 @@
 import { computed, toRefs, useSlots } from "vue";
 const props = defineProps({
   icon: { type: String, required: false },
-  disabled: { type: Boolean, required: false },
   active: { type: Boolean, required: false, default: false },
   appearance: { type: String, required: false },
   error: { type: [String, null], required: false },
@@ -11,7 +10,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 { disabled, active } = toRefs(props);
 const slots = useSlots();
@@ -28,11 +33,10 @@ function click(event) {
 </script>
 
 <template>
-  <orio-control-element v-bind="props">
+  <orio-control-element v-slot="{ control }" v-bind="props">
     <button
-      v-bind="$attrs"
+      v-bind="{ ...$attrs, ...control }"
       :class="{ 'icon-only': isIconOnly, active }"
-      :disabled
       :aria-current="active ? 'page' : void 0"
       @click="click"
     >

package/dist/runtime/components/NavButton.vue.d.ts

@@ -1,7 +1,6 @@
 import type { ControlProps } from "./ControlElement.vue.js";
 interface Props extends ControlProps {
     icon?: string;
-    disabled?: boolean;
     active?: boolean;
 }
 declare var __VLS_8: {}, __VLS_15: {};

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

@@ -6,14 +6,19 @@ defineProps({
   max: { type: Number, required: false, default: void 0 },
   step: { type: Number, required: false, default: 1 },
   decimalPlaces: { type: Number, required: false, default: 0 },
-  disabled: { type: Boolean, required: false, default: false },
   appearance: { type: String, required: false },
   error: { type: [String, null], required: false },
   group: { type: Boolean, required: false },
   id: { type: String, required: false },
   label: { 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, default: false },
+  required: { type: Boolean, required: false },
+  name: { type: String, required: false },
+  ariaLabel: { type: String, required: false }
 });
 const modelValue = defineModel({ type: Number, ...{ default: 0 } });
 const { pressAndHold, stop } = usePressAndHold();

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

@@ -0,0 +1,74 @@
+---
+kind: component
+category: Form inputs
+purpose: number input, numeric input, custom-control numeric stepper
+short: numeric input base with overlay controls slot; pair with Horizontal/Vertical variants for ready-made spinners
+invariants: true
+---
+
+# NumberInput — agent-only invariants
+
+`<orio-number-input>` is the **base** numeric input. By itself it renders a
+`<input type="number">` with no spinner. Custom step controls go in the
+`#controls` slot. For ready-made stepper UIs, use
+`<orio-number-input-horizontal>` or `<orio-number-input-vertical>`.
+
+## Invariants
+
+- **Extends `NumberInputProps`** (exported from this file): `ControlProps`
+  minus `layout`, plus `layout?: InputLayout`, `min`, `max`, `step`,
+  `decimalPlaces`. Same `"inner"` layout trick as Input/Textarea.
+- **v-model is `number`** (default `0`). Native input value is coerced via
+  Vue's `v-model.number` semantics.
+- **Validation runs on blur and on every increase/decrease.** Value is
+  clamped to `[min, max]` (if finite) and then rounded to `decimalPlaces`
+  via `toFixed`. Typing an out-of-range value is allowed *during* edit;
+  blur snaps it back.
+- **`decimalPlaces` defaults to `0`.** Decimal input requires both
+  `decimalPlaces` and a matching `step` (e.g. `:decimalPlaces="2" :step="0.01"`).
+- **Native webkit/firefox spin buttons are hidden** via CSS. Always
+  `appearance: textfield`.
+- **`#controls` slot overlays the input absolutely** with `pointer-events:
+  none` on the container and `:deep(button) { pointer-events: auto }`.
+  Only buttons receive clicks; the rest of the overlay passes through to
+  the input.
+- **`#controls` slot props**: `{ increase, decrease, isAtMax, isAtMin }`.
+  `increase`/`decrease` apply `step` and run validation; `isAtMax`/`isAtMin`
+  are `false` when `min`/`max` are undefined.
+- **`min`, `max`, `step`, `decimalPlaces` are stripped from `controlProps`**
+  before forwarding to ControlElement — they do not pollute the wrapper's
+  prop bag.
+- **`$attrs` is spread before `control`** on the inner `<input>`, same as
+  Input.
+
+## Gotchas
+
+- **No spinner UI without the slot or a variant.** A bare
+  `<orio-number-input v-model="n" />` renders nothing in the controls area.
+- **`min`/`max` of `0` are honored** because the check uses `Number.isFinite`,
+  not truthiness.
+- **Blur normalization rewrites the model.** Even if the user types a value
+  that is already valid, it gets re-`toFixed`d on blur — `"3"` becomes
+  `"3.00"` displayed when `decimalPlaces: 2`.
+- **Negative `step` is not blocked.** Passing `step: -1` makes increase
+  decrement.
+
+## Quick reference — custom controls slot
+
+```vue
+<template>
+  <orio-number-input v-model="quantity" :min="1" :max="99" :label="$t('cart.qty')">
+    <template #controls="{ increase, decrease, isAtMax, isAtMin }">
+      <orio-button :disabled="isAtMin" @click="decrease">−</orio-button>
+      <orio-button :disabled="isAtMax" @click="increase">+</orio-button>
+    </template>
+  </orio-number-input>
+</template>
+```
+
+## Related
+
+- `<orio-number-input-horizontal>` — pre-styled minus/plus on either side.
+- `<orio-number-input-vertical>` — pre-styled chevron stack on the right.
+- `<orio-input>` — when you want raw text, not a number.
+- Public API reference: `docs/components/number-input.md`.