npm - orio-ui - Versions diffs - 1.27.0 → 1.28.0 - Mend

orio-ui 1.27.0 → 1.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (64) hide show

package/README.md +76 -1
package/bin/orio-ui.mjs +72 -0
package/dist/agents/ROUTING.md +140 -0
package/dist/agents/component-finder.md +142 -0
package/dist/agents/component-worker.md +152 -0
package/dist/agents/snippet.md +6 -0
package/dist/module.json +1 -1
package/dist/runtime/components/AnimatedContainer.USAGE.md +79 -0
package/dist/runtime/components/Badge.USAGE.md +75 -0
package/dist/runtime/components/Banner.USAGE.md +52 -0
package/dist/runtime/components/Button.USAGE.md +78 -0
package/dist/runtime/components/Calendar.USAGE.md +8 -0
package/dist/runtime/components/Canvas/USAGE.md +8 -0
package/dist/runtime/components/CheckBox.USAGE.md +63 -0
package/dist/runtime/components/CheckboxGroup.USAGE.md +95 -0
package/dist/runtime/components/ControlElement.USAGE.md +8 -0
package/dist/runtime/components/DashedContainer.USAGE.md +65 -0
package/dist/runtime/components/EmptyState.USAGE.md +65 -0
package/dist/runtime/components/Form.USAGE.md +102 -0
package/dist/runtime/components/Icon.USAGE.md +61 -0
package/dist/runtime/components/Input.USAGE.md +8 -0
package/dist/runtime/components/ListItem.USAGE.md +84 -0
package/dist/runtime/components/LoadingSpinner.USAGE.md +50 -0
package/dist/runtime/components/LocaleSwitcher.USAGE.md +73 -0
package/dist/runtime/components/Modal.USAGE.md +8 -0
package/dist/runtime/components/NavButton.USAGE.md +80 -0
package/dist/runtime/components/NumberInput/Horizontal.USAGE.md +61 -0
package/dist/runtime/components/NumberInput/USAGE.md +74 -0
package/dist/runtime/components/NumberInput/Vertical.USAGE.md +55 -0
package/dist/runtime/components/Popover.USAGE.md +103 -0
package/dist/runtime/components/RadioButton.USAGE.md +72 -0
package/dist/runtime/components/Selector.USAGE.md +131 -0
package/dist/runtime/components/SwitchButton.USAGE.md +62 -0
package/dist/runtime/components/Tag.USAGE.md +51 -0
package/dist/runtime/components/TaggableSelector.USAGE.md +73 -0
package/dist/runtime/components/Textarea.USAGE.md +72 -0
package/dist/runtime/components/Tooltip.USAGE.md +84 -0
package/dist/runtime/components/ZoomableContainer.USAGE.md +108 -0
package/dist/runtime/components/date/Picker.USAGE.md +8 -0
package/dist/runtime/components/date/PickerTrigger.USAGE.md +65 -0
package/dist/runtime/components/date/RangePicker.USAGE.md +97 -0
package/dist/runtime/components/gallery/Carousel.USAGE.md +98 -0
package/dist/runtime/components/gallery/CarouselPreview.USAGE.md +51 -0
package/dist/runtime/components/upload/USAGE.md +91 -0
package/dist/runtime/components/view/Dates.USAGE.md +67 -0
package/dist/runtime/components/view/KeyBinds.USAGE.md +58 -0
package/dist/runtime/components/view/Separator.USAGE.md +57 -0
package/dist/runtime/components/view/Text.USAGE.md +68 -0
package/dist/runtime/composables/useApi.USAGE.md +64 -0
package/dist/runtime/composables/useControlSize.USAGE.md +73 -0
package/dist/runtime/composables/useDecimalFormatter.USAGE.md +72 -0
package/dist/runtime/composables/useFilter.USAGE.md +120 -0
package/dist/runtime/composables/useFuzzySearch.USAGE.md +68 -0
package/dist/runtime/composables/useInertia.USAGE.md +80 -0
package/dist/runtime/composables/useListKeyboard.USAGE.md +97 -0
package/dist/runtime/composables/useModal.USAGE.md +82 -0
package/dist/runtime/composables/usePinchZoom.USAGE.md +95 -0
package/dist/runtime/composables/usePressAndHold.USAGE.md +70 -0
package/dist/runtime/composables/useRovingGrid.USAGE.md +106 -0
package/dist/runtime/composables/useSound.USAGE.md +74 -0
package/dist/runtime/composables/useTheme.USAGE.md +76 -0
package/dist/runtime/composables/useUrlSync.USAGE.md +91 -0
package/dist/runtime/composables/useValidation.USAGE.md +100 -0
package/package.json +12 -2

