orio-ui 1.24.0 → 1.28.0

package/dist/runtime/components/CheckboxGroup.vue

@@ -6,7 +6,13 @@ const props = defineProps({
   label: { type: String, required: false },
   layout: { type: String, required: false, default: "vertical" },
   size: { type: String, required: false, default: "md" },
-  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: Array, ...{ default: () => [] } });
 function isChecked(value) {

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

@@ -0,0 +1,77 @@
+---
+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,
+NumberInput, Selector, CheckBox, etc.). When you build a new orio form
+component, wrap it in `<orio-control-element>`. When you consume an existing
+one, pass `ControlProps` straight through — they are usually re-exported.
+
+## Invariants
+
+- **`inheritAttrs: false`.** Attrs do **not** auto-flow onto the wrapper or
+  the inner element. The component exposes a `control` slot prop containing
+  the a11y/form attr bag (`id`, `ariaDescribedby`, `ariaInvalid`,
+  `ariaRequired`, plus passthrough `tabindex`, `focusKey`, `disabled`,
+  `required`, `name`, `ariaLabel`). The inner element **must** spread it:
+  ```vue
+  <orio-control-element v-slot="{ control }" v-bind="props">
+    <input v-bind="control" />
+  </orio-control-element>
+  ```
+- **`group` prop changes the semantic root.** When `true`, the wrapper gets
+  `role="group"` + `aria-labelledby`, and the label renders as `<span>`
+  (still id-linked) instead of `<label>`. Use this for `CheckboxGroup`,
+  radio groups, anything where the "control" is multiple inputs.
+- **Error wiring is automatic.** Setting `error` to a non-null string:
+  - Renders a `.control-error` span below the slot.
+  - Sets `aria-invalid` and `aria-describedby` on the inner element via the
+    `control` slot prop.
+  - Adds a red border to `.slot-wrapper` (unless the wrapper contains a
+    `:deep(.error-fields)` element, in which case the inner component owns
+    error styling — see TaggableSelector).
+- **`size` is provided to descendants** via `provideControlSize`. Children
+  that use `useControlSize()` (e.g. inner buttons, icons) inherit it
+  automatically — do not re-pass `size` down manually.
+- **`appearance="minimal"`** zeros margin and strips border + box-shadow from
+  the first slot child. Use for inputs embedded in a row with their own
+  surrounding chrome.
+
+## Gotchas
+
+- The slot's `id` matches what the `<label>` points to via `for`. The inner
+  element receives the same `id` through the `control` bag. Do **not**
+  override it — it is `useId()` by default and accessibility breaks if two
+  inputs in the same render share an id.
+- `disabled` is forwarded to the inner element AND drives the wrapper's
+  `.disabled` class for styling. Pass `disabled` on the wrapper, never on the
+  inner element directly.
+- The exported types are the contract:
+  - `ControlProps` — what consumers pass to ControlElement.
+  - `ControlPassthroughProps` — the subset that travels to the inner element.
+  - `ControlSlotAttrs` — the bag exposed via the `control` slot prop.
+  - `ControlLayout = "vertical" | "horizontal"`.
+  Components that wrap ControlElement extend `ControlProps`, e.g.
+  `interface Props extends ControlProps { ... }`.
+
+## Quick reference
+
+```vue
+<script setup lang="ts">
+import type { ControlProps } from "./ControlElement.vue";
+interface Props extends ControlProps { /* component-specific props */ }
+const props = defineProps<Props>();
+</script>
+
+<template>
+  <orio-control-element v-slot="{ control }" v-bind="props">
+    <my-inner-element v-bind="control" />
+  </orio-control-element>
+</template>
+```

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

@@ -1,43 +1,58 @@
 export type ControlLayout = "vertical" | "horizontal";
 export type ControlSize = "sm" | "md" | "lg" | "xl";
