orio-ui 1.24.0 → 1.27.0

package/README.md

@@ -119,7 +119,7 @@ function handleClick() {
 
 - **Upload** - File upload component
 
-### Composables (13)
+### Composables (15)
 
 - **useTheme** - Theme and color mode management
 - **useModal** - Modal state with animation origin tracking
@@ -195,7 +195,7 @@ orio-ui/
 ├── src/
 │   ├── runtime/
 │   │   ├── components/   # 58 Vue components
-│   │   ├── composables/  # 13 composables
+│   │   ├── composables/  # 15 composables
 │   │   ├── assets/css/   # Theme CSS files
 │   │   └── utils/        # Icon registry
 │   └── module.ts         # Nuxt Module definition

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^3.0.0 || ^4.0.0"
   },
-  "version": "1.24.0",
+  "version": "1.27.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

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,51 @@
+# 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"
+/>
+```

package/dist/runtime/components/Calendar.vue

@@ -1,6 +1,7 @@
 <script setup>
-import { computed } from "vue";
+import { computed, ref, useId, watch } from "vue";
 import { useI18n } from "vue-i18n";
+import { useRovingGrid } from "../composables/useRovingGrid";
 import {
   addMonths,
   formatISO,
@@ -20,129 +21,286 @@ const emit = defineEmits(["select", "dayEnter"]);
 const { locale, t } = useI18n();
 const today = /* @__PURE__ */ new Date();
 const visibleMonth = computed(
-  () => startOfMonth(parseISO(anchor.value) ?? /* @__PURE__ */ new Date())
+  () => startOfMonth(
+    parseISO(anchor.value) ?? parseISO(props.selected) ?? /* @__PURE__ */ new Date()
+  )
 );
-function shift(delta) {
+function shiftMonth(delta) {
   anchor.value = formatISO(addMonths(visibleMonth.value, delta));
 }
+function shiftYear(delta) {
+  const target = new Date(visibleMonth.value);
+  target.setFullYear(target.getFullYear() + delta);
+  anchor.value = formatISO(startOfMonth(target));
+}
 const monthLabel = computed(
   () => new Intl.DateTimeFormat(locale.value, {
     month: "long",
     year: "numeric"
   }).format(visibleMonth.value)
 );
+const titleId = useId();
+const dayLabelFormat = computed(
+  () => new Intl.DateTimeFormat(locale.value, {
+    weekday: "long",
+    day: "numeric",
+    month: "long",
+    year: "numeric"
+  })
+);
+function fullDateLabel(iso) {
+  const date = parseISO(iso);
+  return date ? dayLabelFormat.value.format(date) : iso;
+}
 const weekdayLabels = computed(() => {
-  const sunday = new Date(2024, 0, 7);
-  return Array.from({ length: 7 }, (_, i) => {
-    const d = new Date(sunday);
-    d.setDate(sunday.getDate() + (i + props.weekStartsOn) % 7);
+  const tuesday = new Date(1998, 6, 14);
+  return Array.from({ length: 7 }, (_, position) => {
+    const date = new Date(tuesday);
+    date.setDate(
+      tuesday.getDate() + (position + props.weekStartsOn - 2 + 7) % 7
+    );
     return new Intl.DateTimeFormat(locale.value, { weekday: "short" }).format(
-      d
+      date
     );
   });
 });
-function resolveMarker(iso) {
-  if (props.getMarker) {
-    const m = props.getMarker(iso);
-    if (m) {
-      return {
-        variant: m.variant,
-        isStart: iso === m.start,
-        isEnd: iso === m.end
-      };
-    }
-  }
-  for (let i = props.markers.length - 1; i >= 0; i--) {
-    const m = props.markers[i];
-    if (iso >= m.start && iso <= m.end) {
-      return {
-        variant: m.variant,
-        isStart: iso === m.start,
-        isEnd: iso === m.end
-      };
-    }
-  }
-  return null;
+function resolveMarker(iso, reversedMarkers) {
+  const matched = props.getMarker?.(iso) ?? reversedMarkers.find(
+    (marker) => iso >= marker.start && iso <= marker.end
+  ) ?? null;
+  if (!matched) return null;
+  return {
+    variant: matched.variant,
+    isStart: iso === matched.start,
+    isEnd: iso === matched.end
+  };
 }
 const days = computed(() => {
-  const first = visibleMonth.value;
-  const startWeekday = first.getDay();
-  const offset = (startWeekday - props.weekStartsOn + 7) % 7;
-  const gridStart = new Date(first);
-  gridStart.setDate(gridStart.getDate() - offset);
-  const sel = parseISO(props.selected);
-  const result = [];
-  for (let i = 0; i < 42; i++) {
-    const d = new Date(gridStart);
-    d.setDate(gridStart.getDate() + i);
-    const iso = formatISO(d);
-    result.push({
+  const firstOfMonth = visibleMonth.value;
+  const leadingOffset = (firstOfMonth.getDay() - props.weekStartsOn + 7) % 7;
+  const gridStart = new Date(firstOfMonth);
+  gridStart.setDate(gridStart.getDate() - leadingOffset);
+  const selectedDate = parseISO(props.selected);
+  const reversedMarkers = [...props.markers].reverse();
+  return Array.from({ length: 42 }, (_, dayOffset) => {
+    const date = new Date(gridStart);
+    date.setDate(gridStart.getDate() + dayOffset);
+    const iso = formatISO(date);
+    return {
       iso,
-      label: d.getDate(),
-      inMonth: d.getMonth() === first.getMonth(),
-      isToday: isSameDay(d, today),
-      isSelected: !!sel && isSameDay(d, sel),
+      label: date.getDate(),
+      inMonth: date.getMonth() === firstOfMonth.getMonth(),
+      isToday: isSameDay(date, today),
+      isSelected: !!selectedDate && isSameDay(date, selectedDate),
       isDisabled: props.isDisabled?.(iso) ?? false,
-      marker: resolveMarker(iso)
-    });
+      marker: resolveMarker(iso, reversedMarkers)
+    };
+  });
+});
+const weeks = computed(
+  () => Array.from(
+    { length: 6 },
+    (_, weekIndex) => days.value.slice(weekIndex * 7, weekIndex * 7 + 7)
+  )
+);
+function isInVisibleMonth(date) {
+  return date.getMonth() === visibleMonth.value.getMonth() && date.getFullYear() === visibleMonth.value.getFullYear();
+}
+function initialActiveISO() {
+  const selectedDate = parseISO(props.selected);
+  if (selectedDate && isInVisibleMonth(selectedDate)) {
+    return formatISO(selectedDate);
+  }
+  if (isInVisibleMonth(today)) return formatISO(today);
+  return formatISO(visibleMonth.value);
+}
+const navButtons = computed(() => [
+  {
+    key: "year-prev",
+    ariaLabel: t("calendar.previousYear"),
+    icon: "chevron-left",
+    size: "md",
+    action: () => shiftYear(-1)
+  },
+  {
+    key: "month-prev",
+    ariaLabel: t("calendar.previousMonth"),
+    icon: "chevron-left",
+    size: "sm",
+    action: () => shiftMonth(-1)
+  },
+  {
+    key: "month-next",
+    ariaLabel: t("calendar.nextMonth"),
+    icon: "chevron-right",
+    size: "sm",
+    action: () => shiftMonth(1)
+  },
+  {
+    key: "year-next",
+    ariaLabel: t("calendar.nextYear"),
+    icon: "chevron-right",
+    size: "md",
+    action: () => shiftYear(1)
+  }
+]);
+const navRows = computed(() => [navButtons.value]);
+const navRef = ref(null);
+const {
+  tabindexFor: tabindexForNav,
+  setActive: setActiveNav,
+  onKeydown: onNavKeydown
+} = useRovingGrid({
+  rows: navRows,
+  gridRef: navRef,
+  getKey: (button) => button.key,
+  initial: () => "month-prev",
+  onActivate: (button) => button.action()
+});
+function onNavButtonClick(button) {
+  setActiveNav(button.key, false);
+  button.action();
+}
+const ARROW_DAY_DELTA = {
+  up: -7,
+  down: 7,
+  left: -1,
+  right: 1
+};
+const gridRef = ref(null);
+const { activeKey, setActive, tabindexFor, onKeydown } = useRovingGrid({
+  rows: weeks,
+  gridRef,
+  getKey: (day) => day.iso,
+  initial: initialActiveISO,
+  isNavigable: (day) => !day.isDisabled,
+  onActivate(day) {
+    if (day.isDisabled) return;
+    emit("select", day.iso);
+  },
+  onArrowOverflow(direction, currentKey) {
+    const date = parseISO(currentKey);
+    if (!date) return null;
+    const stepDays = ARROW_DAY_DELTA[direction];
+    for (let attempt = 0; attempt < 750; attempt++) {
+      date.setDate(date.getDate() + stepDays);
+      const iso = formatISO(date);
+      if (!props.isDisabled?.(iso)) return iso;
+    }
+    return null;
+  },
+  onPage(direction, bigJump, currentKey) {
+    const date = parseISO(currentKey);
+    if (!date) return null;
+    const monthDelta = (direction === "down" ? 1 : -1) * (bigJump ? 12 : 1);
+    const target = new Date(
+      date.getFullYear(),
+      date.getMonth() + monthDelta,
+      1
+    );
+    const lastDayOfTargetMonth = new Date(
+      target.getFullYear(),
+      target.getMonth() + 1,
+      0
+    ).getDate();
+    target.setDate(Math.min(date.getDate(), lastDayOfTargetMonth));
+    return formatISO(target);
+  }
+});
+watch(activeKey, (iso) => {
+  const date = parseISO(iso);
+  if (date && !isInVisibleMonth(date)) {
+    anchor.value = formatISO(startOfMonth(date));
   }
-  return result;
 });
-function onSelect(day) {
+function onDayClick(day) {
   if (day.isDisabled) return;
+  setActive(day.iso, false);
   emit("select", day.iso);
 }
-function onEnter(day) {
+function onDayMouseenter(day) {
   emit("dayEnter", day.iso);
 }
 </script>
 
 <template>
   <div class="calendar">
-    <div class="calendar-nav">
-      <orio-button
-        variant="subdued"
-        icon="chevron-left"
-        :aria-label="t('calendar.previousMonth')"
-        @click="shift(-1)"
-      />
-      <span class="calendar-month-title">{{ monthLabel }}</span>
-      <orio-button
-        variant="subdued"
-        icon="chevron-right"
-        :aria-label="t('calendar.nextMonth')"
-        @click="shift(1)"
-      />
+    <div
+      ref="navRef"
+      class="calendar-nav"
+      role="toolbar"
+      aria-orientation="horizontal"
+      :aria-label="t('calendar.navigation')"
+      @keydown="onNavKeydown"
+    >
+      <template v-for="(button, position) in navButtons" :key="button.key">
+        <orio-button
+          variant="subdued"
+          :icon="button.icon"
+          :size="button.size"
+          :focus-key="button.key"
+          :tabindex="tabindexForNav(button.key)"
+          :aria-label="button.ariaLabel"
+          @click="onNavButtonClick(button)"
+        />
+        <span v-if="position === 1" :id="titleId" class="calendar-month-title">
+          {{ monthLabel }}
+        </span>
+      </template>
     </div>
     <div class="calendar-weekdays">
-      <span v-for="w in weekdayLabels" :key="w" class="calendar-weekday">
-        {{ w }}
+      <span
+        v-for="weekday in weekdayLabels"
+        :key="weekday"
+        class="calendar-weekday"
+      >
+        {{ weekday }}
       </span>
     </div>
-    <div class="calendar-grid">
-      <button
-        v-for="day in days"
-        :key="day.iso"
-        type="button"
-        class="calendar-day"
-        :class="{
+    <div
+      ref="gridRef"
+      class="calendar-grid"
+      role="grid"
+      :aria-labelledby="titleId"
+      @keydown="onKeydown"
+    >
+      <div
+        v-for="(week, weekIndex) in weeks"
+        :key="weekIndex"
+        role="row"
+        class="calendar-week"
+      >
+        <button
+          v-for="day in week"
+          :key="day.iso"
+          type="button"
+          role="gridcell"
+          class="calendar-day"
+          :class="{
   'out-of-month': !day.inMonth,
   today: day.isToday,
   selected: day.isSelected,
   'has-marker': !!day.marker,
   [`marker-${day.marker?.variant}`]: !!day.marker,
   'marker-start': day.marker?.isStart,
-  'marker-end': day.marker?.isEnd
+  'marker-end': day.marker?.isEnd,
+  active: day.iso === activeKey
 }"
-        :disabled="day.isDisabled"
-        @click="onSelect(day)"
-        @mouseenter="onEnter(day)"
-      >
-        <orio-badge v-if="day.isSelected" pill variant="primary">
-          {{ day.label }}
-        </orio-badge>
-        <template v-else>{{ day.label }}</template>
-      </button>
+          :focus-key="day.iso"
+          :tabindex="tabindexFor(day.iso)"
+          :aria-selected="day.isSelected"
+          :aria-current="day.isToday ? 'date' : void 0"
+          :aria-label="fullDateLabel(day.iso)"
+          :disabled="day.isDisabled"
+          @click="onDayClick(day)"
+          @mouseenter="onDayMouseenter(day)"
+        >
+          <orio-badge v-if="day.isSelected" pill variant="primary">
+            {{ day.label }}
+          </orio-badge>
+          <template v-else>{{ day.label }}</template>
+        </button>
+      </div>
     </div>
   </div>
 </template>
@@ -157,18 +315,19 @@ function onEnter(day) {
   user-select: none;
   font-size: var(--control-font-size, var(--font-md));
   color: var(--color-text);
-  min-width: 17rem;
+  width: 22rem;
 }
 
 .calendar-nav {
   display: flex;
   align-items: center;
-  justify-content: space-between;
-  gap: 0.5rem;
+  gap: 0.25rem;
   margin-bottom: 0.5rem;
 }
 
 .calendar-month-title {
+  flex: 1;
+  text-align: center;
   font-weight: 600;
   text-transform: capitalize;
 }
@@ -179,6 +338,10 @@ function onEnter(day) {
   grid-template-columns: repeat(7, 1fr);
 }
 
+.calendar-week {
+  display: contents;
+}
+
 .calendar-weekday {
   text-align: center;
   font-size: var(--font-xs);
@@ -203,6 +366,10 @@ function onEnter(day) {
 .calendar-day:hover:not(:disabled):not(.has-marker):not(.selected) {
   background-color: var(--color-surface);
 }
+.calendar-day:focus-visible {
+  outline: 2px solid var(--color-accent);
+  outline-offset: -2px;
+}
 .calendar-day.out-of-month {
   color: var(--color-muted);
   opacity: 0.45;

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

@@ -0,0 +1,65 @@
+# Canvas — agent-only invariants
+
+Read this before integrating `<orio-canvas>` into a consumer app. Public API
+lives in `docs/components/canvas/`.
+
+## Invariants
+
+- **`name` prop is required.** It registers this canvas instance in the
+  module-level `canvasRegistry` (`./registry.ts`), which is how detached
+  toolbars find it. Without a `name`, a toolbar rendered outside the canvas
+  subtree cannot bind to it.
+- **Detached toolbar uses `canvas="<name>"`, not `provide/inject`.** Render
+  `<orio-canvas-toolbar canvas="editor" />` anywhere in the app — even in a
+  sibling subtree — and it resolves the context via the registry. Toolbars
+  nested as children of `<orio-canvas>` resolve via `useCanvasContext()`
+  inject and do not need the prop.
+- **Tools are pluggable, nothing ships by default.** Pass `:tools="[drawTool(),
+  textTool(), ...]"`. There are no implicit defaults.
+- **Tool factories are functions, not singletons.** Call `drawTool()` per
+  canvas instance — closure state (e.g. the in-progress stroke id) must not be
+  shared across canvases on the same page.
+- **`v-model:nodes` is the persistence boundary.** Serialize the array to JSON
+  for save/load. Unknown node types (tools not yet registered on hydrate) are
+  silently skipped on render — register the tool, then re-render.
+- **`frozen: true` nodes** are protected from `eraseTool`, `moveTool`,
+  `highlightTool` and future selection tools. Drawing/text passes ignore the
+  flag.
+- **`setup(api)` runs once on mount** with the full tool API. Use it to seed
+  initial nodes (frozen background images, watermark, etc.). It can add node
+  types whose tools are not in the user-facing `tools` prop — useful for
+  display-only nodes.
+
+## Gotchas
+
+- Tool `id` doubles as the node `type`. Two tools with the same id collide.
+- `setup` may be async; nodes added inside resolve before the first render.
+- Undo snapshot is finalized on `pointerUp` for `drawTool` — mid-stroke is not
+  a history step. If you script node creation outside a tool, call
+  `requestRender()` and rely on the next user action to checkpoint.
+- Custom fonts: no bundled loader. Caller is responsible for `document.fonts`
+  / `FontFace` loading before `textTool` renders that font.
+
+## Quick reference
+
+```vue
+<orio-canvas
+  name="editor"
+  v-model:nodes="nodes"
+  :tools="[drawTool(), textTool(), eraseTool(), undoTool()]"
+  :width="800"
+  :height="500"
+  :setup="(api) => api.addNode({ type: 'bg', frozen: true, ... })"
+/>
+
+<!-- elsewhere in the app -->
+<orio-canvas-toolbar canvas="editor" />
+```
+
+## Where things live
+
+- Types & `defineCanvasTool` → `./types.ts`
+- Context (`provide`/`inject`, `useCanvasContext`) → `./context.ts`
+- Registry (module-level Map for detached toolbars) → `./registry.ts`
+- Built-in tools → `./tools/*.ts`
+- Full spec → `./REQUIREMENTS.md`