orio-ui 1.27.0 → 1.28.1

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

@@ -0,0 +1,79 @@
+---
+kind: component
+category: Layout & containers
+purpose: animation wrapper, fade/slide a slot, animated list, mount-stagger layout
+short: flex container that fade-slides its direct children up on mount and exposes a sound `play` callback
+invariants: true
+---
+
+# AnimatedContainer — agent-only invariants
+
+`<orio-animated-container>` is a flex layout that runs a fade-in-up CSS
+animation on every direct child when it mounts. It is **not** a Vue
+`<Transition>` — there is no leave animation and reactive state changes do
+not retrigger it.
+
+## Invariants
+
+- **Animation fires on mount only.** The `containerFadeInUp` keyframe is a
+  plain CSS animation on `.animated-container > *`. To replay, change
+  `:key` on the container (or on the child). Re-rendering reactive content
+  inside the slot does **not** restart the animation.
+- **Only direct children animate.** The selector is `> *`. Wrapping children
+  in an extra `<div>` moves the animation up to the wrapper. Nested deep
+  trees do not animate per-node.
+- **Layout is opinionated.** The container is `display: flex; flex-wrap:
+  wrap; justify-content: center; gap: 1rem; padding-inline: 1rem;`. Treat it
+  as a layout primitive, not a transparent wrapper.
+- **`direction` toggles flex-direction _and_ justification.** `"row"`
+  (default) → wrap + centered. `"column"` → `flex-direction: column` +
+  `justify-content: flex-start`.
+- **`play` slot prop is `useSound().play`.** The default slot exposes
+  `{ play }`. Wire it to `@mouseenter` / `@click` on children for hover or
+  tap feedback. There is no prop to disable or swap the sound — it is
+  global `useSound`.
+
+## Gotchas
+
+- **No leave animation.** Items removed from the slot disappear instantly.
+  If you need exit animation, wrap each item in `<Transition>` or use a
+  different primitive.
+- **Newly inserted children animate independently.** When the slot's child
+  list grows (v-for over a reactive array), each new node animates on its
+  own mount — there is no list-coordinated stagger.
+- **Built-in horizontal padding bleeds.** `padding-inline: 1rem` is on the
+  container. If the consumer wraps it in a tight column, the inner content
+  starts 1rem in. Override with `:deep(.animated-container)` or pad the
+  parent.
+- **`direction="column"` does not stretch children.** They still wrap by
+  default (`flex-wrap: wrap` is unchanged). Children narrower than the
+  container will not fill the row.
+
+## Quick reference
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+
+const animationKey = ref(0);
+function replay() {
+  animationKey.value += 1;
+}
+</script>
+
+<template>
+  <orio-button @click="replay">Replay</orio-button>
+
+  <orio-animated-container :key="animationKey" direction="column" v-slot="{ play }">
+    <div v-for="item in items" :key="item.id" @mouseenter="play">
+      {{ item.label }}
+    </div>
+  </orio-animated-container>
+</template>
+```
+
+## Related
+
+- `useSound` composable — the source of the `play` callback. See
+  `docs/composables/use-sound.md`.
+- Public API reference: `docs/components/animated-container.md`.

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

@@ -0,0 +1,75 @@
+---
+kind: component
+category: Buttons & indicators
+purpose: badge, small status pill, notification dot, count indicator, corner badge
+short: small status pill or dot indicator; optionally positioned in the top-right corner of a wrapped element
+invariants: true
+---
+
+# Badge — agent-only invariants
+
+`<orio-badge>` renders one of two shapes:
+- A standalone inline status pill / dot.
+- A **positioned** badge anchored to the top-right corner of an element
+  passed via the `#wrapping` slot (typical notification-on-icon pattern).
+
+## Invariants
+
+- **`#wrapping` slot toggles positioning mode.** When provided, the badge
+  is rendered absolutely at `top: 15%; right: 15%; transform: translate(50%, -50%)`
+  on top of the wrapped element. Without `#wrapping`, the badge is plain
+  inline.
+- **Default slot determines dot vs text mode.** Empty default slot → dot
+  badge (0.5rem circle, no padding). Any content → text/number badge.
+- **`variant`**: `"primary"` (default), `"danger"`, `"alert"`, `"grey"`.
+  Maps to accent / danger / alert / surface color tokens.
+- **`pill` prop**: switches the border-radius to pill shape; ignored when
+  in dot mode.
+- **`hidden` prop**: gates the badge render via `v-if`. The wrapped slot
+  still renders when in wrapping mode — only the indicator hides.
+- **No `count` prop.** Use the default slot for the number: `<orio-badge>3</orio-badge>`.
+
+## Gotchas
+
+- **No automatic "99+" cap.** Long content (e.g. `1234`) renders fully,
+  pushing the corner badge wider. Cap in the consumer.
+- **Positioned badge offsets are percentages of the wrapping element.**
+  Tiny wrapped icons may have the badge clip outside the wrapper. The
+  wrapper is `position: relative; display: inline-flex` — `overflow: visible`
+  is implicit, but parent overflow may clip it.
+- **No interactive behavior.** Click does not bubble specially; it's a
+  `<span>`. For removable chips, use `<orio-tag>` instead.
+
+## Quick reference — corner badge on an icon
+
+```vue
+<template>
+  <orio-badge variant="danger">
+    <template #wrapping>
+      <orio-button icon="bell" variant="subdued" />
+    </template>
+    {{ unreadCount }}
+  </orio-badge>
+
+  <orio-badge variant="alert" :hidden="!hasUpdates">
+    <template #wrapping>
+      <orio-icon name="refresh" />
+    </template>
+  </orio-badge>
+</template>
+```
+
+## Quick reference — inline status pill
+
+```vue
+<template>
+  <orio-badge variant="grey" pill>{{ $t("status.draft") }}</orio-badge>
+  <orio-badge variant="primary">{{ $t("status.live") }}</orio-badge>
+</template>
+```
+
+## Related
+
+- `<orio-tag>` — chip with text and optional `id` / variant for filters
+  and selections.
+- Public API reference: `docs/components/badge.md`.

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