package/dist/runtime/components/Popover.USAGE.md ADDED Viewed

@@ -0,0 +1,103 @@
+---
+kind: component
+category: Layout & containers
+purpose: popover, anchored floating panel, dropdown menu base, contextual menu
+short: anchored floating panel teleported to body with auto-flip placement and click-outside dismissal
+invariants: true
+---
+# Popover — agent-only invariants
+`<orio-popover>` anchors a floating panel to a trigger element. The trigger
+is the default slot; the panel content is the `#content` slot.
+## Invariants
+- **Two slots, both get `{ toggle, isOpen }`.** Default slot wraps the
+  trigger; `#content` is the floating panel. You **must** call `toggle`
+  yourself — the component does not auto-attach a click handler to the
+  trigger.
+- **Panel is teleported to `<body>`**. Parent CSS scoping does not reach
+  it. Use `:deep()` from a parent, global styles, or scope the panel via
+  classes you control.
+- **`toggle(force?)`** — `toggle(true)` forces open, `toggle(false)` forces
+  close, `toggle()` flips. While `disabled` is true, all three are no-ops.
+- **`position` syntax is `main-sub`, not "diagonal".** `top-left` means
+  *above the trigger* with the panel's **right edge** aligned to the
+  trigger's right edge — NOT "above and to the left of the trigger".
+  `left-top` means *left of the trigger* with **top** edges aligned.
+  Single-word values (`"top"`, `"left"`, …) center on the cross axis.
+- **Placement auto-flips.** If the requested position doesn't fit in the
+  viewport, the component tries the opposite-main, then center variants,
+  then perpendicular axes — first fit wins. `currentPosition` is the
+  resolved value. No way to disable the fallback.
+- **`offset` is gap in px between trigger and panel.** Default `10`.
+- **Click outside closes**, with `triggerRef` in the ignore list.
+- **Reposition on scroll/resize** uses capture-phase listeners on `window`,
+  so it catches nested scrolling ancestors. Panel resizes via
+  `useElementBounding` also trigger reposition.
+- **No keyboard support.** No Esc-to-close, no focus trap, no return-focus.
+  If you need those, wire them at the consumer level on the `#content`
+  slot.
+- **No visual chrome.** The wrapper is `background: transparent; border: 0;
+  position: fixed; z-index: 999999`. The `#content` slot must render its
+  own surface (card, panel, menu).
+## Gotchas
+- **Trigger must accept the slot props.** Use `v-slot="{ toggle, isOpen }"`
+  on the default slot — without it, the trigger has no way to open the
+  popover.
+- **No arrow / caret.** Add your own pseudo-element on the content slot if
+  needed; the wrapper offers no anchor point.
+- **First-paint flicker is avoided via `visibility: hidden`** during
+  measurement, but only briefly. If your trigger animates while opening,
+  the trigger rect read on `nextTick` may be mid-animation — measure after
+  the animation, or open without animating the trigger.
+- **`appear` transition fires only on first paint.** Reopening the same
+  popover does not re-trigger `appear` — only the standard enter
+  transition. Make sure your `animate-fade-slide` styles cover both.
+- **z-index is hard-coded to `999999`.** Stacking with other body-teleports
+  (Modal at the same z-index) is order-dependent — the later-mounted
+  element wins. Mount-order is not stable across HMR.
+- **No `v-model:show`.** State is internal. Drive it through `toggle` (via
+  the slot prop) or by mounting/unmounting the component with `v-if`.
+## Quick reference
+```vue
+<template>
+  <orio-popover position="bottom-left" :offset="8">
+    <template #default="{ toggle, isOpen }">
+      <orio-button @click="toggle()">
+        Menu {{ isOpen ? "▴" : "▾" }}
+      </orio-button>
+    </template>
+    <template #content="{ toggle }">
+      <div class="menu-panel">
+        <button @click="onEdit(); toggle(false)">Edit</button>
+        <button @click="onDelete(); toggle(false)">Delete</button>
+      </div>
+    </template>
+  </orio-popover>
+</template>
+<style scoped>
+.menu-panel {
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: var(--border-radius-md);
+  padding: 0.5rem;
+  display: flex;
+  flex-direction: column;
+}
+</style>
+```
+## Related
+- `<orio-tooltip>` — for hover/focus hints; do not use Popover for tooltips.
+- `<orio-modal>` — when you need a backdrop, focus trap, and centered
+  dialog.
+- Public API reference: `docs/components/popover.md`.

