orio-ui 1.24.0 → 1.28.0

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,73 @@
+---
+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
+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`

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/CheckBox.vue

@@ -10,19 +10,25 @@ 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 }
 });
 </script>
 
 <template>
-  <orio-control-element v-bind="props" class="checkbox" fill>
+  <orio-control-element v-slot="{ control }" v-bind="props" class="checkbox" fill>
     <label class="checkbox-label">
       <input
         v-model="modelValue"
+        v-bind="{ ...$attrs, ...control }"
         type="checkbox"
         class="checkbox-input"
         tabindex="-1"
-        v-bind="$attrs"
       />
       <span
         class="checkbox-box"

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