@@ -0,0 +1,52 @@
+---
+kind: component
+category: Buttons & indicators
+purpose: banner, page-level notice, alert strip, inline notification, info bar
+short: page-level notice strip with danger/alert/success/info variants; default slot for content
+invariants: true
+---
+
+# Banner — agent-only invariants
+
+`<orio-banner>` is a plain styled `<div>` for page-level notices. No icon,
+no close button, no auto-dismiss — bring your own.
+
+## Invariants
+
+- **`variant`**: `"info"` (default), `"success"`, `"alert"`, `"danger"`.
+  Each maps to a soft-background + matching border color from the
+  project's color tokens.
+- **Default slot is the entire body.** Text, links, action buttons —
+  whatever fits the layout.
+- **Padding (`0.75rem 1rem`) and border-radius (`--border-radius-sm`)
+  are fixed.** No size variants.
+
+## Gotchas
+
+- **No semantic role / ARIA live region.** The `<div>` has no
+  `role="alert"` or `role="status"`. For screen-reader-announced
+  notices, add `role="alert"` (urgent) or `role="status"` (polite) via
+  `$attrs`.
+- **No close button.** Pair with `v-if` on the consumer side for
+  dismissable banners.
+- **No icon prop.** Render `<orio-icon>` inside the slot if needed —
+  the banner does not auto-prepend a variant-matching glyph.
+
+## Quick reference
+
+```vue
+<template>
+  <orio-banner variant="alert" role="alert" v-if="paymentFailed">
+    <strong>{{ $t("billing.failed.title") }}</strong>
+    <orio-button variant="subdued" @click="retry">
+      {{ $t("billing.failed.retry") }}
+    </orio-button>
+  </orio-banner>
+</template>
+```
+
+## Related
+
+- `<orio-empty-state>` — for empty-list placeholders.
+- `<orio-tooltip>` — for transient hover hints.
+- Public API reference: `docs/components/banner.md`.

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