package/dist/runtime/components/RadioButton.USAGE.md ADDED Viewed

@@ -0,0 +1,72 @@
+---
+kind: component
+category: Form inputs
+purpose: radio, radio button, single-choice from group
+short: single radio option wrapping ControlElement; group by sharing the same v-model
+invariants: true
+---
+# RadioButton — agent-only invariants
+`<orio-radio-button>` is one radio option. There is **no `RadioGroup`** —
+grouping is done by sharing the same v-model across multiple instances.
+## Invariants
+- **`value` is the option's payload.** It is what gets written to v-model
+  when this radio is selected. Comparison is strict (`===`).
+- **v-model is `unknown`** (typically `string` / `number` / object id) —
+  the selected value. Two `<orio-radio-button>`s with the same v-model
+  form a group; whichever value matches the model is checked.
+- **`text` prop _or_ default slot** for the inline label. Slot wins.
+  Render nothing if both are absent.
+- **`hideLabel` prop** applies `.sr-only` to the text — visually hidden,
+  still announced by screen readers. Use for icon-only radios that still
+  need an accessible name.
+- **Visual is a CSS-only rounded box** with `::after` for the inner dot
+  when checked.
+- **Native `<input type="radio">` has `tabindex="-1"`** in the template.
+  Default tab order skips it; clicking the label still toggles. If you
+  need keyboard arrow-key roving across the group, layer that on top —
+  it is not provided.
+- **No `name` HTML attribute by default.** Two browser radios with the
+  same DOM `name` form a native group; this component groups via Vue
+  v-model only. Set `name` via `$attrs` if a `<form>` submission needs
+  the radio group serialized natively.
+## Gotchas
+- **Multiple instances bound to the same v-model are not visually grouped.**
+  Layout (column / row) is up to the consumer — wrap them in a div or
+  `<orio-control-element group>` with a shared label.
+- **Object values must be the same reference** as the one stored in the
+  model. Comparing `{ id: 1 }` to a new `{ id: 1 }` is false. Bind to
+  primitive ids when possible.
+- **No "deselect" behavior.** Once a radio is selected, clicking it again
+  does not clear. To allow clearing, expose a separate "None" radio with
+  `value: null`.
+- **`required` from `ControlProps`** flows through but only takes effect
+  inside a `<form>` that calls `reportValidity`.
+## Quick reference
+```vue
+<script setup lang="ts">
+const plan = defineModel<"basic" | "pro" | "team">();
+</script>
+<template>
+  <orio-control-element group :label="$t('billing.plan')">
+    <orio-radio-button v-model="plan" value="basic" :text="$t('billing.basic')" />
+    <orio-radio-button v-model="plan" value="pro"   :text="$t('billing.pro')" />
+    <orio-radio-button v-model="plan" value="team"  :text="$t('billing.team')" />
+  </orio-control-element>
+</template>
+```
+## Related
+- `<orio-control-element>` (group mode) — wrap multiple radios for an
+  accessible group label.
+- `<orio-switch-button>` — boolean on/off pill button.
+- Public API reference: `docs/components/radio-button.md`.

