orio-ui 1.24.0 → 1.28.0

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,78 @@
+---
+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.
+- **`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" />
+</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,13 +3,14 @@ interface Props extends ControlProps {
     variant?: "primary" | "secondary" | "subdued";
     icon?: string;
     loading?: boolean;
-    disabled?: boolean;
 }
-declare var __VLS_13: {}, __VLS_20: {};
+declare var __VLS_13: {}, __VLS_20: {}, __VLS_22: {};
 type __VLS_Slots = {} & {
     icon?: (props: typeof __VLS_13) => any;
 } & {
     default?: (props: typeof __VLS_20) => any;
+} & {
+    'icon-right'?: (props: typeof __VLS_22) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
     click: (event: PointerEvent) => any;

package/dist/runtime/components/Button.vue

@@ -4,7 +4,6 @@ const props = defineProps({
   variant: { type: String, required: false, default: "primary" },
   icon: { type: String, required: false },
   loading: { type: Boolean, required: false },
-  disabled: { type: Boolean, required: false },
   appearance: { type: String, required: false },
   error: { type: [String, null], required: false },
   group: { type: Boolean, required: false },
@@ -12,7 +11,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 { loading, disabled } = toRefs(props);
 const slots = useSlots();
@@ -39,21 +44,25 @@ function onMouseleave(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="[variant, 'gradient-hover', { 'icon-only': isIconOnly }]"
-      :disabled
       @click="click"
       @mousedown="onMousedown"
       @mouseup="onMouseup"
       @mouseleave="onMouseleave"
     >
       <orio-loading-spinner v-if="loading" />
-      <slot v-else name="icon">
-        <orio-icon v-if="icon" :name="icon" />
-      </slot>
-      <slot />
+      <template v-else>
+        <slot name="icon">
+          <orio-icon v-if="icon" :name="icon" />
+        </slot>
+
+        <slot />
+
+        <slot name="icon-right" />
+      </template>
     </button>
   </orio-control-element>
 </template>
@@ -73,9 +82,8 @@ button {
   user-select: none;
 }
 button.icon-only {
-  padding: 0;
-  border-radius: 50%;
   line-height: 0;
+  aspect-ratio: 1;
 }
 button:disabled, button:disabled:hover {
   background-color: var(--color-accent-soft-base);

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

@@ -3,13 +3,14 @@ interface Props extends ControlProps {
     variant?: "primary" | "secondary" | "subdued";
     icon?: string;
     loading?: boolean;
-    disabled?: boolean;
 }
-declare var __VLS_13: {}, __VLS_20: {};
+declare var __VLS_13: {}, __VLS_20: {}, __VLS_22: {};
 type __VLS_Slots = {} & {
     icon?: (props: typeof __VLS_13) => any;
 } & {
     default?: (props: typeof __VLS_20) => any;
+} & {
+    'icon-right'?: (props: typeof __VLS_22) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
     click: (event: PointerEvent) => any;

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

@@ -0,0 +1,59 @@
+---
+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
+`date/RangePicker.vue` compose it inside a popover.
+
+## Invariants
+
+- **All dates are ISO `YYYY-MM-DD` strings** at the API boundary
+  (`selected`, `markers.start`/`end`, `getMarker`, `isDisabled`, `@select`,
+  `@dayEnter`). Never pass `Date` objects.
+- **Two reactive states**:
+  - `selected` (prop) — the picked day. Calendar does not own it; emit
+    `@select` and let the parent update its v-model.
+  - `anchor` (v-model:anchor) — the visible month. Calendar owns this when
+    uncontrolled, derived from `selected` if not provided. Pass it as
+    `v-model:anchor` if you need cross-component sync (RangePicker uses
+    this to keep two months in lockstep).
+- **Keyboard a11y via `useRovingGrid`.** Arrow keys, Home/End, PageUp/Down
+  navigate. Only one day cell is in the tab order at a time. Do not add
+  manual `tabindex` to day cells from outside.
+- **42-cell grid (6 rows × 7 cols).** Leading/trailing days from neighbour
+  months are rendered with `inMonth: false`. Selection and disabled checks
+  apply to them too — `isDisabled` is called for every cell.
+- **Markers are matched in reverse order** — the last marker in the array
+  wins on overlap. `getMarker` takes precedence over `markers[]` when both
+  are provided.
+- **`weekStartsOn`** is `0` (Sunday) or `1` (Monday, default). Weekday
+  header labels are derived via `Intl.DateTimeFormat` in the active i18n
+  locale.
+
+## Gotchas
+
+- Disabled-day logic should be reactive — `isDisabled` is called inside a
+  computed. Wrap any external state it reads in `computed`/`ref` or it will
+  not re-render on change.
+- The Calendar emits `@dayEnter` on hover/keyboard-focus, **not** on
+  selection. Use for range-picking previews; selection is only `@select`.
+- i18n keys used: `calendar.previousYear`, `calendar.previousMonth`,
+  `calendar.nextMonth`, `calendar.nextYear`. Override these if you ship a
+  locale not bundled in `runtime/i18n/`.
+
+## Quick reference
+
+```vue
+<orio-calendar
+  :selected="iso"
+  :markers="[{ variant: 'accent', start: '2026-06-01', end: '2026-06-07' }]"
+  :is-disabled="(iso) => iso < todayIso"
+  @select="iso = $event"
+/>
+```