@@ -0,0 +1,83 @@
+---
+kind: component
+category: Buttons & indicators
+purpose: button, primary action, CTA, icon button, action button
+short: primary action button with variants, loading, icon slots, and auto icon-only sizing
+invariants: true
+---
+
+# Button — agent-only invariants
+
+`<orio-button>` is the primary action button. Wraps `<orio-control-element>`
+so it can carry a label/error like other form controls, but it is most
+often used standalone.
+
+## Invariants
+
+- **`variant`**: `"primary"` (default), `"secondary"`, `"subdued"`. Primary
+  is filled; secondary is outline; subdued is bare text. All use the
+  global `gradient-hover` class for the hover treatment.
+- **`icon` prop OR `#icon` slot**: pass an icon name (registered in
+  `utils/iconRegistry`) OR slot in arbitrary content before the label.
+  Slot wins.
+- **`#icon-right` slot**: trailing icon, rendered after the default slot.
+- **`loading` prop**: renders `<orio-loading-spinner>` in place of all
+  slot content (icon, label, icon-right are all hidden). Clicks and
+  mousedown are blocked while loading.
+- **Icon-only mode is auto-detected.** When an icon is present and the
+  default slot is empty, `.icon-only` is applied → `aspect-ratio: 1`,
+  `line-height: 0`. No need to pass a prop.
+- **`pill` prop**: `false` by default. When `true`, swaps the button's
+  `border-radius` to `var(--border-radius-pill)` (fully rounded),
+  overriding the size-driven `--control-radius`. No effect when omitted.
+- **`disabled` blocks `click` and `mousedown` emits.** `mouseup` and
+  `mouseleave` always fire (so press-and-hold callers can release
+  state).
+- **Emits**: `click`, `mousedown`, `mouseup`, `mouseleave`. Only `click`
+  and `mousedown` honor the loading/disabled gates.
+- **Wraps ControlElement** — supports `label`, `error`, `size`, `layout`,
+  etc. The control bag is spread on the inner `<button>` along with
+  `$attrs`.
+
+## Gotchas
+
+- **`$attrs` are duplicated.** Because ControlElement does **not** set
+  `inheritAttrs: false` and Button also spreads `$attrs` on the inner
+  `<button>`, an attr like `data-test="x"` may appear on both the
+  wrapper `<div>` (from ControlElement's root) and the inner `<button>`.
+  For attrs that must be unique (e.g. `data-key` for list keying,
+  `tabindex` override), bind a plain native `<button>` instead of
+  `<orio-button>`.
+- **`type` defaults to `submit`** (native default). Inside an
+  `<orio-form>`, every `<orio-button>` will submit unless you pass
+  `type="button"`.
+- **Loading hides the icon and the icon-right slot.** No way to keep
+  the trailing icon while showing a spinner — render the spinner
+  yourself in `#icon-right` if you need that.
+- **No `aria-busy` on loading.** Set it via `$attrs` if you need
+  screen-reader signal.
+
+## Quick reference
+
+```vue
+<template>
+  <orio-button @click="onSave" :loading="saving">
+    {{ $t("common.save") }}
+  </orio-button>
+
+  <orio-button variant="secondary" icon="trash" @click="onDelete">
+    {{ $t("common.delete") }}
+  </orio-button>
+
+  <orio-button variant="subdued" icon="close" aria-label="Close" />
+
+  <orio-button pill icon="plus" aria-label="Add" />
+</template>
+```
+
+## Related
+
+- `<orio-nav-button>` — link-styled button with `active` state.
+- `<orio-loading-spinner>` — used internally when `loading` is true.
+- `<orio-icon>` — used internally for the `icon` prop and slots.
+- Public API reference: `docs/components/button.md`.

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

@@ -3,6 +3,7 @@ interface Props extends ControlProps {
     variant?: "primary" | "secondary" | "subdued";
     icon?: string;
     loading?: boolean;
+    pill?: boolean;
 }
 declare var __VLS_13: {}, __VLS_20: {}, __VLS_22: {};
 type __VLS_Slots = {} & {

package/dist/runtime/components/Button.vue

@@ -4,6 +4,7 @@ const props = defineProps({
   variant: { type: String, required: false, default: "primary" },
   icon: { type: String, required: false },
   loading: { type: Boolean, required: false },
+  pill: { type: Boolean, required: false },
   appearance: { type: String, required: false },
   error: { type: [String, null], required: false },
   group: { type: Boolean, required: false },
@@ -47,7 +48,7 @@ function onMouseleave(event) {
   <orio-control-element v-slot="{ control }" v-bind="props">
     <button
       v-bind="{ ...$attrs, ...control }"
-      :class="[variant, 'gradient-hover', { 'icon-only': isIconOnly }]"
+      :class="[variant, 'gradient-hover', { 'icon-only': isIconOnly, pill }]"
       @click="click"
       @mousedown="onMousedown"
       @mouseup="onMouseup"
@@ -85,6 +86,9 @@ button.icon-only {
   line-height: 0;
   aspect-ratio: 1;
 }
+button.pill {
+  border-radius: var(--border-radius-pill);
+}
 button:disabled, button:disabled:hover {
   background-color: var(--color-accent-soft-base);
   color: var(--color-muted);

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

@@ -3,6 +3,7 @@ interface Props extends ControlProps {
     variant?: "primary" | "secondary" | "subdued";
     icon?: string;
     loading?: boolean;
+    pill?: boolean;
 }
 declare var __VLS_13: {}, __VLS_20: {}, __VLS_22: {};
 type __VLS_Slots = {} & {

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

@@ -1,3 +1,11 @@
+---
+kind: component
+category: Date
+purpose: month calendar, date grid, day picker UI
+short: month grid with roving-focus keyboard a11y
+invariants: true
+---
+
 # Calendar — agent-only invariants
 
 `<orio-calendar>` is the month-grid primitive. `date/Picker.vue` and

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

@@ -1,3 +1,11 @@
+---
+kind: component
+category: Layout & containers
+purpose: canvas, drawing board, whiteboard, sketch, freeform editor, pluggable tools
+short: pannable workspace with pluggable tools and detached toolbar registry
+invariants: true
+---
+
 # Canvas — agent-only invariants
 
 Read this before integrating `<orio-canvas>` into a consumer app. Public API

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

@@ -0,0 +1,63 @@
+---
+kind: component
+category: Form inputs
+purpose: single checkbox, boolean toggle, opt-in
+short: single boolean checkbox wrapping ControlElement; custom check icon via prop or slot
+invariants: true
+---
+
+# CheckBox — agent-only invariants
+
+`<orio-check-box>` is a single boolean checkbox. The native `<input
+type="checkbox">` is visually hidden; the rendered tick lives in a sibling
+`<span class="checkbox-box">`. Read `ControlElement.USAGE.md` first.
+
+## Invariants
+
+- **v-model is `boolean`**, not required (renders as unchecked when
+  unbound).
+- **Default slot is the label text** rendered to the right of the box.
+- **Default tick is a CSS rotate-45-border checkmark** drawn in
+  `::after`, applied when no `checkedIcon` is passed.
+- **`checkedIcon` / `uncheckedIcon` props** swap in `<orio-icon>` glyphs
+  for either state. Pass icon names registered in `utils/iconRegistry`.
+- **`#icon` slot** lets you render arbitrary indicator content; receives
+  `{ checked }`. Overrides both the default tick and any icon props.
+- **ControlElement is passed `fill`** so the checkbox row fills the wrapper
+  width. Label slot of ControlElement is bypassed — the visible label is
+  the CheckBox's own default slot, not ControlElement's `label` prop.
+- **`--box-size` defaults to `var(--control-icon-size, 1rem)`**. Override
+  the CSS var on the host to resize the box.
+
+## Gotchas
+
+- **The native input has `tabindex="-1"`** in the template, but the
+  styles target `:focus-visible` on it. Keyboard focus for the checkbox
+  may not behave the way an a11y audit expects — confirm tab order
+  before shipping critical forms. If you need keyboard-focusable
+  checkboxes, override `tabindex` via `$attrs`.
+- **`required` from `ControlProps` flows through**, but native checkbox
+  required validation only fires inside a `<form>` that calls
+  `reportValidity`.
+- **No indeterminate state.** v-model is strictly boolean; the
+  underlying input never gets `indeterminate = true`.
+- **Passing both `checkedIcon` and `#icon` slot** — the slot wins; the
+  prop becomes dead code.
+
+## Quick reference
+
+```vue
+<template>
+  <orio-check-box v-model="agreed" :error="errors.terms">
+    {{ $t("signup.acceptTerms") }}
+  </orio-check-box>
+
+  <orio-check-box v-model="bookmarked" checked-icon="bookmark-filled" unchecked-icon="bookmark" />
+</template>
+```
+
+## Related
+
+- `<orio-checkbox-group>` — multi-value group of checkboxes.
+- `<orio-control-element>` — wrapper; owns label/error/a11y.
+- Public API reference: `docs/components/checkbox.md`.

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

@@ -0,0 +1,95 @@
+---
+kind: component
+category: Form inputs
+purpose: group of checkboxes, multi-value boolean group, multi-select boolean
+short: group of CheckBox children bound to an `unknown[]` v-model; supports `options` prop or default slot
+invariants: true
+---
+
+# CheckboxGroup — agent-only invariants
+
+`<orio-checkbox-group>` wires a list of checkboxes to a single array
+v-model. It uses `<orio-control-element group>` so the wrapper renders as
+a `role="group"` with an `aria-labelledby` label — semantically a fieldset
+group, not a `<fieldset>` element.
+
+## Invariants
+
+- **v-model is `unknown[]`** (default `[]`). Each entry is one option's
+  `value`. Comparison is strict `===` — primitives or shared references,
+  not deep equality.
+- **Two modes**: `options` prop (array of `{ label, value }`) **or** the
+  default slot (you render `<orio-check-box>` children yourself). The slot
+  wins when present.
+- **In `options` mode**, each rendered checkbox is `appearance="minimal"`
+  (hardcoded). To change appearance, switch to the slot.
+- **Toggle replaces the array**: `modelValue.value = modelValue.value.filter(...)`
+  / `[...modelValue.value, value]`. Reactive arrays survive; readonly arrays
+  break silently.
+- **Wrapper omits `appearance`, `group`, `id` from `ControlProps`.**
+  `group` is forced true; `id` is internal.
+- **Defaults**: `layout: "vertical"`, `size: "md"`, `error: null`.
+- **Horizontal layout aligns label top** (`align-items: flex-start`) so the
+  label sits next to the first checkbox, not centered against the full
+  column.
+
+## Gotchas
+
+- **`isChecked` uses `Array.includes` with `===`.** Object option values
+  must be the **same reference** as in the model, not a structural match.
+  For object values, store ids and resolve to objects in the parent.
+- **No "select all" / "indeterminate parent" affordance.** Build it in the
+  consumer if needed.
+- **Label rendering depends on `group` mode in ControlElement** — the
+  label becomes a `<span>` with `aria-labelledby` wiring, not a `<legend>`.
+  Screen readers announce it as a group label.
+- **`error` is forwarded** to the group wrapper; per-checkbox errors are
+  not supported. Surface validation at the group level.
+
+## Quick reference — options prop
+
+```vue
+<script setup lang="ts">
+const interests = defineModel<string[]>({ default: () => [] });
+const options = [
+  { label: "Books", value: "books" },
+  { label: "Films", value: "films" },
+  { label: "Music", value: "music" },
+];
+</script>
+
+<template>
+  <orio-checkbox-group
+    v-model="interests"
+    :options="options"
+    :label="$t('profile.interests')"
+  />
+</template>
+```
+
+## Quick reference — slot mode (custom rendering)
+
+```vue
+<template>
+  <orio-checkbox-group v-model="features" :label="$t('settings.features')">
+    <orio-check-box
+      v-for="feature in availableFeatures"
+      :key="feature.id"
+      :model-value="features.includes(feature.id)"
+      checked-icon="star-filled"
+      unchecked-icon="star"
+      @update:model-value="toggle(feature.id)"
+    >
+      {{ feature.name }}
+    </orio-check-box>
+  </orio-checkbox-group>
+</template>
+```
+
+## Related
+
+- `<orio-check-box>` — single checkbox; rendered children inside this
+  group.
+- `<orio-control-element>` (`group` mode) — wrapper; provides the group
+  label semantics.
+- Public API reference: `docs/components/checkbox-group.md`.

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

@@ -1,3 +1,11 @@
+---
+kind: component
+category: Form inputs
+purpose: label + error + a11y wrapper for any form control
+short: label/legend wrapper, owns a11y attrs, exposes the `control` slot prop bag
+invariants: true
+---
+
 # ControlElement — agent-only invariants
 
 `ControlElement` is the wrapper every form input uses (Input, Textarea,

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

@@ -1,5 +1,5 @@
 export type ControlLayout = "vertical" | "horizontal";
-export type ControlSize = "sm" | "md" | "lg" | "xl";
+export type ControlSize = "xs" | "sm" | "md" | "lg" | "xl";
 /**
  * A11y + form attrs that flow from the caller through ControlElement to the
  * actual interactive element via the `control` slot prop. Never rendered on

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

@@ -1,5 +1,5 @@
 export type ControlLayout = "vertical" | "horizontal";
-export type ControlSize = "sm" | "md" | "lg" | "xl";
+export type ControlSize = "xs" | "sm" | "md" | "lg" | "xl";
 /**
  * A11y + form attrs that flow from the caller through ControlElement to the
  * actual interactive element via the `control` slot prop. Never rendered on

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

@@ -0,0 +1,65 @@
+---
+kind: component
+category: Layout & containers
+purpose: dashed empty/drop zone, add-item card, upload tile, empty state with action
+short: clickable dashed-border tile with icon and label, used for add/upload affordances
+invariants: true
+---
+
+# DashedContainer — agent-only invariants
+
+`<orio-dashed-container>` is a self-styled clickable tile that renders an
+optional icon and a label inside a dashed border. It is **not** a generic
+slot wrapper.
+
+## Invariants
+
+- **No default slot.** The template only renders `icon` and `text` props.
+  Children placed between the tags are dropped. To compose richer content,
+  use a different primitive.
+- **Always clickable.** The wrapper has `cursor: pointer` and emits
+  `click` unconditionally — even with no listener attached, the tile looks
+  interactive. Do not use as a passive container.
+- **`size` only scales the icon.** `small` → 2rem, `medium` → 3rem, `large`
+  → 5rem. Padding (2rem), gap (0.5rem), text size, and border are fixed
+  regardless of `size`.
+- **`icon` is forwarded to `<orio-icon :name>`.** Must be a name registered
+  in `utils/iconRegistry`. Missing names render nothing; check the registry
+  before passing a string.
+- **Hover effect comes from the global `gradient-hover` class**, not from
+  scoped styles. The dashed border, padding, and layout are scoped; the
+  hover gradient is project-global.
+
+## Gotchas
+
+- **`text` defaults to English in consumer code.** Project convention
+  (see CLAUDE.md / translations note) is to pass an i18n key: `:text="$t('addItem')"`,
+  not `text="Add Item"`.
+- **Both `icon` and `text` are optional.** With neither, the tile is an
+  empty dashed box that still emits `click`. Confirm at least one is set
+  unless that empty look is intentional.
+- **The `<span :size>` shorthand** in the template forwards `size` as a
+  DOM attribute on the label. It's not styled — harmless, but visible
+  in devtools.
+- **No `disabled` state.** If a consumer needs disabled-looking behaviour,
+  wrap or override styles externally; do not rely on a prop.
+
+## Quick reference
+
+```vue
+<template>
+  <orio-dashed-container
+    icon="plus"
+    :text="$t('gallery.addImage')"
+    size="medium"
+    @click="openPicker"
+  />
+</template>
+```
+
+## Related
+
+- `orio-icon` — icon renderer driven by the same `name` string.
+- `orio-upload` — full file-picker widget; prefer it over hand-rolling
+  click-to-upload on a `DashedContainer`.
+- Public API reference: `docs/components/dashed-container.md`.