package/dist/runtime/components/Selector.USAGE.md ADDED Viewed

@@ -0,0 +1,131 @@
+---
+kind: component
+category: Form inputs
+purpose: select, dropdown, combobox, listbox picker, single or multi-select
+short: button-triggered listbox in a popover; supports single and multi-select with string or object options
+invariants: true
+---
+# Selector — agent-only invariants
+`<orio-selector>` is a button-triggered listbox rendered inside an
+`<orio-popover>`. It is **not** a `<select>` element and **not** a
+combobox — there is no text input or filter. For free-text + filter,
+combine with `useFuzzySearch` and slot `#options-addon`. Generic over
+`T extends object`.
+## Invariants
+- **`options` accepts `string` or object items** (typed
+  `SelectableOption<T> = string | T`). Mixing is allowed but uncommon —
+  treat the array as homogenous.
+- **For object options, set `field`** (defaults to `"id"`) to the
+  uniqueness key, and **`optionName`** to the display label key. Without
+  `optionName`, objects render as `JSON.stringify(option)` — visible bug.
+- **v-model is required.** Type: `SelectableOption | SelectableOption[] |
+  null | undefined`. Single-select binds the option (or its primitive);
+  multi-select binds an array.
+- **`multiple: true` mutates the bound array in place** via
+  `modelValue.value.splice(...)` / `modelValue.value.push(...)`. The bound
+  ref must be a writable array — a deep `readonly` v-model blocks those
+  mutations: Vue warns in dev (`Set operation on key … failed: target is
+  readonly`) and fails silently in prod, so the selection won't update.
+- **Single-select closes the popover on choice**; multi-select keeps it
+  open. Wire your own close on multi-select via the `option` slot
+  `toggle` prop if needed.
+- **Built on `<orio-popover>` with `position="bottom-right"` offset 5**.
+  Same teleport/scroll/auto-flip caveats apply.
+- **Built on `<orio-list-item>` rows** with `role="option"` and
+  `aria-selected`. Listbox itself has `role="listbox"` and
+  `aria-multiselectable` when `multiple` is set.
+- **Keyboard via `useListKeyboard`**: arrow-down opens (or moves
+  highlight), Enter selects, Esc closes. `popoverToggleRef` is captured
+  lazily from the trigger slot — the first keydown after mount may
+  no-op if the popover hasn't initialized; subsequent keys work.
+- **i18n keys are required.** The component calls `useI18n()` and
+  references `selector.placeholder`, `selector.selected` ({count}), and
+  `selector.noOptions`. Consumers must have these keys in their locale
+  files.
+- **`useControlTokens(size)`** injects CSS vars (`--control-py`,
+  `--control-px`, etc.) onto the popover content — size prop on the
+  Selector flows through to dropdown padding.
+## Slots
+- `#trigger` — replaces the entire button. Receives `{ toggle, control }`.
+- `#trigger-content` — replaces the *inside* of the default button.
+  Receives `{ toggle, getOptionKey, getOptionLabel, attrs }`. Use to
+  customize the label/chevron without rebuilding the button shell.
+- `#trigger-label` — replaces only the label text. Receives same props.
+  Use to render tags for multi-select instead of "N selected".
+- `#option` — replaces each row's content. Receives `{ option, toggle,
+  selected, getOptionKey, getOptionLabel }`.
+- `#no-options` — replaces the default `<orio-empty-state>` when
+  `options.length === 0`.
+- `#options-addon` — extra content rendered **after** the list (e.g. a
+  "create new" button, a search input).
+## Gotchas
+- **No built-in search.** For filterable selectors, render an
+  `<orio-input>` in `#options-addon` and pass a filtered array to
+  `:options`.
+- **Multi-select trigger shows "N selected" by default.** Override via
+  `#trigger-label` to render tags — consider `<orio-tag>` chips. Removal
+  must call `toggleOption` (exposed via `#option` slot, not the trigger).
+- **String options bypass `field`/`optionName`.** Selection equality is
+  `===`. Object options compare via `field`.
+- **`placeholder` falls back to `t("selector.placeholder")`**. Pass an
+  explicit `placeholder` to override per-instance; do not assume English.
+- **`controlProps` strip is exhaustive** — `options`, `multiple`,
+  `field`, `optionName`, `placeholder` never reach the ControlElement
+  wrapper. Adding new selector-specific props requires adding them to the
+  strip list.
+- **Trigger is a `<button>`**, not a real `<select>`. Form serialization
+  and native submission do not include the value — handle submit
+  manually.
+## Quick reference — single-select with object options
+```vue
+<script setup lang="ts">
+interface Country { id: string; name: string }
+const countries: Country[] = [
+  { id: "uk", name: "United Kingdom" },
+  { id: "fi", name: "Finland" },
+];
+const country = defineModel<Country | null>({ default: null });
+</script>
+<template>
+  <orio-selector
+    v-model="country"
+    :options="countries"
+    field="id"
+    option-name="name"
+    :label="$t('settings.country')"
+  />
+</template>
+```
+## Quick reference — multi-select with tag chips
+```vue
+<template>
+  <orio-selector v-model="tags" :options="allTags" multiple field="id" option-name="label">
+    <template #trigger-label>
+      <orio-tag v-for="tag in tags" :key="tag.id" removable @remove="removeTag(tag)">
+        {{ tag.label }}
+      </orio-tag>
+    </template>
+  </orio-selector>
+</template>
+```
+## Related
+- `<orio-taggable-selector>` — pre-built multi-select with tag chips.
+- `<orio-list-item>` — the row primitive used inside the listbox.
+- `useListKeyboard` — keyboard nav composable.
+- `useFuzzySearch` — pair with `#options-addon` for a search filter.
+- Public API reference: `docs/components/selector.md`.