-export interface ControlProps {
-    /**
-     * Minimal will reset margin and remove border and box shadow from every element inside the slot
-     */
+/**
+ * A11y + form attrs that flow from the caller through ControlElement to the
+ * actual interactive element via the `control` slot prop. Never rendered on
+ * the wrapper itself.
+ */
+export interface ControlPassthroughProps {
+    /** Native `tabindex` for the inner element. */
+    tabindex?: number | string;
+    /** Roving-focus identifier — see useRovingGrid. Rendered as `focus-key` DOM attr. */
+    focusKey?: string;
+    /** Disables the inner element AND drives wrapper disabled styling. */
+    disabled?: boolean;
+    /** Marks the inner element required and sets `aria-required`. */
+    required?: boolean;
+    /** Native `name` attribute for the inner form element. */
+    name?: string;
+    /** Accessible name for the inner element when no visible label is set. */
+    ariaLabel?: string;
+}
+export interface ControlProps extends ControlPassthroughProps {
+    /** Minimal resets margin and removes border/box-shadow from every element inside the slot. */
     appearance?: "normal" | "minimal";
-    /**
-     * Error message to display below the control
-     */
+    /** Error message to display below the control. Also drives `aria-invalid` and `aria-describedby` on the inner element. */
     error?: string | null;
-    /**
-     * Marks this control as a group (adds role="group" and aria-labelledby).
-     * The label renders as a <span> instead of <label>.
-     * Use for groups of related controls (e.g. CheckboxGroup).
-     */
+    /** Marks this control as a group (adds role="group" + aria-labelledby on the wrapper). The label renders as a <span> instead of <label>. Use for groups of related controls (e.g. CheckboxGroup). */
     group?: boolean;
-    /**
-     * ID for the control's form element, auto-generated if not provided
-     */
+    /** ID for the inner form element. Auto-generated if not provided. */
     id?: string;
-    /**
-     * Label text for the control (or legend text when group is true)
-     */
+    /** Label text for the control (or legend text when group is true). */
     label?: string;
-    /**
-     * Label position relative to the control
-     */
+    /** Label position relative to the control. */
     layout?: ControlLayout;
-    /**
-     * Size of the control and its inner elements
-     */
+    /** Size of the control and its inner elements. */
     size?: ControlSize;
-    /**
-     * Whether element should fill the container
-     */
+    /** Whether the element should fill the container. */
     fill?: boolean;
 }
+/**
+ * Bag the consumer spreads onto the inner interactive element via the `control`
+ * slot prop: `<input v-bind="control" />`. Extends the caller-facing
+ * passthrough props with attrs derived from ControlElement state
+ * (`aria-invalid` from `error`, `aria-describedby` pointing at the error span,
+ * etc.) and the required `id`.
+ */
+export interface ControlSlotAttrs extends ControlPassthroughProps {
+    id: string;
+    ariaDescribedby?: string;
+    ariaInvalid?: boolean;
+    ariaRequired?: boolean;
+}
 declare var __VLS_7: {
     id: string;
+    control: ControlSlotAttrs;
 };
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_7) => any;

package/dist/runtime/components/ControlElement.vue

@@ -10,10 +10,29 @@ const props = defineProps({
   label: { type: String, required: false },
   layout: { type: String, required: false, default: "vertical" },
   size: { type: String, required: false, default: "md" },
-  fill: { type: Boolean, required: false, default: false }
+  fill: { type: Boolean, required: false, default: 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 }
 });
 provideControlSize(toRef(props, "size"));
 const sizeStyle = computed(() => sizeTokens[props.size]);
+const errorId = computed(() => props.error ? `${props.id}-error` : void 0);
+const control = computed(() => ({
+  id: props.id,
+  tabindex: props.tabindex,
+  focusKey: props.focusKey,
+  disabled: props.disabled || void 0,
+  required: props.required || void 0,
+  name: props.name,
+  ariaLabel: props.ariaLabel,
+  ariaDescribedby: errorId.value,
+  ariaInvalid: props.error ? true : void 0,
+  ariaRequired: props.required || void 0
+}));
 </script>
 
 <template>
@@ -23,13 +42,13 @@ const sizeStyle = computed(() => sizeTokens[props.size]);
   appearance,
   layout,
   `size-${size}`,
-  { 'has-error': error, group, fill }
+  { 'has-error': error, group, fill, disabled },
+  $attrs.class
 ]"
