@cocoar/vue-ui 3.1.0 → 3.2.0-beta.6

package/skills/cocoar-vue-ui/references/components/calendar/day-view.md

@@ -0,0 +1,361 @@
+<!-- Generated from apps/docs/components/calendar/day-view.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# `<CoarDayView>` — Day View (Preview)
+
+Time-grid surface with two display choices: **One day** renders one fixed column, while **Multi-day** derives 1–7 complete columns from the available container width. Multi-day all-day events that touch the visible range appear in the all-day band pinned under the day headers. Use it standalone via [`useDayView()`](#usedayview) when you need the surface without the [`<CoarCalendar>`](./coar-calendar.md) shell.
+
+```html
+<CoarDayView :builder="builder" />
+```
+
+## Standalone usage
+
+```ts
+import { ref } from 'vue';
+import { Temporal } from '@js-temporal/polyfill';
+import {
+  CoarDayView,
+  useDayView,
+  type CalendarEvent,
+} from '@cocoar/vue-calendar';
+
+const events = ref<CalendarEvent[]>([
+  {
+    id: 'standup',
+    start: Temporal.ZonedDateTime.from('2026-04-15T09:00:00[UTC]'),
+    end:   Temporal.ZonedDateTime.from('2026-04-15T09:15:00[UTC]'),
+  },
+]);
+const date = ref('2026-04-15');
+
+const { builder, api } = useDayView();
+builder
+  .events(events)
+  .date(date)
+  .timezone('UTC')
+  .timeRange([8, 18])
+  .slotDuration(15)
+  .onTimeClick(({ time }) => console.log(time.toString()));
+```
+
+```html
+<CoarDayView :builder="builder" />
+```
+
+The Day view shares its builder type, `CalendarBuilder`, with the [Week view](./week-view.md) — they differ only in the days array the wrapper computes (Day uses `[date]`, Week uses `weekDates(date, fdow)`).
+
+## One day and Multi-day
+
+The shell presents both as variations under Day. Multi-day never squeezes partial columns into the available width: it calculates the number of full columns from `dayColumnMinWidth`, clamps the result to `1…7`, and honours `dayColumnCount` as its minimum.
+
+```ts
+builder
+  .dayMode('multiDay')
+  .dayColumnCount(1)
+  .dayColumnMinWidth(220);
+
+api.setDayMode('single');
+```
+
+For fixed seven-day and configured-workday grids, use [Week](./week-view.md) and [Work Week](./work-week-view.md). They share the same time-grid renderer.
+
+**Demo — `calendar/demos/DayViewBasic.vue`**
+
+```vue
+<template>
+  <div style="height: 600px; border: 1px solid var(--coar-border-neutral-tertiary); border-radius: var(--coar-radius-xs); overflow: hidden;">
+    <CoarDayView :builder="builder" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  CoarDayView,
+  useDayView,
+  Temporal,
+  type CalendarEvent,
+} from '@cocoar/vue-calendar';
+
+const date = ref(Temporal.PlainDate.from('2026-04-15'));
+
+const pd = (iso: string) => Temporal.PlainDate.from(iso);
+const zdt = (iso: string, tz = 'Europe/Vienna') =>
+  Temporal.ZonedDateTime.from(`${iso}[${tz}]`);
+
+const events = ref<CalendarEvent[]>([
+  // All-day band: a multi-day OOO that touches today.
+  {
+    id: 'devconf',
+    start: pd('2026-04-13'),
+    end: pd('2026-04-16'),
+    meta: { title: 'DevConf — Vienna', color: '#7c3aed' },
+  },
+  // Three timed events with a 3-deep overlap cluster.
+  {
+    id: 'standup',
+    start: zdt('2026-04-15T09:00:00'),
+    end: zdt('2026-04-15T09:30:00'),
+    meta: { title: 'Daily standup', color: '#10b981' },
+  },
+  {
+    id: 'design',
+    start: zdt('2026-04-15T11:00:00'),
+    end: zdt('2026-04-15T12:30:00'),
+    meta: { title: 'Design review', color: '#8b5cf6' },
+  },
+  {
+    id: 'pair',
+    start: zdt('2026-04-15T11:30:00'),
+    end: zdt('2026-04-15T13:00:00'),
+    meta: { title: 'Pair: calendar', color: '#f59e0b' },
+  },
+  {
+    id: 'lunch',
+    start: zdt('2026-04-15T12:00:00'),
+    end: zdt('2026-04-15T13:00:00'),
+    meta: { title: 'Lunch with Anna', color: '#ef4444' },
+  },
+  {
+    id: 'one-on-one',
+    start: zdt('2026-04-15T15:00:00'),
+    end: zdt('2026-04-15T15:45:00'),
+    meta: { title: '1:1 with Bernhard', color: '#3b82f6' },
+  },
+]);
+
+const { builder } = useDayView();
+builder
+  .events(events)
+  .date(date)
+  .timezone('Europe/Vienna')
+  // Apply drag/keyboard moves in place so the demo is interactive.
+  .onEventDrop(({ event, next }) => {
+    const idx = events.value.findIndex((e) => e.id === event.id);
+    if (idx < 0) return;
+    events.value = [
+      ...events.value.slice(0, idx),
+      { ...event, start: next.start, ...(next.end ? { end: next.end } : {}) },
+      ...events.value.slice(idx + 1),
+    ];
+  });
+</script>
+```
+
+## Working hours
+
+Constrain the visible hour range via `timeRange([startHour, endHour])` and tighten drag-snap precision via `slotDuration(15)` for a 15-minute grid. Events outside the visible window are still in the data set but invisible.
+
+**Demo — `calendar/demos/DayViewWorkingHours.vue`**
+
+```vue
+<template>
+  <div>
+    <p class="hint">
+      Visible hour range constrained to <code>[8, 18]</code>; slot
+      subdivision tightened to 15 min for finer drag-snap. The early
+      flight (5–7&nbsp;AM) is still in <code>events</code> but lives off
+      the visible window.
+    </p>
+    <div style="height: 520px; border: 1px solid var(--coar-border-neutral-tertiary); border-radius: var(--coar-radius-xs); overflow: hidden;">
+      <CoarDayView :builder="builder" />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  CoarDayView,
+  useDayView,
+  Temporal,
+  type CalendarEvent,
+} from '@cocoar/vue-calendar';
+
+const date = ref(Temporal.PlainDate.from('2026-04-15'));
+
+const zdt = (iso: string, tz = 'Europe/Vienna') =>
+  Temporal.ZonedDateTime.from(`${iso}[${tz}]`);
+
+const events = ref<CalendarEvent[]>([
+  // Off-window early — invisible at timeRange [8, 18].
+  {
+    id: 'red-eye',
+    start: zdt('2026-04-15T05:00:00'),
+    end: zdt('2026-04-15T07:30:00'),
+    meta: { title: 'Early flight', color: '#84cc16' },
+  },
+  {
+    id: 'standup',
+    start: zdt('2026-04-15T09:00:00'),
+    end: zdt('2026-04-15T09:15:00'),
+    meta: { title: 'Daily standup', color: '#10b981' },
+  },
+  {
+    id: 'review',
+    start: zdt('2026-04-15T10:30:00'),
+    end: zdt('2026-04-15T11:30:00'),
+    meta: { title: 'Design review', color: '#8b5cf6' },
+  },
+  {
+    id: 'lunch',
+    start: zdt('2026-04-15T12:00:00'),
+    end: zdt('2026-04-15T13:00:00'),
+    meta: { title: 'Lunch', color: '#ef4444' },
+  },
+  {
+    id: 'deep-work',
+    start: zdt('2026-04-15T13:15:00'),
+    end: zdt('2026-04-15T16:45:00'),
+    meta: { title: 'Deep work', color: '#2563eb' },
+  },
+]);
+
+const { builder } = useDayView();
+builder
+  .events(events)
+  .date(date)
+  .timezone('Europe/Vienna')
+  .timeRange({ startMinutes: 8 * 60, endMinutes: 18 * 60 })
+  .slotDuration(15)
+  .onEventDrop(({ event, next }) => {
+    const idx = events.value.findIndex((e) => e.id === event.id);
+    if (idx < 0) return;
+    events.value = [
+      ...events.value.slice(0, idx),
+      { ...event, start: next.start, ...(next.end ? { end: next.end } : {}) },
+      ...events.value.slice(idx + 1),
+    ];
+  });
+</script>
+
+<style scoped>
+.hint {
+  margin: 0 0 12px;
+  font-size: 13px;
+  color: var(--coar-text-subtle, #6b7280);
+}
+.hint code {
+  font-family: var(--coar-font-family-mono, monospace);
+  font-size: 12px;
+  background: var(--coar-background-neutral-tertiary, #f3f4f6);
+  padding: 1px 5px;
+  border-radius: 3px;
+}
+</style>
+```
+
+## Point events (timed, no `end`)
+
+A timed event without `end` keeps the default 30-minute slot geometry but renders distinguishably from a real 30-minute event: a solid start edge in the event color sits exactly on the start time, and the card body drops to ~38 % fill opacity — the title stays fully opaque. Resize handles are suppressed (there is no `end` to grab). Month and Agenda render point events unchanged. The look matches the SwiftUI port; tune it via `--coar-calendar-point-edge-height` / `--coar-calendar-point-body-opacity` (see [Theming](./index.md#theming)).
+
+## Overlapping timed cards
+
+Same cascade and compact-anatomy policy as the week view, tuned with `timedEventDetailMinWidth` — see [Overlapping timed cards](./week-view.md#overlapping-timed-cards).
+## Inside `<CoarCalendar>`
+
+`<CoarCalendar>` and `<CoarDayView>` consume the SAME `CalendarBuilder` instance — there's no sub-builder forking. Time-grid config goes directly on the composer's builder:
+
+```ts
+const { builder } = useCalendar();
+builder
+  .timeRange({ startMinutes: 8 * 60, endMinutes: 18 * 60 })
+  .slotDuration(15);
+```
+
+When the active view is day or week, the same builder feeds the embedded `<CoarTimeGrid>`. View-specific settings have no effect outside their view.
+
+## `useDayView<TMeta>()`
+
+```ts
+function useDayView<TMeta>(): {
+  builder: CalendarBuilder<TMeta>;
+  api: CalendarApi<TMeta>;
+};
+```
+
+Returns a fresh standalone builder + its imperative api. The builder type is the same `CalendarBuilder` used by `<CoarCalendar>` — `useDayView()` is a thin shorthand that pre-sets `view: 'day'`.
+
+## One model for every time grid
+
+Day, Multi-day, Week and Work week render on the same surface and are described by the same four parameters. The classic views are presets; `builder.timeGridRange(...)` lets the Day view use any other combination.
+
+| Parameter | Meaning | Values |
+|---|---|---|
+| `anchor` | Where the first column stands | `'cursor'`, or `'weekStart'` (cursor snapped to the locale's first day of the week) |
+| `span` | Days from the anchor | a number, or `'responsive'` (as many complete columns as the container width allows) |
+| `filter` | Which of those days are drawn | `'all'`, or `'workDays'` (the builder's `workDays`; the loader window still covers the whole span) |
+| `step` | How far `next` / `prev` / a swipe move the cursor | a number of days, or `'span'` (as many as are shown) |
+
+| View | anchor | span | filter | step |
+|---|---|---|---|---|
+| Day, `dayMode('single')` | cursor | 1 | all | span |
+| Day, `dayMode('multiDay')` | cursor | responsive | all | span |
+| Week | weekStart | 7 | all | 7 |
+| Work week | weekStart | 7 | workDays | 7 |
+
+"Start on Monday, show five days, page by a week" is one more spec:
+
+```ts
+builder.view('day').timeGridRange({ anchor: 'cursor', span: 5, filter: 'all', step: 7 });
+```
+
+Week and Work week are fixed presets and ignore `timeGridRange`; `null` restores the `dayMode` presets. Because there is one resolver (`resolveTimeGridRange`, exported from the core subpath) and one surface underneath, every grid feature — touch paging, the empty-cell hooks, the all-day lane cap — behaves identically across the four.
+
+## Touch paging
+
+On touch devices a horizontal pan on the day columns moves the grid with the finger — header cells, all-day band and columns together, the hour axis stays put — and pages to the previous / next range on release past a quarter of the width or on a fast flick. Below that the grid settles back. A touch that never moves is a tap and reaches `onTimeClick` on release, so a swipe never starts with a stray slot click. Vertical pans stay native scrolling. Mouse and pen keep their click-on-press semantics.
+
+While you drag, the **previous and next page** are drawn to the left and right of the current one — same columns, same events — so the gesture reads as paging between two visible pages; they are visual only and disappear once the grid settles. In loader mode the calendar pre-warms those two windows shortly after each page becomes visible (`builder.prefetchNeighbours(false)` switches that off; one extra fetch per neighbour), and `api.getEventsForWindow(window)` is the read behind it. In `events()` mode nothing needs fetching.
+
+The **day-name strip** at the top is a paging handle for every pointer type: a mouse drag across the day names pages the grid the same way (grab cursor), because there is nothing else to drag or click up there. On the columns themselves the mouse keeps its click-on-press semantics.
+
+`builder.swipeNavigation(false)` switches the gesture off. `prefers-reduced-motion` skips the settle animation and pages immediately. The same gesture is available on the Week and Work week grids.
+
+## Builder setters
+
+Full reference: see [the composer's API reference](./coar-calendar.md#api-reference). Highlights for the day view:
+
+| Setter | Argument | Default | Notes |
+|---|---|---|---|
+| `timeRange(r)` | `MaybeRefOrGetter<{ startMinutes, endMinutes }>` | `{0, 1440}` | Visible hour range, in minutes from midnight. Events outside are still rendered into the all-day band when applicable. |
+| `dayMode(m)` | `'single' \| 'multiDay'` | `'single'` | Fixed one-day column or width-aware multi-day range (the two Day presets of the time-grid model). |
+| `timeGridRange(spec)` | `MaybeRefOrGetter<TimeGridRangeSpec \| null>` | `null` | Explicit anchor / span / filter / step for the Day view — see "One model for every time grid". |
+| `dayColumnCount(n)` | `MaybeRefOrGetter<number>` | `1` | Minimum number of complete columns in Multi-day mode. |
+| `dayColumnMinWidth(px)` | `MaybeRefOrGetter<number>` | `220` | Target width used to derive additional columns, capped at seven. |
+| `slotDuration(d)` | `MaybeRefOrGetter<number>` | `30` | Slot subdivision (minutes). Also the snap step when dragging. |
+| `pixelsPerHour(p)` | `MaybeRefOrGetter<number>` | `60` | Vertical density. `60` = 30 px per 30-min slot. |
+| `eventRenderer(r)` | `EventRenderer<TMeta>` | — | Universal renderer. Branch on `ctx.layout?.kind === 'positioned'` (timed cards) vs `'allDayBar'` (all-day band). |
+| `dayHeaderRenderer(r)` | `DayHeaderRenderer` | — | Per-day column header. |
+
+## Imperative API
+
+```ts
+interface CalendarApi<TMeta> {
+  goTo(date: Temporal.PlainDate): void;
+  goToToday(): void;
+  next(): void;                            // ±1 day in day-view
+  prev(): void;
+  getVisibleRange(): ViewWindow | null;
+  getVisibleEvents(): CalendarEvent<TMeta>[];
+  scrollToTime(time: Temporal.PlainTime): void;   // Day / Week only
+  scrollToDate(date: Temporal.PlainDate): void;   // Agenda only
+  refresh(): void;
+  refreshRange(window: ViewWindow): void;
+  readonly loading: Readonly<Ref<boolean>>;
+  readonly visibleRange: Readonly<Ref<ViewWindow | null>>;
+  readonly gridReady: Readonly<Ref<boolean>>;
+}
+```
+
+## `<CoarDayView>` props + slots
+
+| Prop | Type | Description |
+|---|---|---|
+| `builder` | `CalendarBuilder` | **Required.** From `useDayView()` (or share the one from `useCalendar()`). |
+
+| Slot | Scope | Purpose |
+|---|---|---|
+| `event` | `{ event, layout }` | Per-event renderer. `layout` is the `PositionedEvent` (lane / startMinutes / endMinutes / clipping flags). |
+| `allDayEvent` | `{ event, layout }` | All-day band renderer. `layout` is the `AllDayBar` (lane / startCol / endCol / clipping flags). |
+| `dayHeader` | `{ date, isToday, isWeekend }` | Per-day column header. |

package/skills/cocoar-vue-ui/references/components/calendar/index.md

@@ -0,0 +1,312 @@
+<!-- Generated from apps/docs/components/calendar/index.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Calendar (Preview)
+
+A Vue 3 calendar whose visible hierarchy follows the iOS calendar: **Year**, **Month**, **Day** and **Agenda**, plus fixed **Week** and **Work week** time grids for web applications. Month and Day expose their display choices as nested variations instead of flattening every renderer into the primary view switcher.
+
+Events on the public surface use **`Temporal`** values directly (`PlainDate` for all-day, `ZonedDateTime` for timed) — there's no string parsing or implicit-zone guessing. Consumers convert their wire format (ISO strings, epoch ms, etc.) at the boundary; the calendar receives unambiguous values and runs all date math on them across DST boundaries.
+
+```ts
+import {
+  // Top-level shell + composer
+  CoarCalendar,
+  useCalendar,
+  // Sub-views — each usable standalone via a matching composable
+  CoarYearView,
+  CoarContinuousMonthView,
+  CoarMonthListView,
+  CoarMonthView,  useMonthView,
+  CoarDayView,    useDayView,
+  CoarWeekView,   useWeekView,
+  CoarAgendaView, useAgendaView,
+  // Drop-in display-zone selector (writes to a string ref consumed by `builder.timezone(ref)`)
+  CoarDisplayZoneSwitcher,
+  // Helper for surfacing C3 / C5 zone semantics in custom renderers
+  getEventZoneHints,
+  // Public types
+  type CalendarEvent,
+  type CalendarView,
+  type ViewWindow,
+  type EventZoneHints,
+} from '@cocoar/vue-calendar';
+```
+
+## Install
+
+```bash
+pnpm add @cocoar/vue-calendar
+```
+
+The component styles ship as one stylesheet on the `./styles` subpath. Import it once, next to the design-system styles:
+
+```ts
+import '@cocoar/vue-ui/styles';
+import '@cocoar/vue-calendar/styles';
+```
+
+### Localization
+
+Every visible label (`Today`, `Month`, `All day`, the a11y announcements, …) is looked up as a `coar.calendar.*` key through the host's `@cocoar/vue-localization` service, with English fallbacks inline. The package ships German and English catalogs plus a translation source, so a host registers them instead of maintaining the key list by hand:
+
+```ts
+import { createCoarLocalization } from '@cocoar/vue-localization';
+import { createCalendarTranslationSource, calendarMessages } from '@cocoar/vue-calendar';
+
+const localization = createCoarLocalization({ defaultLanguage: 'de-AT' });
+localization.service.addTranslationSource(createCalendarTranslationSource());
+app.use(localization);
+```
+
+Regional tags resolve to their base language (`de-AT` → `de`). A host source registered **after** the calendar's overrides per key, so app-specific wording still wins. `calendarMessages.en` / `.de` are the flat key → text maps for hosts that bundle one catalog file themselves. Date, time and weekday names are never in the catalog — they come from `Intl` (C6).
+
+## Two ways to use the calendar
+
+### As a single shell
+
+[`<CoarCalendar>`](./coar-calendar.md) is the all-in-one component: header with prev / today / next, a primary view switcher, nested Month / Day display controls, and the body that dispatches to whichever view is active. **One** `useCalendar()` builder feeds it; switching views is just `api.setView('agenda')`.
+
+```ts
+const { builder, api } = useCalendar();
+builder.events(events).date(date).timezone('Europe/Vienna');
+```
+
+```html
+<CoarCalendar :builder="builder" />
+```
+
+> **Tip: Use the shell when…**
+>
+> You want the complete view hierarchy, navigation chrome, and a consistent feel without writing custom layout. This is the path 90 % of consumers want.
+
+### As a single sub-view
+
+Each sub-view is exported and consumes its OWN `:builder` produced by a matching composable:
+
+| View | Component | Composable | Builder |
+|---|---|---|---|
+| Year | [`<CoarYearView>`](./year-view.md) | `useCalendar()` + `.view('year')` | `CalendarBuilder` |
+| Continuous Month | [`<CoarContinuousMonthView>`](./month-view.md) | `useCalendar()` + `.view('month')` | `CalendarBuilder` |
+| Month List | [`<CoarMonthListView>`](./month-view.md#month-list) | `useCalendar()` + `.view('monthList')` | `CalendarBuilder` |
+| Day | [`<CoarDayView>`](./day-view.md) | `useDayView()` | `CalendarBuilder` |
+| Week | [`<CoarWeekView>`](./week-view.md) | `useWeekView()` | `CalendarBuilder` |
+| Single Month Section | [`<CoarMonthView>`](./month-view.md#single-month-section) | `useMonthView()` | `CalendarBuilder` |
+| Agenda | [`<CoarAgendaView>`](./agenda-view.md) | `useAgendaView()` | `CalendarBuilder` |
+
+```ts
+const { builder } = useMonthView();
+builder.events(events).date(cursor).timezone('Europe/Vienna');
+```
+
+```html
+<CoarMonthView :builder="builder" />
+```
+
+> **Tip: Use a sub-view directly when…**
+>
+> You're building your own header / chrome, embedding the calendar in a larger layout, or only need one view forever. Sub-views skip the navigation header + view switcher entirely.
+
+The standalone composables and the shell composer share the same universal config surface (events / locale / timezone / density / handlers / renderers), so a renderer or handler written once works in either context. The flat `CalendarBuilder` carries every view's config — there are no per-view sub-builders to reach into.
+
+## Architecture invariants (C1–C8) {#invariants}
+
+Eight non-negotiable invariants drawn from the ["Time in Software, Done Right"][articles] article series. They're enforced **structurally** — by the type surface, by the test suite, by the single drop pipeline — not by convention. Other docs pages reference them by id (e.g. "Article 3 / C5"); this is the canonical reference.
+
+[articles]: https://dev.to/bwi/why-a-date-is-not-a-point-in-time-ad8
+
+| Article | Invariant | What it means |
+|---|---|---|
+| 1, 2, 4, 8 | **C1** Temporal-only public surface | Strings, `Date`, `PlainDateTime`, `Instant` rejected at the events-watcher boundary by `validateCalendarEvent`. Only `Temporal.ZonedDateTime` (timed) or `Temporal.PlainDate` (all-day) cross the wire. |
+| 4, 5 | **C2** Single drop pipeline | Exactly one function (`applyMoveToEvent`) converts a UI drop → new endpoints. Mouse, keyboard, touch all reach it once — same code path, same DST resolution, same payload shape. |
+| 4 | **C3** Source zone preserved per-endpoint | Cross-zone events are first-class. A Tokyo→Vienna flight keeps both endpoints in their source zones across every drag mode; the library never collapses both ends to one zone. |
+| 5 | **C4** DST disambiguation explicit | `DstPolicy` (`'compatible' \| 'reject' \| 'earlier' \| 'later'`) is a **required** parameter of every wall-time → instant conversion. No silent default — gap / overlap behaviour is always opted into. |
+| 3, 4 | **C5** Display zone vs source zone separated | `EventDropPayload.target.displayZone` (the zone the user's eyes saw) and `next.start.timeZoneId` (where the event actually lives) are distinct fields. Switching display zone never destroys event intent. |
+| 9 | **C6** Three independent display decisions | `locale`, `dateStyle`, `timeStyle`, `hour12` are independent setters, none derived from another. `buildFormatOptions(base, overrides)` is the only `Intl.DateTimeFormat` merge point. |
+| spirit | **C7** Reactivity by reads, not setup-captures | Every consumer function (`canDrop`, `eventsLoader`, `eventRenderer`, `dayHeaderRenderer`) is read on every invocation — never captured at setup. Mutating the builder mid-session always takes effect on the next call. |
+| 5 | **C8** Recurrence is a first-class type | `RecurringSeries` lives separately from `CalendarEvent`. RRULE / RDATE / EXDATE expand only for the visible window through the lazy bundled `rrule-temporal` engine, with occurrence provenance preserved for consumer-side series editing. |
+
+The conformance test suite at `src/core/__tests__/timezone/` pins every invariant; CI fails if any of them slips.
+
+## CalendarEvent shape
+
+The library reads the layout-relevant fields (`start`, `end`, `id`); anything you put in `meta` is opaque to the engine and forwarded back to your renderer / slot. Use the generic `CalendarEvent<TMeta>` to keep your meta strongly typed.
+
+```ts
+import { Temporal } from '@js-temporal/polyfill';
+
+interface CalendarEvent<TMeta extends Record<string, unknown> = Record<string, unknown>> {
+  /** Stable id. For occurrences of a recurring event, this is the SERIES id. */
+  id: string;
+  /**
+   * `ZonedDateTime` for timed events, `PlainDate` for all-day events.
+   * The shape of `start` discriminates the event type — there is no
+   * separate `allDay` flag.
+   */
+  start: Temporal.ZonedDateTime | Temporal.PlainDate;
+  /** Exclusive end. Must match `start`'s shape. Defaults to start + slot duration (timed) / start + 1 day (all-day). */
+  end?: Temporal.ZonedDateTime | Temporal.PlainDate;
+  /** Anything the consumer needs in their renderer. */
+  meta?: TMeta;
+}
+```
+
+Construct events directly from `Temporal`:
+
+```ts
+import { Temporal } from '@js-temporal/polyfill';
+
+// All-day event:
+{ id: 'devconf', start: Temporal.PlainDate.from('2026-04-13'), end: Temporal.PlainDate.from('2026-04-16') }
+
+// Timed event in UTC:
+{
+  id: 'standup',
+  start: Temporal.ZonedDateTime.from('2026-04-15T09:00:00[Europe/Vienna]'),
+  end:   Temporal.ZonedDateTime.from('2026-04-15T09:30:00[Europe/Vienna]'),
+}
+
+// Timed event in a specific zone:
+{
+  id: 'vienna-call',
+  start: Temporal.ZonedDateTime.from('2026-06-15T10:00:00[Europe/Vienna]'),
+  end:   Temporal.ZonedDateTime.from('2026-06-15T11:00:00[Europe/Vienna]'),
+}
+```
+
+The default event renderer reads `meta.title` and `meta.color` if present. Drop those in `meta` to skip writing a custom renderer for simple cases. Text on the coloured surface is black or white by contrast policy (`builder.eventTextContrast('wcag' | 'apca')`); `meta.textColor` (any CSS colour) overrides that choice for one event — tones on the fence are a design decision, not a computation.
+
+## Display zone — switcher + on-card hints
+
+Every event keeps its **source** zone (`start.timeZoneId`); the calendar renders it in whatever **display** zone the builder is configured with (`.timezone(ref)`). The two are kept separate by design — invariant C5 — so switching the display zone never destroys event intent. Two pieces of UI surface this distinction without writing any custom renderer:
+
+```ts
+import { CoarDisplayZoneSwitcher, getEventZoneHints } from '@cocoar/vue-calendar';
+
+const tz = ref(Intl.DateTimeFormat().resolvedOptions().timeZone);
+const { builder } = useCalendar();
+builder.timezone(tz);
+```
+
+```html
+<CoarDisplayZoneSwitcher v-model="tz" />
+<CoarCalendar :builder="builder" />
+```
+
+`<CoarDisplayZoneSwitcher>` is a `<CoarSelect>` pre-populated with a curated short-list of common zones plus the browser-detected zone — pass `:options="..."` to swap in a domain-specific list (or `Intl.supportedValuesOf('timeZone')` for the full IANA roster).
+
+The default event renderers also surface two zone semantics inline on every card:
+
+- **Globe icon** when `start.timeZoneId === 'UTC'` — Article 5's "global event, same instant worldwide" (product launches, livestreams).
+- **Cross-zone tag** (globe + accent dot) + tooltip when `start.timeZoneId` differs from the display zone — Article 3's fairness contract: we render the user's clock but don't hide where the event actually lives.
+
+Both are rendered with `title=""` tooltips and an inline sr-only span for screen readers. The two are mutually exclusive — a UTC-anchored event in a non-UTC display gets only the global icon. Custom renderers can re-use the same logic via `getEventZoneHints(event, displayZone)`:
+
+```ts
+import { getEventZoneHints } from '@cocoar/vue-calendar';
+
+builder.eventRenderer((ctx) => {
+  const { isUtcAnchored, sourceZone } = getEventZoneHints(ctx.event, displayZone.value);
+  // …draw whatever icon / chip / accent suits your design.
+});
+```
+
+## Reactive configuration
+
+Every config setter accepts `MaybeRefOrGetter<T>` — pass a static value, a `ref()`, or a `() => …` getter and Vue tracks whatever shape you give it.
+
+```ts
+const { builder } = useCalendar();
+
+builder.timezone('Europe/Vienna');               // static
+builder.timezone(timezoneRef);                   // ref
+builder.density(() => narrow.value ? 'compact' : 'comfortable');  // getter / computed
+```
+
+This applies to the one flat builder shared by the shell and to every standalone sub-view builder.
+
+## Theming
+
+The calendar reads CSS custom properties at runtime, so themes apply the moment you set them on any ancestor — typically `:root`, the calendar's wrapper, or a per-instance class.
+
+Two layers of tokens. **Calendar-specific** tokens are unique to this component and override only what would otherwise inherit from the design system. **Inherited DS tokens** are the shared `--coar-*` palette / type / radius scale every Cocoar component uses; they're listed here for completeness so consumers know what to set if they're embedding the calendar in a non-Cocoar host.
+
+### Calendar-specific
+
+| Token | Light | Dark | Purpose |
+|---|---|---|---|
+| `--coar-color-accent` | → `--coar-color-accent-500`, then `#2563eb` | same | Today markers (day number, column header, agenda badge), default event fill in list surfaces, cross-zone hint dot. Never defined by the package: it follows the vue-ui accent ramp (so `--coar-accent` rebrands it) unless the host sets it explicitly. |
+| `--coar-calendar-bg` | `#fff` | `#18181b` | Background of every cell, header, and band. |
+| `--coar-calendar-bg-today` | `rgba(37, 99, 235, 0.04)` | `#2563eb24` | Today highlight on month cells + day-column tint. |
+| `--coar-calendar-bg-weekend` | `#f6f7f9` | `#212125` | Weekend tint (Sat/Sun) on month cells + day-columns. |
+| `--coar-calendar-bg-other-month` | `#fafafb` | `#131316` | Leading / trailing days outside the active month. |
+| `--coar-calendar-border` | `#d1d5db` | `#3f3f46` | Cell borders, header underlines, axis dividers. |
+| `--coar-calendar-grid-line` | `#e3e5e9` | `#2c2c30` | The slot-line gradient inside time-grid columns. |
+| `--coar-calendar-agenda-divider` | → `--coar-calendar-border`, then `#f3f4f6` | `#27272a` | Row separator between agenda entries. |
+| `--coar-calendar-event-default-bg` | → `--coar-color-accent-soft`, then `#93c5fd` | `#1e3a8a` | Fill of events without a `meta.color`. |
+| `--coar-calendar-point-edge-height` | `3px` | — | Start-edge bar on point events (timed, no `end`) in Day / Week. |
+| `--coar-calendar-point-body-opacity` | `0.38` | — | Body fill opacity of point events (title stays fully opaque). |
+| `--coar-calendar-scroll-inset-bottom` | `0px` | — | Extra scroll room at the bottom of every scrolling surface (Day / Week grids, Month, List, Agenda, Timeline, Year), so the last rows can clear host chrome that overlays the bottom edge. See [Host chrome over the bottom edge](#host-chrome-over-the-bottom-edge). |
+| `--coar-time-grid-axis-width` | `80px` | — | Width of the hour-axis on the left of Day / Week. |
+| `--coar-time-grid-header-height` | _auto_ | — | Sticky day-of-week header min-height. |
+
+Light values are per-usage `var()` fallbacks — the tokens are undefined in light mode, so a single override anywhere wins. Dark values ship with the package stylesheet (see below).
+
+### Host chrome over the bottom edge
+
+On phones something almost always sits over the bottom of the viewport — a tab bar, a floating action button, the home-indicator safe area. Padding *around* the calendar doesn't help: the scroll container is inside the component, and outer padding shrinks the surface instead of letting the content scroll past the overlay. `--coar-calendar-scroll-inset-bottom` adds that room *inside* every scrolling surface (the same content inset the iOS calendar applies), and keyboard / focus scrolling honours it through `scroll-padding-bottom`.
+
+```css
+/* A 56 px bottom bar plus the device's safe area. */
+.my-app .coar-calendar {
+  --coar-calendar-scroll-inset-bottom: calc(56px + env(safe-area-inset-bottom));
+}
+```
+
+The token is read at runtime, so it can change with the host's layout (a bar that hides while scrolling, a sheet that opens). Standalone sub-views read it the same way.
+### Inherited from the design system
+
+Used as direct `var()` references. Override at the design-system level rather than per-calendar-instance unless you need a calendar-only variant.
+
+| Group | Tokens |
+|---|---|
+| Palette | `--coar-color-accent`, `--coar-color-accent-soft`, `--coar-color-danger`, `--coar-background-accent-primary`, `--coar-background-neutral-primary`, `--coar-background-neutral-tertiary`, `--coar-surface-subtle` |
+| Text | `--coar-text-base`, `--coar-text-subtle` (calendar-local names — not defined by `@cocoar/vue-ui`; dark values ship with this package), `--coar-text-neutral-primary` |
+| Type | `--coar-font-size-base`, `--coar-font-size-sm`, `--coar-font-size-xs`, `--coar-body-base-family` |
+| Shape | `--coar-radius-md`, `--coar-radius-xs`, `--coar-border-neutral-tertiary` |
+
+### Dark mode
+
+Dark values for every calendar token ship with the package stylesheet — no consumer CSS needed. They activate on either trigger:
+
+- `.dark-mode` class on `<html>` or any ancestor (the Cocoar convention, same as `@cocoar/vue-ui`)
+- `[data-theme="dark"]` attribute
+
+The values mirror the SwiftUI port (`Cocoar.Calendar.iOS`, `CalendarTheme.dark`), so web and iOS render identically dark. Accent and danger stay scheme-invariant, and event colors provided via `meta.color` are **not** remapped in either mode — dark-safe event palettes are the consumer's responsibility.
+
+To customize, redefine any token under the same trigger after the package styles:
+
+```css
+.dark-mode,
+[data-theme='dark'] {
+  --coar-calendar-bg: #101014;
+}
+```
+
+> **Tip: RTL**
+>
+> Layout-mirroring for `direction: rtl` is **not yet** wired (multi-day bars, resize handles, sticky-header positioning all assume LTR). If you need RTL support, open an issue — the math is mostly localised to the bar / handle inset calc()s, but it deserves a deliberate pass with proper test coverage rather than a one-shot patch.
+
+## Performance notes
+
+- **Variable-size virtualization.** The agenda surface uses a Fenwick-tree-backed measurement cache so every day-row keeps its natural height (header ~37 px, event ~42 px) without breaking anchor-restoration when the user scrolls.
+- **No recycling pool.** Vue's keyed v-for diff turned out faster than a stable pool for typical slot content. Heavy custom renderers (charts, video) might still benefit; the surface accepts a custom recycling pool if needed.
+- **Cluster-aware lane sizing.** Events with no transitive overlap render at full width even when busy parts of the same day have 3-deep stacks. Matches Google / Outlook behaviour.
+- **LoAF, not rAF.** The CI perf gate measures Long Animation Frame entries; rAF FPS is unreliable under wheel-scroll on Chrome (input dispatch defers callbacks 1-2 vsync ticks without producing visual jank).
+
+## Where to next
+
+- **[`<CoarCalendar>` (composer)](./coar-calendar.md)** — the top-level shell + the full builder API reference.
+- **[Year View](./year-view.md)** — responsive twelve-month overview and drill-in.
+- **[Month Views](./month-view.md)** — continuous Compact / Stacked / Details months and responsive Month List.
+- **[Day View](./day-view.md)** — one-day or width-aware multi-day time-grid surface.
+- **[Week View](./week-view.md)** — 7-day time-grid + all-day band.
+- **[Agenda View](./agenda-view.md)** — virtualized chronological list grouped by day.