package/dist/runtime/components/SwitchButton.USAGE.md ADDED Viewed

@@ -0,0 +1,62 @@
+---
+kind: component
+category: Form inputs
+purpose: toggle, on/off switch, pill toggle, boolean button
+short: boolean on/off pill button (not a sliding switch) wrapping ControlElement; click/Enter/Space toggle
+invariants: true
+---
+# SwitchButton — agent-only invariants
+`<orio-switch-button>` is a **pill-shaped button** that toggles a boolean.
+Despite the name it is **not** a sliding toggle switch — it is a chip-style
+button that flips between active and inactive states.
+## Invariants
+- **Renders a `<button type=...>` element**, not a checkbox or sliding
+  knob. The "switch" is purely visual state via the `.active` class.
+- **v-model is `boolean`** (not required — renders as off when unbound).
+- **Click, Enter, and Space all toggle.** `Enter` and `Space` use
+  `.prevent` to avoid form submit / page scroll.
+- **`disabled` blocks toggling** and applies `.disabled` styles (0.5
+  opacity, `cursor: not-allowed`). Keyboard activation is also gated.
+- **Default slot is the button content** (label, icon, or both). Visual
+  active state changes background/border/color; the slot does not
+  receive any reactive prop.
+- **Wraps `<orio-control-element>`** — supports the standard `label`,
+  `error`, `layout`, `size`, etc. The control bag is spread on the
+  inner `<button>` along with `$attrs`.
+## Gotchas
+- **The component name is misleading.** If you want a sliding toggle
+  switch (knob that animates), this is not it. Build that yourself or
+  pick another primitive.
+- **No `aria-pressed`.** The active state is visual only. For correct
+  screen reader semantics, pass `:aria-pressed="modelValue"` via
+  `$attrs`.
+- **`@keydown.enter.prevent`** swallows form-submit Enter inside a
+  `<form>`. If the SwitchButton is inside a form, Enter on it will
+  toggle but not submit.
+## Quick reference
+```vue
+<template>
+  <orio-switch-button
+    v-model="notifications"
+    :label="$t('settings.notifications')"
+    :aria-pressed="notifications"
+  >
+    <orio-icon :name="notifications ? 'bell' : 'bell-off'" />
+    {{ notifications ? $t("common.on") : $t("common.off") }}
+  </orio-switch-button>
+</template>
+```
+## Related
+- `<orio-check-box>` — when you want a real checkbox.
+- `<orio-radio-button>` — single-choice from a group.
+- Public API reference: `docs/components/switch-button.md`.