-    :style="sizeStyle"
-    v-bind="{
-  ...$attrs,
-  ...group ? { role: 'group', ...label ? { 'aria-labelledby': id } : {} } : {}
-}"
+    :style="[sizeStyle, $attrs.style]"
+    v-bind="
+  group ? { role: 'group', ...label ? { 'aria-labelledby': id } : {} } : {}
+"
   >
     <component
       :is="group ? 'span' : 'label'"
@@ -41,9 +60,9 @@ const sizeStyle = computed(() => sizeTokens[props.size]);
     </component>
     <div class="control-group">
       <div class="slot-wrapper">
-        <slot :id />
+        <slot :id :control />
       </div>
-      <span v-if="error" class="control-error">{{ error }}</span>
+      <span v-if="error" :id="errorId" class="control-error">{{ error }}</span>
     </div>
   </div>
 </template>

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

@@ -1,43 +1,58 @@
 export type ControlLayout = "vertical" | "horizontal";
 export type ControlSize = "sm" | "md" | "lg" | "xl";
-export interface ControlProps {
-    /**
-     * Minimal will reset margin and remove border and box shadow from every element inside the slot
-     */
+/**
+ * A11y + form attrs that flow from the caller through ControlElement to the
+ * actual interactive element via the `control` slot prop. Never rendered on
+ * the wrapper itself.
+ */
+export interface ControlPassthroughProps {
+    /** Native `tabindex` for the inner element. */
+    tabindex?: number | string;
+    /** Roving-focus identifier — see useRovingGrid. Rendered as `focus-key` DOM attr. */
+    focusKey?: string;
+    /** Disables the inner element AND drives wrapper disabled styling. */
+    disabled?: boolean;
+    /** Marks the inner element required and sets `aria-required`. */
+    required?: boolean;
+    /** Native `name` attribute for the inner form element. */
+    name?: string;
+    /** Accessible name for the inner element when no visible label is set. */
+    ariaLabel?: string;
+}
+export interface ControlProps extends ControlPassthroughProps {
+    /** Minimal resets margin and removes border/box-shadow from every element inside the slot. */
     appearance?: "normal" | "minimal";
-    /**
-     * Error message to display below the control
-     */
+    /** Error message to display below the control. Also drives `aria-invalid` and `aria-describedby` on the inner element. */
     error?: string | null;
-    /**
-     * Marks this control as a group (adds role="group" and aria-labelledby).
-     * The label renders as a <span> instead of <label>.
-     * Use for groups of related controls (e.g. CheckboxGroup).
-     */
+    /** Marks this control as a group (adds role="group" + aria-labelledby on the wrapper). The label renders as a <span> instead of <label>. Use for groups of related controls (e.g. CheckboxGroup). */
     group?: boolean;
-    /**
-     * ID for the control's form element, auto-generated if not provided
-     */
+    /** ID for the inner form element. Auto-generated if not provided. */
     id?: string;
-    /**
-     * Label text for the control (or legend text when group is true)
-     */
+    /** Label text for the control (or legend text when group is true). */
     label?: string;
-    /**
-     * Label position relative to the control
-     */
+    /** Label position relative to the control. */
     layout?: ControlLayout;
-    /**
-     * Size of the control and its inner elements
-     */
+    /** Size of the control and its inner elements. */
     size?: ControlSize;
-    /**
-     * Whether element should fill the container
-     */
+    /** Whether the element should fill the container. */
     fill?: boolean;
 }
+/**
+ * Bag the consumer spreads onto the inner interactive element via the `control`
+ * slot prop: `<input v-bind="control" />`. Extends the caller-facing
+ * passthrough props with attrs derived from ControlElement state
+ * (`aria-invalid` from `error`, `aria-describedby` pointing at the error span,
+ * etc.) and the required `id`.
+ */
+export interface ControlSlotAttrs extends ControlPassthroughProps {
+    id: string;
+    ariaDescribedby?: string;
+    ariaInvalid?: boolean;
+    ariaRequired?: boolean;
+}
 declare var __VLS_7: {
     id: string;
+    control: ControlSlotAttrs;
 };
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_7) => any;

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`.

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

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

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

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

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

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