package/dist/runtime/components/Tag.USAGE.md ADDED Viewed

@@ -0,0 +1,51 @@
+---
+kind: component
+category: Buttons & indicators
+purpose: tag, chip, label, removable chip, category pill
+short: small text chip with neutral or accent variant; static display only (no remove behavior)
+invariants: true
+---
+# Tag — agent-only invariants
+`<orio-tag>` is a static text chip. No close button, no click handler, no
+removal behavior — display only.
+## Invariants
+- **`text` is required.** It is the only way to set the chip's visible
+  content — there is no default slot.
+- **`variant`**: `"neutral"` (default, gray) or `"accent"` (themed
+  accent). No `danger` / `alert` colors here — use `<orio-badge>` for
+  that.
+- **`id` is an optional uniqueness key** used by upstream components
+  (`<orio-taggable-selector>`) to match selected tags. Pass it whenever
+  the tag participates in selection state.
+- **`user-select: none`** — text inside the chip cannot be selected with
+  the cursor.
+## Gotchas
+- **No remove / close button.** The `TagProps` shape is intentionally
+  passive. For removable chips, wrap a custom button next to it or build
+  your own primitive.
+- **No icon support.** No `icon` prop, no slot. For icon+text chips,
+  build directly from a `<span>` with `<orio-icon>`.
+- **No size variants.** Padding (`0.25rem 0.6rem`) and font size
+  (`--font-sm`) are fixed.
+## Quick reference
+```vue
+<template>
+  <orio-tag :text="$t('category.urgent')" variant="accent" />
+  <orio-tag :text="$t('category.draft')" />
+</template>
+```
+## Related
+- `<orio-taggable-selector>` — uses `TagProps` as its option shape.
+- `<orio-badge>` — when you need a status pill with semantic color
+  variants.
+- Public API reference: `docs/components/tag.md`.

package/dist/runtime/components/TaggableSelector.USAGE.md ADDED Viewed

@@ -0,0 +1,73 @@
+---
+kind: component
+category: Form inputs
+purpose: multi-select with tag chips, taggable selector, chip picker
+short: multi-select Selector that renders chosen options as tag chips in the trigger
+invariants: true
+---
+# TaggableSelector — agent-only invariants
+`<orio-taggable-selector>` is a thin wrapper over `<orio-selector>` that
+forces `multiple` mode and renders the selection as a row of `<orio-tag>`
+chips inside the trigger. Read `Selector.USAGE.md` for the full contract.
+## Invariants
+- **Always multi-select.** The internal `<orio-selector>` is passed
+  `multiple` unconditionally; the prop cannot be turned off.
+- **`optionName` defaults to `"text"`** to align with `TagProps.text`. If
+  your option type uses a different label key, pass `option-name`.
+- **v-model type is `TagProps[]`** — `{ id?: string; text: string;
+  variant?: "neutral" | "accent" }[]`. Options must be tag-shaped or
+  augmented to satisfy this contract.
+- **Tags in the trigger are display-only.** Clicking a chip does **not**
+  remove the option. The user must reopen the dropdown and uncheck it.
+  This is a real usability tradeoff — for click-to-remove, fall back to
+  `<orio-selector>` with a custom `#trigger-label`.
+- **Trigger lays chips out as `flex-wrap`** with `0.5rem` gap, left-aligned.
+  Selecting many chips grows the trigger height; constrain it if your
+  layout depends on a fixed height.
+## Gotchas
+- **`field` (uniqueness key) still defaults to `"id"`** from the underlying
+  Selector. Each tag should have a stable `id` — without one, multi-select
+  add/remove will mis-match items with identical `text`.
+- **No empty-state placeholder by default in the trigger.** When the
+  selection is empty, the trigger is empty space. Pass a `placeholder` so
+  the dropdown shows a hint, but the trigger label itself will not show
+  it (the `#trigger-label` slot renders an empty chip list).
+- **Variant per chip is per-option.** Set `variant: "accent"` on individual
+  option objects to tint specific chips.
+## Quick reference
+```vue
+<script setup lang="ts">
+import type { TagProps } from "../components/Tag.vue";
+const allCategories: TagProps[] = [
+  { id: "fiction", text: "Fiction" },
+  { id: "non-fiction", text: "Non-fiction", variant: "accent" },
+  { id: "poetry", text: "Poetry" },
+];
+const selected = defineModel<TagProps[]>({ default: () => [] });
+</script>
+<template>
+  <orio-taggable-selector
+    v-model="selected"
+    :options="allCategories"
+    :label="$t('book.categories')"
+  />
+</template>
+```
+## Related
+- `<orio-selector>` — base; use with custom `#trigger-label` for
+  removable chips or different layouts.
+- `<orio-tag>` — the chip primitive rendered in the trigger.
+- Public API reference: `docs/components/taggable-selector.md`.

package/dist/runtime/components/Textarea.USAGE.md ADDED Viewed

@@ -0,0 +1,72 @@
+---
+kind: component
+category: Form inputs
+purpose: textarea, multi-line text, long text input
+short: multi-line text input wrapping ControlElement; supports inner-floating label and vertical resize
+invariants: true
+---
+# Textarea — agent-only invariants
+`<orio-textarea>` is the multi-line counterpart to `<orio-input>`. Same
+ControlElement wrapping, same layout modes, same slot-bag flow. Read
+`ControlElement.USAGE.md` and `Input.USAGE.md` first — most of the contract
+lives there.
+## Invariants
+- **Extends `ControlProps`** with one override: `layout?: InputLayout`
+  where `InputLayout = ControlLayout | "inner"`. The `"inner"` mode floats
+  the label inside the textarea chrome (same trick as Input).
+- **`layout="inner"` translates to `vertical`** on the inner ControlElement
+  and adds an `.inner` class. The label reposition is driven by `:deep()`
+  styles, not a duplicate label DOM.
+- **v-model is `string`** (default `""`).
+- **`rows="4"` is the hard default** rendered on the `<textarea>`. Override
+  via `$attrs` — `<orio-textarea :rows="2">` flows through.
+- **`resize: vertical`** is set in CSS. The user can drag the bottom edge
+  but cannot resize horizontally.
+- **Horizontal layout aligns the label to the top.** When `layout="horizontal"`,
+  the `.control-label` is padded with `--control-py` and the row uses
+  `align-items: flex-start` — so the label sits next to the top of a tall
+  textarea, not centered vertically.
+- **`$attrs` is spread before the control bag** on the inner `<textarea>`:
+  `v-bind="{ ...$attrs, ...control }"`. Native attrs (`placeholder`,
+  `maxlength`, `rows`, `wrap`) work on `<orio-textarea>` and reach the
+  underlying element.
+## Gotchas
+- **Resize handle ignores `layout="inner"`.** The drag handle still appears
+  bottom-right — the inner label can overlap an aggressively resized
+  textarea's content. Cap `max-height` if that matters.
+- **`rows` only sets the initial height** (in line-heights). After the
+  user resizes, the manual height wins. To reset, re-mount the component.
+- **The textarea is `width: 100%`** of the slot wrapper, which itself
+  follows the wrapper border. Setting `cols` has no effect on rendered
+  width.
+## Quick reference
+```vue
+<script setup lang="ts">
+const note = defineModel<string>({ default: "" });
+</script>
+<template>
+  <orio-textarea
+    v-model="note"
+    :label="$t('order.notes.label')"
+    :placeholder="$t('order.notes.placeholder')"
+    layout="inner"
+    :rows="6"
+    maxlength="500"
+  />
+</template>
+```
+## Related
+- `<orio-input>` — single-line text. Same contract.
+- `<orio-control-element>` — the wrapper; owns label/error/a11y.
+- Public API reference: `docs/components/textarea.md`.

package/dist/runtime/components/Tooltip.USAGE.md ADDED Viewed

@@ -0,0 +1,84 @@
+---
+kind: component
+category: Layout & containers
+purpose: tooltip, hover hint, focus hint, label-on-hover
+short: hover/focus-triggered tooltip teleported to body, with delay, arrow, and four placements
+invariants: true
+---
+# Tooltip — agent-only invariants
+`<orio-tooltip>` wraps a trigger in an `inline-flex` div and shows a small
+floating bubble on hover or focus. It is not for click-driven menus — use
+`<orio-popover>` for that.
+## Invariants
+- **Trigger wrapper is `display: inline-flex`** (centered). The slot lives
+  inside it. Block-level children are coerced into the flex layout.
+- **Mouse + keyboard both trigger.** `@mouseenter`/`@focus` show,
+  `@mouseleave`/`@blur` hide. Touch is not supported.
+- **`delay` (default 500 ms) gates open only.** Hide is immediate. Setting
+  `delay: 0` makes it instant.
+- **`disabled` watcher closes an open tooltip.** Flipping to disabled mid-
+  display hides it. Re-enabling does not reopen — the user has to re-hover.
+- **Two content sources, slot wins.** `#content` slot renders if provided,
+  otherwise the `text` prop. Both being empty renders an empty bubble.
+- **Teleported to body only while visible.** Unlike Popover, the tooltip is
+  mounted/unmounted around the visible window — no leftover DOM at rest.
+- **No placement fallback.** `placement` (`top`/`bottom`/`left`/`right`) is
+  honored as-is. If the bubble overflows the viewport, it stays offscreen.
+  Compare with Popover, which auto-flips.
+- **Position is recalculated on scroll/resize** while visible (capture-phase
+  listeners catch nested scrollers).
+- **`pointer-events: none` on the bubble.** It never intercepts the cursor —
+  so leaving the trigger always closes it.
+- **Has a CSS-triangle arrow** (`.orio-tooltip-arrow-{placement}`) anchored
+  on the appropriate edge.
+- **Styles are intentionally unscoped** in the second `<style>` block,
+  because teleported nodes escape scoped CSS. Class names use the
+  `orio-tooltip-` prefix to avoid collisions. Consumers **can** override
+  them globally — useful for theming, dangerous if not namespaced.
+- **`white-space: nowrap`** on the bubble. Long `text` does not wrap. For
+  multi-line, render `#content` with your own line-breaking CSS.
+- **A11y is partial.** The bubble has `role="tooltip"` and `aria-hidden`,
+  but the trigger does **not** receive `aria-describedby`. Screen readers
+  may not announce the tooltip. Wire `aria-describedby` on the trigger
+  child yourself if it matters.
+## Gotchas
+- **`text` defaults to English.** Project convention: pass an i18n key —
+  `:text="$t('action.delete.hint')"`.
+- **`inline-flex` wrapper can change layout.** Wrapping a block-level
+  element (a card, a list row) in a Tooltip squashes it. Wrap a smaller
+  trigger (button, icon) instead.
+- **`delay` does not debounce reopens.** Rapid hover toggles can still
+  flash the tooltip on the second mount if the first delay completed.
+- **Z-index is `9999`** on the bubble — less than Popover (`999999`) and
+  Modal. Tooltips above an open popover may render behind it.
+- **No click-to-dismiss.** Clicking the trigger does not close the bubble.
+  The user has to move focus or hover away.
+## Quick reference
+```vue
+<template>
+  <orio-tooltip :text="$t('action.delete.hint')" placement="top" :delay="200">
+    <orio-button icon-only icon="trash" @click="onDelete" />
+  </orio-tooltip>
+  <orio-tooltip placement="right">
+    <span>Hover me</span>
+    <template #content>
+      <strong>Custom</strong> content with <em>markup</em>.
+    </template>
+  </orio-tooltip>
+</template>
+```
+## Related
+- `<orio-popover>` — click-driven anchored panel; do not reach for Tooltip
+  for menus.
+- Public API reference: `docs/components/tooltip.md`.