---
url: /guide/getting-started.md
---
# Getting Started

Set up the Cocoar Design System in your Vue 3 project in a few steps.

## 1. Install

```bash
pnpm add @cocoar/vue-ui
```

## 2. Import Fonts & Styles

Import fonts and styles in your app's entry point. Fonts are self-hosted via `@fontsource` — no external CDN needed.

```ts
// main.ts
import '@cocoar/vue-ui/fonts';   // Poppins + Inter (self-hosted)
import '@cocoar/vue-ui/styles';  // Design tokens + component styles
```

::: info Bring your own fonts?
The font import is optional. If you prefer a CDN or custom fonts, skip `@cocoar/vue-ui/fonts` and load them yourself. Components fall back to system fonts gracefully.
:::

## 3. Use Components

Import components directly — no global registration required. Tree-shaking is automatic.

```vue
<script setup>
import { CoarButton } from '@cocoar/vue-ui';
</script>

<template>
  <CoarButton>Hello Coar</CoarButton>
</template>
```

## 4. Dark Mode

Toggle dark mode by adding the `.dark-mode` class to the root element. All design tokens and components adapt automatically.

```ts
document.documentElement.classList.toggle('dark-mode', isDark);
```

## 5. Overlay System

For components that render overlays (Dialog, Toast, Popover, Tooltip), register the plugin once:

```ts
// main.ts
import { createApp } from 'vue';
import { CoarOverlayPlugin } from '@cocoar/vue-ui';

createApp(App)
  .use(CoarOverlayPlugin)
  .mount('#app');
```

And add the overlay host to your root layout:

```vue
<template>
  <router-view />
  <CoarOverlayHost />
</template>
```

## Date/Time Components

The date and time pickers use the [Temporal API](https://tc39.es/proposal-temporal/docs/) via `@js-temporal/polyfill`, which is included as a dependency of `@cocoar/vue-ui`. No extra install needed. When native Temporal support reaches all browsers, the polyfill can be dropped in a future major release.

## Additional Packages

Optional packages for extended functionality:

```bash
pnpm add @cocoar/vue-localization   # i18n & timezone
pnpm add @cocoar/vue-data-grid      # AG Grid wrapper
pnpm add @cocoar/vue-markdown       # Markdown viewer
```

---

---
url: /guide/error-handling.md
---
# Error Handling

Cocoar UI components are designed to fail gracefully. Internal errors are either caught and recovered silently, or surfaced to the user through controlled feedback mechanisms. This guide explains the patterns used throughout the library and how to handle errors in your own application code.

## Library Philosophy: Fail Gracefully

Components never throw unhandled exceptions into your application. Instead they follow one of two patterns:

* **Silent fallback** — return a safe default (`null`, `'UTC'`, `false`) and continue
* **User feedback** — surface the error visibly via a Toast or state change

## Overlay Promises

`CoarDialog` and `CoarPopconfirm` return Promises. Always handle the rejection case:

```ts
import { useDialog } from '@cocoar/vue-ui';

const dialog = useDialog();

// ✅ Always add .catch()
dialog.confirm({
  title: 'Delete item',
  message: 'This cannot be undone.',
})
  .then((confirmed) => {
    if (confirmed) deleteItem();
  })
  .catch(() => {
    // Dialog was closed unexpectedly (e.g. overlay destroyed before user responded)
  });
```

With async/await:

```ts
try {
  const confirmed = await dialog.confirm({ title: 'Delete item', message: '...' });
  if (confirmed) await deleteItem();
} catch {
  // Handle unexpected close
}
```

::: tip Popconfirm
`CoarPopconfirm` emits `@confirmed` and `@cancelled` events — no Promise handling needed there. Use it for simple inline confirmations, and reserve `useDialog()` for programmatic flows where error handling is more important.
:::

## Toast for Error Feedback

Use `useToast().error()` to surface errors to the user. Error toasts are persistent by default (duration `0`) — they stay until the user dismisses them, which is appropriate for errors that require attention.

```ts
import { useToast } from '@cocoar/vue-ui';

const toast = useToast();

async function saveData() {
  try {
    await api.save(payload);
    toast.success('Saved successfully');
  } catch (err) {
    toast.error('Save failed', {
      message: err instanceof Error ? err.message : 'Please try again.',
    });
  }
}
```

```ts
// With a retry action
toast.error('Connection lost', {
  message: 'Could not reach the server.',
  action: {
    label: 'Retry',
    callback: () => saveData(),
  },
});
```

## Date and Time Parsing

Date parsing functions return `null` on failure instead of throwing. Always null-check the result before using it:

```ts
import { coarParsePlainDate } from '@cocoar/vue-ui';

const date = coarParsePlainDate(userInput);

if (date === null) {
  // Input was invalid — show validation error
  toast.error('Invalid date format');
  return;
}

// date is a Temporal.PlainDate — safe to use
processDate(date);
```

The date picker components handle this internally — invalid input simply doesn't update the model value. Your `v-model` will remain `null` until the user enters a valid date.

## Timezone Fallbacks

Timezone utilities default to `'UTC'` when the browser API fails or the timezone identifier is unrecognised. This keeps date/time components functional even in restricted environments:

```ts
import { useTimezone } from '@cocoar/vue-localization';

const { timezone } = useTimezone();
// Always a valid IANA identifier — 'UTC' as last resort
```

## Async Operations in Overlays

When loading data inside a Dialog or Popover, manage loading and error states yourself:

```vue
<script setup>
import { ref } from 'vue';
import { useDialog, useToast } from '@cocoar/vue-ui';

const dialog = useDialog();
const toast = useToast();

async function openEditDialog(id: string) {
  let data;
  try {
    data = await fetchItem(id);
  } catch {
    toast.error('Could not load item');
    return; // Don't open the dialog if data failed to load
  }

  const saved = await dialog.confirm({
    title: 'Edit item',
    // ... pass data to dialog body component
  }).catch(() => false);

  if (saved) {
    try {
      await saveItem(data);
      toast.success('Saved');
    } catch {
      toast.error('Save failed');
    }
  }
}
</script>
```

## Pattern Summary

| Situation | Recommended pattern |
|-----------|---------------------|
| Dialog/Popconfirm result | `.then().catch()` or `try/await/catch` |
| API call in component | `try/catch` + `toast.error()` |
| Date input validation | Null-check return value of parse functions |
| Non-recoverable error | `toast.error()` with persistent duration (default) |
| Recoverable error | `toast.error()` with `action: { label: 'Retry', callback }` |
| Silent failures OK | Rely on library defaults (`null`, `'UTC'`, `false`) |

---

---
url: /guide/theming.md
---
# Theming

Cocoar uses an **oklch-based** color system. You set a few base colors, and the entire palette — including all shades for light and dark mode — is auto-calculated.

## Quick Start

Override the CSS custom properties on `:root` to match your brand:

```css
:root {
  --coar-accent: #1183CD;   /* Your brand color → primary buttons, links, focus rings */
}
```

That's it. All accent shades (50–900), in both light and dark mode, recalculate from this single value.

## Customizable Base Colors

| Variable | Default | Purpose |
|----------|---------|---------|
| `--coar-accent` | `#1183CD` | Brand/accent color — primary buttons, active states, links |
| `--coar-success` | `#1e8f48` | Success states — confirmations, positive feedback |
| `--coar-error` | `#d63b3b` | Error states — validation errors, destructive actions |
| `--coar-warning` | `#cc821f` | Warning states — caution, attention needed |
| `--coar-info` | `#5e6b84` | Info states — neutral informational context |

### Example: Red Brand

```css
:root {
  --coar-accent: #C41E3A;   /* Red brand */
  --coar-error:  #8B0000;   /* Darker red so errors are distinguishable */
}
```

### Example: Purple Brand

```css
:root {
  --coar-accent: #7C3AED;
}
```

## How It Works

Each base color generates a 10-step shade scale using **oklch relative color syntax**:

```css
/* You set this: */
--coar-accent: #1183CD;

/* The library calculates these: */
--coar-color-accent-50:  oklch(from var(--coar-accent) 0.97 0.012 h);  /* lightest */
--coar-color-accent-100: oklch(from var(--coar-accent) 0.92 0.035 h);
--coar-color-accent-200: oklch(from var(--coar-accent) 0.84 0.075 h);
/* ... */
--coar-color-accent-500: var(--coar-accent);                            /* = your exact color */
/* ... */
--coar-color-accent-900: oklch(from var(--coar-accent) 0.31 0.095 h);  /* darkest */
```

The `h` (hue) is extracted from your color. Lightness and chroma follow a designed curve that keeps shades vibrant instead of washed out. `accent-500` is always your exact brand color.

This works because **oklch is perceptually uniform** — unlike HSL, a lightness of 0.5 in oklch looks equally "medium" for blue, red, and yellow.

## Fine-Tuning Individual Shades

If an auto-calculated shade doesn't look right for your specific color, override it:

```css
:root {
  --coar-accent: #FF6600;

  /* Auto-calculated 50 too warm? Override just that one: */
  --coar-color-accent-50: #FFF5EB;
}
```

## Dark Mode

Dark mode shades are calculated from the same base variables — no need to set anything extra. The library uses a separate lightness/chroma curve designed for dark backgrounds:

* Low numbers (50–200): dark with a subtle color tint
* Mid range (300–500): vibrant and saturated
* High numbers (600–900): lighter for text on dark backgrounds

The primary button color (`accent-500`) stays identical in both modes.

## Browser Support

The oklch color system requires:

* Chrome 119+
* Firefox 128+
* Safari 18+

This covers all modern browsers. For older browsers, consider providing hex fallbacks for your specific brand color.

---

---
url: /guide/changelog.md
---

# Changelog

All notable changes to the Cocoar Design System (Vue) will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
Versions are calculated automatically by [GitVersion](https://gitversion.net/).

***

## 2.0.0

This release lands the calendar package's largest feature push since it shipped in 1.16.0 — the C8 recurrence pipeline is wired end-to-end, three previously-reserved or missing view IDs (`workWeek`, `timeline`) become real working components, and the event-interaction surface picks up hover handlers so consumers can wire their own popovers / tooltips via `@cocoar/vue-ui`'s overlay system. None of the changes are strictly breaking — the new shapes are additive — but the surface delta is large enough that a major bump is the honest signal. `@cocoar/vue-data-grid`, `@cocoar/vue-script-editor`, `@cocoar/vue-markdown-editor`, `@cocoar/vue-fragment-parser`, and `@cocoar/vue-ui` ride along on the same monorepo cadence; only one user-visible UI fix in this release (popover-preset export gap).

### Added

* **`@cocoar/vue-ui` — `CoarPlainDateView` / `CoarPlainDateTimeView` / `CoarZonedDateTimeView` display components**: read-only Temporal-typed date / date-time / zoned-date-time displays paired with the existing picker family. Each viewer mirrors its picker's `formatValue` logic exactly (same `useDatePickerBase` for locale + date-format resolution, same `coarFormatPlainDate` + `coarFormatTime` + `coarFormatTimezoneLabel` helpers) so a read-only display and the editor's resting state look identical. Props: `value`, `locale?`, `dateFormat?`, `placeholder?`, `size?`; `CoarPlainDateTimeView` adds `use24Hour?: boolean | 'auto'` (defaults to locale detection); `CoarZonedDateTimeView` adds `displayTimeZone?: string` (project all values into a single zone), `showTimeZone?: boolean` (toggle the trailing `GMT+1`-style label), and `use24Hour?`. **Cross-realm-safe type checks**: each viewer uses `Symbol.toStringTag` instead of `instanceof Temporal.X`, so a Temporal value created against one polyfill copy (e.g. inside `@cocoar/vue-ui`) still renders correctly when read by another package that resolves a different `@js-temporal/polyfill` path under pnpm's isolated dependency tree. **Reactive locale**: `useDatePickerBase` already tracks the consumer-app `useL10n().language` ref, so display updates on language change without consumer wiring. Use these anywhere you'd show a date without an editor — cards, dialogs, list rows, data-grid cells. 18 new unit tests across the three viewer components (rendering, format resolution, null handling, cross-realm duck-type acceptance, displayTimeZone projection). Total `@cocoar/vue-ui` suite 1211 tests across 60 files.
* **`@cocoar/vue-data-grid` — `col.plainDate()` / `col.plainDateTime()` / `col.zonedDateTime()` column shortcuts**: three new Temporal-typed column factories for date / date-time / zoned-date-time cells. Each pairs a locale-aware renderer (formats via `toLocaleString` with date-style: medium; `plainDateTime` adds time-style: short; `zonedDateTime` adds short zone-name suffix so cross-zone columns stay unambiguous at a glance) with an editor that wraps the matching picker from `@cocoar/vue-ui` (`CoarPlainDatePicker` / `CoarPlainDateTimePicker` / `CoarZonedDateTimePicker`). Cell values are `Temporal.PlainDate | null` / `Temporal.PlainDateTime | null` / `Temporal.ZonedDateTime | null` — strict typing, matching `@cocoar/vue-calendar`'s contract so dates round-trip between the grid and the calendar without conversion shims. Configurators expose the middle-tier picker surface: `.size()`, `.clearable()`, `.min()`, `.max()`, `.showWeekNumbers()`, `.highlightWeekends()`, `.markers()` (static or per-row function), `.locale()`. `col.zonedDateTime()` additionally exposes `.timeZone()` (default IANA zone for newly-created values; existing values keep their own zone) and `.timezoneFilter()` (wildcard patterns like `['Europe/*', 'America/*']`). Editor lifecycle matches the other Coar cell editors: `afterGuiAttached` focuses the trigger so the picker's keyboard handlers fire (arrow-key scrolls-page bug fixed at the source), focus-preservation prevents AG Grid from committing prematurely while the user navigates the body-teleported panel, commit happens via `getValue()` on Tab / Enter / click-outside. The legacy `col.date(field, config?)` shortcut (display-only, accepts `Date | string`) is unchanged for back-compat. `@js-temporal/polyfill` is now a peer dependency of `@cocoar/vue-data-grid`. 11 new factory tests; total data-grid suite 258 tests across 8 files. Docs page at `/components/data-grid/date-columns` with three live demos (PlainDate task scheduling, PlainDateTime reminders, ZonedDateTime cross-zone meetings).
* **`@cocoar/vue-data-grid` — `col.multiSelect(field, s => …)` and `col.tagSelect(field, s => …)` column shortcuts**: two new factory methods for multi-value cells. Both store the cell value as `T[]` and share one renderer (`CoarMultiSelectCellRenderer`) — comma-separated label lookup by default, `.display('chips')` opts into one `<CoarTag>` per value. `col.multiSelect()` editor wraps `<CoarMultiSelect>` (checkbox-list dropdown, `.searchable()` / `.showSelectAll()` / `.clearable()` available); `col.tagSelect()` editor wraps `<CoarTagSelect>` (chip-style trigger, dropdown shows only not-yet-selected, `.allowCreate()` accepts free-form values that round-trip into the array verbatim — the renderer falls back to `String(value)` for unknown labels). Both editors auto-open via `afterGuiAttached` and use focus-preservation (capture-phase `mousedown` listener that `preventDefault`s on `.coar-overlay-host` targets) so the dropdown stays open while the user toggles options; unlike `col.select()`'s auto-commit-per-pick, AG Grid only commits when the user finishes (click outside / Tab / Enter — `getValue()` returns the final array). Row-aware options work via `s.options(row => …)`. Configurators (`MultiSelectColumnConfigurator`, `TagSelectColumnConfigurator`) export from the package root; `MultiSelectCellEditorConfig` is the shared editor params type. 11 new factory tests; total data-grid suite 247 tests across 8 files. Docs page at `/components/data-grid/multi-select` with live demo (both variants side-by-side).
* **`@cocoar/vue-ui` — `CoarOtpInput` component**: N-cell input for 2FA / TOTP / SMS verification codes — the pattern where each digit lives in its own box, focus auto-advances on type, jumps back on Backspace-empty, and pastes spread across cells. Replaces the long-standing pain of using a regular `CoarTextInput` for 6-digit codes (typing fast, then Enter or mouse-to-OK). Fires a `complete(value)` event the moment the last cell fills so consumers can auto-submit without an OK button. `length` prop (default `6`) covers 4-digit PINs and 8-digit backup codes alike; `type: 'numeric' | 'alphanumeric' | 'text'` (default `'numeric'`) drives both keystroke filtering and the mobile keyboard hint via `inputmode`; `mask` renders cells as `<input type="password">` for shared-screen contexts. Sizes match the form-input family (`xs` / `s` / `m` / `l`) and the component picks up `error` + `required` automatically when wrapped in `CoarFormField` via the existing FORM\_FIELD\_INJECTION\_KEY pattern. First cell carries `autocomplete="one-time-code"` so iOS / Android offer the SMS-autofill chip on the right cell. Keyboard model: Type → fill + advance, Backspace on empty → jump-back-and-clear, Backspace on filled → clear, Delete → clear in place, Arrows + Home/End → navigate, Tab → exits the group (the OTP input is effectively one tab-stop). Paste handler accepts a multi-character clipboard payload starting at any cell and spreads it forward, stripping characters that don't match `type` first. Two optional hooks fine-tune per-character behaviour beyond the built-in classes: `transform: (char) => string` rewrites or drops a character before commit (e.g. `c => c.toUpperCase()` so users can type lowercase claim codes), and `accept: (char) => boolean` adds a per-char reject predicate that ANDs with `type` (e.g. `c => !/[O0lI1]/.test(c)` to block visually-ambiguous chars in printed claim codes). Both hooks fire on single-char input AND on every char of paste-spread — paste runs through the same sanitizer. ARIA: `role="group"` with `aria-label="Verification code, N digits"`, each cell has `aria-label="Digit i of N"`, `aria-invalid` propagates from the error state. 24 unit tests cover the full surface (cell rendering, v-model in/out, numeric filtering, Backspace jump-back, Delete clear, paste spread, complete event, disabled / readonly / error states). Lives at `packages/ui/src/components/otp-input/`; types `CoarOtpInputProps`, `CoarOtpInputSize`, `CoarOtpInputType` exported from the package root. Docs page at `/components/otp-input` with five live demos.
* **`@cocoar/vue-calendar` — `onEventHover` / `onEventHoverLeave` handlers**: fire on `pointerenter` / `pointerleave` over any event element in any view (day / week / workWeek / month / agenda / timeline). Payload mirrors `onEventClick`: `{ event, native: PointerEvent }`. `native.currentTarget` is the event-element DOM node — pass it directly to `useOverlay({ anchor: { kind: 'element', element: native.currentTarget } })` from `@cocoar/vue-ui` to anchor a popover. The library deliberately does NOT ship a built-in popover (consumers want different shape: title-only tooltip vs full action menu vs edit-in-place panel) and does NOT apply hover delay (wrap with `setTimeout(..., 200)` if needed). Companion playground demo at `/calendar-popover` wires the pattern end-to-end.
* **`@cocoar/vue-calendar` — `'timeline'` view (Gantt-lite)**: one-row-per-logical-event horizontal time-axis layout for project-plan rendering. Date-axis and day-grid cells use `box-sizing: border-box` so the 1px right border doesn't add to the cell's flex width — bars (absolutely positioned at `left = days × pixelsPerDay`) stay aligned with their date columns indefinitely (without the fix, bars drifted left by 1px per day, accumulating to 21px after three weeks). Default bar render is a coloured rectangle without inline text — the row label on the left is the title source-of-truth; bars are pure timeline geometry. Consumers wanting inline bar text use the `#bar` slot. **Row virtualization built in** — labels and bars only render for rows in the viewport + 8-row buffer; a 1000-task project plan costs ~30-40 DOM rows regardless of total count. Uniform `rowHeight` makes the visible-range math `O(1)` (no per-row measurement); slot renderers only fire for visible rows. Companion playground page at `/calendar-timeline-perf` benches the workload at 100 / 500 / 1 000 / 2 500 tasks. **Recurring series collapse to one row** with N bars (one per occurrence in the window) instead of N separate rows — a weekly standup with 26 occurrences renders as ONE "Standup ×26" row, not 26 stacked "Standup" entries. Grouping key is `meta.__recurrence.seriesId` for recurring events, `event.id` for standalone — automatic, consumer code unchanged. New `<CoarTimelineView>` component, `useTimelineView()` composable, and the previously-reserved `'timeline'` value in `CalendarView` is now live. Left pane lists event labels (`meta.title ?? event.id`); right pane renders each event as a bar positioned by `[start, end)` against the visible window. **Excel-style frozen-pane layout** — date axis sticks at top during vertical scroll, label column sticks at left during horizontal scroll, top-left corner sticks at both. Single scroll container with pure CSS `position: sticky` + CSS Grid; no JavaScript scroll-sync. **Click-and-drag pan mode** — drag anywhere on non-interactive area to scroll both axes at once (`cursor: grab` / `grabbing` affordance, pointer-capture so pan continues when cursor leaves the element, `touch-action: none` for matching tablet behavior). Bar clicks bypass the pan handler via interactive-element detection. Configurable density via four setters: `timelineRangeDays(n)` (default 60 days — also the prev/next step), `timelinePixelsPerDay(p)` (default 56 — sized so a localized "DD. Mon" label fits on one line), `timelineRowHeight(h)` (default 32), `timelineLabelWidth(w)` (default 200). Pure layout math at `layoutTimeline(events, options)` exported from the package root for custom implementations and tests; one row per event sorted by start asc + id-asc tie-break, bars clamped to `[windowStart, windowEnd)` with `clippedStart` / `clippedEnd` flags. Cross-zone timed events project into the display zone for visual layout (a meeting at 23:00 Tokyo viewed in Vienna lands on the correct visual day). Three slots (`label`, `bar`, `dateHeader`) override the defaults with the full row geometry available. Scope-bounded — task hierarchy, dependencies, critical-path computation, milestones, and resource lanes are out of scope here; those land in a future `@cocoar/vue-gantt` package that builds on the same primitive. New i18n key `coar.calendar.view.timeline` (default label "Timeline"). Added to the default `availableViews` so the shell's view-switcher exposes it. Dedicated docs page at `/components/calendar/timeline-view`.
* **`@cocoar/vue-calendar` — `'workWeek'` view**: working-days subset of the week view. New `<CoarWorkWeekView>` component, `useWorkWeekView()` composable, and the `'workWeek'` value joins `CalendarView` after `'week'`. Configure the working-day set via `builder.workDays(MaybeRefOrGetter<readonly DayOfWeek[]>)` — default Mon–Fri (`[1, 2, 3, 4, 5]` using the 0 = Sun … 6 = Sat convention), overridable for 6-day operations (Mon–Sat), 4-day weeks (Mon–Thu), or Middle-East Sun–Thu work weeks. The visible-range `ViewWindow` stays the full Mon–Sun span (so `eventsLoader` / `seriesLoader` see weekend events the same way they do for the week view); only the rendered columns differ. Navigation steps by 7 days (the workday filter is purely a render concern, not a navigation one — stepping by 5 would leave the cursor on a weekend on alternate clicks). Added to the default `availableViews` list so the shell's view-switcher gets a "Work week" button automatically (consumers hide it by setting their own `availableViews`). New i18n key `coar.calendar.view.workWeek` (default label "Work week"). Pure helper `workWeekDates(date, firstDayOfWeek, workDays)` exposed from `core/index.ts` for consumer-side use. Dedicated docs page at `/components/calendar/work-week-view` documents the working-day conventions, navigation semantics, and the window-vs-render-set distinction (loaders see weekends, columns don't render them); matches the per-view doc-page pattern established by Day / Week / Month / Agenda.
* **`@cocoar/vue-calendar` — recurring events end-to-end (Phase 4 of the C1–C8 architecture)**: the C8 typed-throwing-stub `expandSeries` that shipped with the package in 1.16.0 is now a working engine. Two new builder setters mirror the non-recurring event pipeline: `builder.series(MaybeRefOrGetter<RecurringSeries<TMeta>[]>)` binds a reactive in-memory series source (mutating the array re-expands), and `builder.seriesLoader((window: ViewWindow) => RecurringSeries[] | Promise<RecurringSeries[]>)` binds a calendar-managed per-window async loader (cached by `${view}|${timezone}|${start}|${end}` like `eventsLoader`). Both compose with `events()` / `eventsLoader()` — `api.getVisibleEvents()` returns the merged set. `series()` and `seriesLoader()` are mutually exclusive (calling one clears the other), independent of the events pair. Expansion happens lazily per visible window, never speculatively — a series with `FREQ=DAILY` from year 2000 doesn't pay 25 years of expansion to render today's calendar.
* **`@cocoar/vue-calendar/recurrence` — public subpath**: standalone `expandSeries(series, window, dstPolicy, engine?)` function for non-builder use (server-side pre-expansion, custom views, deterministic tests). Async — engines are async by contract so worker-backed implementations fit the same shape. Lives at a subpath so apps that don't use recurrence don't pull the engine into their main bundle (the subpath chunk is ~7 KB; the bundled `rrule-temporal` adapter ~4 KB; both lazy-loaded on first call). Re-exports `RecurringSeries`, `RecurrenceExpansionWindow`, `RecurrencePattern` types and the `getRecurrenceMeta(event)` provenance accessor.
* **`@cocoar/vue-calendar/recurrence-rrule-temporal` — bundled engine adapter**: pure-JS, Temporal-native, wraps `rrule-temporal` (~1.5K LOC) for the canonical RFC-5545 RRULE feature set. No WASM, no worker, SSR-clean. Construction is cheap; dynamic-imported by the lazy default in `recurrence/`. Apps with extreme volume or specialized needs (alternative parsers, backend-delegated expansion) implement the `RecurrenceEngine` interface in consumer code and register via `builder.recurrenceEngine(custom)` — no library change required.
* **`@cocoar/vue-calendar` — `builder.recurrenceEngine(engineOrFactory)`**: override the bundled engine per builder. Accepts a `RecurrenceEngine` instance or a `() => RecurrenceEngine` factory (the factory form is the SSR escape — engines are constructed only on first client-side use). Intentionally NOT C7-reactive (mid-session swap has no sensible semantics — in-flight requests, worker lifecycle, cache coherency). Replacing the engine clears the resolved-engine cache and the series cache so the next visible-range read re-expands through the new engine.
* **`@cocoar/vue-calendar` — `RecurringSeries<TMeta>` public type**: Temporal-typed `dtstart` (`ZonedDateTime` for timed, `PlainDate` for all-day), RFC-5545 `rrule` string, optional `duration` (`{ minutes?, hours? }` for timed; `{ days? }` for all-day — D2 day-count semantics, no `Period`), optional `rdate` / `exdate` arrays of the matching Temporal type. ISO strings, native `Date`, floating `Temporal.PlainDateTime` rejected at the boundary; mixed `ZonedDateTime` / `PlainDate` in `rdate`/`exdate` against the series' `dtstart` shape throws with the series id named.
* **`@cocoar/vue-calendar` — `SeriesLoader<TMeta>` type**: mirrors `EventsLoader`. Re-exported from the package root for ergonomic single-import.
* **`@cocoar/vue-calendar` — per-occurrence provenance**: every expanded `CalendarEvent` carries `meta.__recurrence: { seriesId, recurrenceId, source: 'rrule' | 'rdate' }`, read via the new public `getRecurrenceMeta(event)` accessor exported from `@cocoar/vue-calendar/recurrence`. Returns `null` for non-recurring events. `recurrenceId` matches RFC-5545 `RECURRENCE-ID` semantics — the original wallclock slot — so future single-instance edits (override or cancel one occurrence) are addressable without changing the `CalendarEvent` shape. The `__` prefix marks the key as library-managed; consumer code reads it through the accessor, not directly.
* **`@cocoar/vue-calendar` — `DstPolicy` enforced uniformly across every recurring occurrence**: the same `'compatible' | 'reject' | 'earlier' | 'later'` union the drag pipeline uses (C4). After the engine returns instants, every timed rule-generated occurrence is re-resolved via `Temporal.PlainDateTime.toZonedDateTime` with the configured disambiguation, using the series' source zone — engine-swap invariance is structural, not advisory. Observable output depends only on `(intended wallclock, source zone, dstPolicy)`, never on which engine ran underneath. `'reject'` throws `DstResolutionError` on the first gap/overlap with the series id and offending wallclock in the message. All-day series and RDATE-originated occurrences pass through (no DST involvement, no library-imposed override of consumer intent). The `detectDstSituation` primitive moved from private to `core/index.ts` export so the drag pipeline and the recurrence pipeline share one source of truth.

### Fixed

* **`@cocoar/vue-data-grid` — popup cell editors survive nested-overlay interaction (zone-select inside date-picker panel)**: clicking a body-teleported overlay inside an already-open editor overlay (e.g. the timezone-`CoarSelect` inside the `<CoarZonedDateTimePicker>` panel, which itself lives in an AG Grid cell editor) closed the outer panel mid-interaction. Root cause: `focusout` events fired on the editor root with `relatedTarget` pointing to the nested overlay element, bubbled up through the cell DOM, and triggered AG Grid's `stopEditingWhenCellsLoseFocus` commit → editor unmounted → both overlays destroyed. The existing `mousedown` capture-phase guard (`preventDefault` for `.coar-overlay-host` targets) was insufficient because some element types still emit a focus shift despite the prevented default. New shared composable `usePopupEditorFocusGuard(rootRef)` installs a second guard: a `focusout` listener on the editor root that calls `stopPropagation` when the `relatedTarget` is inside `.coar-overlay-host`. AG Grid never sees the cell-focus-loss for focus shifts into body-teleported overlay panels. Applied to all six popup-style cell editors: `CoarSelectCellEditor`, `CoarMultiSelectCellEditor`, `CoarTagSelectCellEditor`, `CoarPlainDateCellEditor`, `CoarPlainDateTimeCellEditor`, `CoarZonedDateTimeCellEditor`. The text + number editors don't use the guard — their inputs are in-cell, no body teleport.
* **`@cocoar/vue-data-grid` — date-column renderers refactored as thin wrappers around `@cocoar/vue-ui` viewer components**: the three renderers (`CoarPlainDateCellRenderer`, `CoarPlainDateTimeCellRenderer`, `CoarZonedDateTimeCellRenderer`) previously did all formatting inline using `toLocaleString` + `instanceof Temporal.X` checks against their own polyfill copy. Two symptoms surfaced from real-world use: (1) **editing a `zonedDateTime` cell wouldn't update the renderer's display** — the picker (in `@cocoar/vue-ui`) constructed `Temporal.ZonedDateTime` instances against its own polyfill copy, the renderer's `instanceof Temporal.ZonedDateTime` from its own copy rejected them, and the renderer fell through to empty string. (2) **Locale changes only partially propagated** — `toLocaleString` reacts to the BCP-47 language tag, but the pickers (and the rest of the date-time family) format via a locale-resolved date-format pattern from `useDatePickerBase`, so consumer locale switches that updated the format pattern bypassed the renderer's BCP-47-only formatter. Both bugs fixed at the source: renderers now embed the matching `<CoarPlainDateView>` / `<CoarPlainDateTimeView>` / `<CoarZonedDateTimeView>`, which use cross-realm-safe `Symbol.toStringTag` checks and the same `useDatePickerBase` reactive resolution as the pickers. Cell editors got the same toStringTag fix for their initial-value type-check (same potential cross-polyfill failure mode on edit-mode entry). New renderer-only `displayTimeZone` config on `col.zonedDateTime()` (`.displayTimeZone('Europe/Vienna')`) projects every row into a single zone for cross-zone coordination views.
* **`@cocoar/vue-ui` — overlay-preset export gap closed**: `popoverPreset`, `datepickerPreset`, `subFlyoutPreset`, `contextMenuPreset`, and `sidebarFlyoutPreset` were declared in `components/overlay/overlay-presets.ts` and re-exported by the internal `components/overlay/index.ts`, but missing from the public package barrel — only 7 of the 12 presets were reachable. Consumer code calling `import { popoverPreset } from '@cocoar/vue-ui'` crashed with `SyntaxError: The requested module does not provide an export named 'popoverPreset'`. Caught when wiring the calendar popover demo. Five exports added to the public barrel; existing preset exports unchanged.
* **`@cocoar/vue-data-grid` — select cell editors focus the trigger on edit-mode entry**: `CoarSelectCellEditor`, `CoarMultiSelectCellEditor`, and `CoarTagSelectCellEditor` previously only `click()`-ed the trigger in `afterGuiAttached` to auto-open the dropdown — focus stayed on the AG Grid cell wrapper. The trigger's `@keydown` handler (Arrow Up / Arrow Down navigation, Enter commit) therefore never fired; arrow keys bubbled to the document and **scrolled the page** instead of moving through the option list. All three editors now call `trigger.focus()` after the click. `tabindex="0"` on the trigger (already present) makes the focus call valid. For `.searchable()`, `CoarSelect.onTriggerClick` schedules a `nextTick` focus on the inline `<input>` — that input's own `@keydown` delegates to the same handler, so search-mode keyboard navigation continues to work.
* **`@cocoar/vue-calendar` — views read the merged event source** (was: only `state.events`): `<CoarMonthView>`, `<CoarTimeGrid>`, `<CoarAgendaView>` previously read `state.events ? toValue(state.events) : []` directly, bypassing the loader cache (silent for `eventsLoader`-mode consumers) and — once Phase 4 landed — the series cache (recurring events counted in `getVisibleEvents()` but never rendered). All three views now read via `props.builder.api.getVisibleEvents()`. Caught during browser hand-test via chrome-devtools on the `/calendar-recurrence` playground page: stats panel said 22 events visible, only 1 (the one-off) rendered as a pill.
* **`@cocoar/vue-calendar` — recurring occurrences no longer collapse to one pill in the month view**: `layoutMonthGrid` dedupes events by `event.id` — multiple expanded occurrences sharing the series id collapsed to a single rendered pill (12 of 13 weekly standups silently dropped). Each occurrence now carries a unique synthetic `${seriesId}__${recurrenceId}` id; series identity moved to `getRecurrenceMeta(event).seriesId`. Public contract reflects the unique-id shape; tests assert no duplicates in expansion output.

### Internal

* **`@cocoar/vue-calendar` — adapter-pattern topology with one bundled engine**: the `RecurrenceEngine` interface lives at `src/recurrence/types.ts` with structured wire types (`EngineRequest` / `EngineResponse` use plain numeric components + per-endpoint `tzid`, no string round-trips). The bundled adapter at `src/recurrence-rrule-temporal/` is the only place that imports `rrule-temporal`. ESLint `no-restricted-imports` rule enforces the topology: `rrule-temporal` outside `recurrence-rrule-temporal/**` is a lint error. The decision to ship one engine (not the planned rrule-rust + rrule-temporal pair) follows from the engine-baseline divergence found during cross-engine bake-off: rrule-rust's DST and per-RDATE-zone semantics differed from rrule-temporal's in ways that couldn't be hidden behind the post-processing normalizer without losing information. Apps that need rrule-rust performance plug their own adapter via `builder.recurrenceEngine(...)`.
* **`@cocoar/vue-calendar` — race-safe series expansion**: `_inFlightSeriesKeys: Set<string>` keyed by `windowKey` blocks duplicate dispatches when `[SET_VISIBLE_RANGE]` and the post-flush series watcher both trigger expansion for the same window in close succession. Generation counter (`_seriesGeneration`) discards stale results on cache invalidation (`refresh()`, engine swap, dstPolicy change, source replacement). The initial-set watcher guard (skip when `state.series` transitions from `null` to a value, since `[SET_VISIBLE_RANGE]` is the canonical trigger for that case) prevents a self-DoS where setting series before setVisibleRange would leak in-flight chains.
* **`@cocoar/vue-calendar` — `expandSeries` lazy-imported by the builder**: dynamic `import('../recurrence/index')` in `_runSeriesExpansion` keeps the recurrence chunk out of the main bundle for apps that never use series. `dist/index.js` stays at ~133 KB (was 128 KB before Phase 4 — +5 KB for the new builder methods, no engine code).
* **`@cocoar/vue-calendar` — 32 new unit tests across 4 files**: `recurrence-public.test.ts` (expansion correctness for timed + all-day, source-zone preservation, EXDATE / RDATE behavior, provenance), `dst-resolve.test.ts` (all four `DstPolicy` values against spring-forward + fall-back in `Europe/Vienna`, RDATE pass-through, all-day pass-through, cross-zone Tokyo-in-Vienna), `recurrence-engine-setter.test.ts` (builder API + factory form), `series-pipeline.test.ts` (reactive series source, seriesLoader caching, mutual exclusivity, composition with `events()`, recurrence-engine swap invalidation, dstPolicy change invalidation, `refresh()` / `refreshRange()`, loading flag accounting). Total calendar suite: 634 unit tests across 44 files (was 602 baseline).

### Docs

* **`docs(calendar)` — new "Recurring events" section** in `apps/docs/components/calendar/coar-calendar.md`: covers the `RecurringSeries` shape and Temporal-only contract, the two source modes (`series()` reactive and `seriesLoader()` cached), `getRecurrenceMeta()` provenance access, the standalone `expandSeries(series, window, dstPolicy, engine?)` entry, the `RecurrenceEngine` interface for custom engines (with SSR factory form), and the `Quartz.NET 3.18.0` interop note — since Quartz now ships native RFC-5545 RRULE triggers (`WithRecurrenceSchedule`), the same `rrule` string + `dtstart` + IANA zone round-trips between Cocoar's frontend display and a Quartz backend job scheduler without a translation layer. Companion live demo `demos/CalendarRecurrence.vue` (DST-policy switcher, reactive add-series button, provenance click-inspect).
* **`playground(calendar)` — new `/calendar-recurrence` demo page**: same shape as the docs demo but with a larger surface area (multiple visible weeks, all-day yearly holiday, dynamic series mutation, "Jump to DST day" navigation shortcut). Used for chrome-devtools regression testing; landed both browser-only bugs in this release.
* **`docs(calendar)` — API reference table extended**: `series`, `seriesLoader`, `recurrenceEngine` setters added with full type signatures and mutual-exclusivity notes.
* **`docs(calendar)` — live popover + timeline demos mirrored from playground into VitePress**: the playground app (`apps/playground/`) isn't deployed publicly, so the popover-anchoring and timeline interaction patterns were invisible to consumers reading the docs. New `<preview>`-embedded demos in `apps/docs/components/calendar/coar-calendar.md` ("Popovers and tooltips" section, `demos/CalendarPopover.vue`) and `apps/docs/components/calendar/timeline-view.md` ("Live example" section, `demos/CalendarTimeline.vue`).
* **`docs(data-grid)` — new "Multi-Select & Tag-Select Columns" page** at `/components/data-grid/multi-select`: documents `col.multiSelect()` and `col.tagSelect()` side-by-side (when-to-use comparison, edit-mode flow, rendering modes, row-aware options, separate API tables, layered-overrides escape-hatch). Single live demo shows both variants in one grid (checkbox-list multi-select with chips display + tag-style trigger with allow-create). Sidebar entry under Data Grid.
* **`docs(data-grid)` — new "Date Columns" page** at `/components/data-grid/date-columns`: documents `col.plainDate()`, `col.plainDateTime()`, `col.zonedDateTime()` with a Temporal-only contract callout, edit-mode flow, per-shortcut API tables, row-aware markers example, and three live demos (PlainDate task scheduling with weekend highlights, PlainDateTime reminders, ZonedDateTime cross-zone meetings with `timezoneFilter`).
* **`docs(ui)` — new "Date Views" page** at `/components/date-views`: documents `CoarPlainDateView`, `CoarPlainDateTimeView`, `CoarZonedDateTimeView` — the read-only display siblings of the picker family. Single page covers all three with a head-to-head feature table, live demos (basic display, locale switching, 12h/24h, cross-zone projection, placeholder for null), and the cross-realm `Symbol.toStringTag` safety note.
* **`docs(ui)` — new "OTP Input" page** at `/components/otp-input`: documents `CoarOtpInput` with five live demos (Basic Usage, Length, Type & Mask, Custom filtering with `transform`/`accept`, Validation, Sizes), behavior table covering every keyboard interaction (auto-advance, Backspace-jump-back, Delete clear, paste-spread), full API table, accessibility notes, and the mobile SMS-autofill chip behavior. Sidebar entry under Form Controls.

***

## 1.18.0

### Added

* **`@cocoar/vue-data-grid` — cell-editing primitives**: three new chainable methods on the column / grid builders form the foundation for in-cell editing. `column.editable(value | row-predicate)` gates whether a cell enters edit-mode (boolean or `(row) => boolean`; predicate auto-handles missing row data). `column.cellEditorConfig(component, config)` mirrors the existing `cellRendererConfig` for swapping in custom editors — the config is wrapped under `cellEditorParams.config` so every editor gets the same access shape. `gridBuilder.onCellValueChanged(handler)` provides a single grid-level commit hook fired for both editor commits and renderer-driven mutations (e.g. checkbox toggles via `node.setDataValue`). New "Editing" doc page documents the AG-Grid edit-mode flow + Tab-through-edit-mode navigation.
* **`@cocoar/vue-data-grid` — `col.text(field, t => …)`**: text column whose editor is `<CoarTextInput>`, fitted into the cell with form chrome stripped (no nested border, no extra focus ring — the AG Grid cell is the edit-mode frame). Replace-on-type via AG Grid's `eventKey` (printable key seeds the input), value pre-selected via `afterGuiAttached` so typing replaces. Configurator: `placeholder`, `maxLength`, `size`, `prefix`, `suffix`. Renderer uses AG Grid's default text rendering.
* **`@cocoar/vue-data-grid` — `col.number(field, n => …)`** *(overload)*: existing `col.number(field, config?)` keeps the legacy config-object form (renderer only). New callback form bundles `CoarNumberCellEditor` automatically — Maskito-driven locale-aware parsing means `1.234,56` in `de-AT` and `1,234.56` in `en-US` both yield the same numeric value. Configurator: `decimals` (renderer + editor), `min`/`max`/`step`/`stepperButtons`/`placeholder`/`size` (editor). Replace-on-type seeded via the digit / `.` / `,` / `-` key that started the edit.
* **`@cocoar/vue-data-grid` — `col.select(field, s => …)`**: select column with two cooperating components — `CoarSelectCellRenderer` (label-lookup; displays the label of the option matching the cell value) and `CoarSelectCellEditor` (auto-opens the dropdown via `afterGuiAttached`). Selection auto-commits — picking an option *is* the edit, no separate Tab/Enter needed. Configurator: `options` (static array OR `(row) => CoarSelectOption<T>[]` for row-aware menus), `clearable`, `searchable`, `placeholder`, `searchPlaceholder`, `size`. Dropdown teleports to `<body>` via Coar's overlay-host so it can extend past cell / grid boundaries without clipping.
* **`@cocoar/vue-data-grid` — `col.checkbox(field, c => …)`**: checkbox column with a read-only `<CoarCheckbox>` renderer + interactive `<CoarCheckboxCellEditor>`. Renderer is always read-only by design (matches text/number/select); interactivity comes from edit-mode entered via double-click / Enter / F2, exactly like other editable column types. Inside edit-mode Space toggles, Tab commits and moves to the next editable cell (AG Grid's standard keyboard navigation), Escape cancels. Configurator: `label` (static or per-row), `indeterminate` (per-row tri-state), `size`. Vertical-centering CSS shim corrects CoarCheckbox's form-context layout (`align-items: flex-start`, fixed `min-height`, `margin-top` hack) inside the grid cell.
* **Configurator-callback pattern**: new `CheckboxColumnConfigurator`, `TextColumnConfigurator`, `NumberColumnConfigurator`, `SelectColumnConfigurator` classes provide the `s => s.options(...).clearable()`-style fluent API. Layered overrides via `.cellRenderer(MyOwn)` / `.cellEditorConfig(MyEditor, …)` continue to work as escape hatches (last-write-wins on the chain).

### Fixed

* **`@cocoar/vue-ui` — `CoarNumberInput` clear button no longer surfaces on focus when `clearable={false}`**: the `.coar-number-input-clear--hidden` modifier (`opacity: 0`) was outranked by the focused / hover overrides (`opacity: 1`, same selector specificity but defined later in the cascade), so the X appeared even on focused inputs explicitly opted out of clearing. Fix scopes the focused / hover rules with `:not(.coar-number-input-clear--hidden)` so they explicitly skip hidden buttons. Keeps the opacity-based hiding strategy (rather than switching to `v-if` like `CoarTextInput`) because the clear button sits to the LEFT of the input — a `display: none` hide would shift the input on appear/disappear, hurting layout stability.
* **`@cocoar/vue-data-grid` — `CoarSelectCellEditor` commits the selected option** (was: silently dropped under real user clicks): mousedown on a body-teleported dropdown option shifted focus away from the editor → AG Grid's `stopEditingWhenCellsLoseFocus` fired *before* CoarSelect's option-click handler could update the model → `getValue()` returned the OLD value. Caught by the user during hand-testing; the original verification used synthetic `HTMLElement.click()` which bypasses focus/blur flow. Fix is a capture-phase document `mousedown` listener installed while the editor is mounted: when the click target sits inside a Coar `overlay-host`, `preventDefault()` blocks the focus shift. The click event still fires, CoarSelect updates the model, the watch picks it up and triggers `stopEditing` — `getValue()` then returns the new value. Outside-clicks (everywhere else) still cause focus loss → AG Grid commits/cancels normally.

### Internal

* **`@cocoar/vue-data-grid` — new `configurators/` directory**: holds the per-column-type fluent configurator classes. Re-exported from the package root for consumers writing custom helpers.
* **Docs reorganisation**: dedicated "Data Grid" sidebar section replaces the single-item "Data" section. Currently five sub-pages (Overview, Editing, Text Column, Number Column, Select Column, Checkbox Column) with one live demo per page.
* **`docs(calendar)`**: marked the Calendar package as **Preview** in the sidebar to set expectations until v1.0 of `@cocoar/vue-calendar`.
* **`ci`**: docs-only changes now skip the full CI matrix (`paths-ignore` filter on `apps/docs/**` and `**/*.md`). Saves ~3 min per docs-only PR; full CI still runs whenever non-docs files are touched.

***

## 1.17.0

### Added

* **`@cocoar/vue-calendar` — DnD composables generic over `TMeta`**: `useCalendarDnd`, `useMonthDnd`, `useTimeGridDnd` now accept a `TMeta extends Record<string, unknown>` type parameter, propagating event meta types through `CalendarEvent<TMeta>`, `EventDropPayload<TMeta>`, snapshot types, and the keyboard-drag state. Default stays `Record<string, unknown>` so existing JS consumers are unaffected; TypeScript consumers writing custom DnD wiring can now keep their meta types end-to-end through the drop pipeline.
* **`@cocoar/vue-calendar` — `useViewWindow` accepts a `{ view }` override**: standalone sub-views (`<CoarMonthView />`, `<CoarDayView />`, `<CoarWeekView />`, `<CoarAgendaView />`) pass their intended view via the new optional 2nd argument, which sets `builder.state.view` so the same builder composed via `useDayView()` / `useMonthView()` etc. (which never set `view`) renders correctly when handed to a sub-view component. Replaces the parallel `onMounted` hacks DayView and WeekView each carried; MonthView and AgendaView never had them and were silently broken in standalone mode (window computed for the wrong view, loader fetched the wrong range).
* **`@cocoar/vue-calendar` — `canDrop` validators receive `displayZone`**: the `CanDropTarget` shape advertised `displayZone: string` but both DnD composables silently dropped the field before invoking the validator. Now passed through. Article-5 / C5 conformance — consumers writing rules like "no drops in business hours of the user's local zone" can read `target.displayZone` directly instead of closing over `state.timezone` separately.

### Changed

* **`@cocoar/vue-calendar` — `EventLayoutCtx.kind` discriminator values aligned with templates**: type values are now `'positioned' | 'allDayBar' | 'monthPill' | 'monthBar'` (matching the layout-class names used by the views and the values templates have always emitted). The previous `'timed' | 'allDay' | 'monthBar' | 'monthPill'` was a documentation lie: templates never sent `'timed'` or `'allDay'`, so consumer event-renderers branching on those values were dead code at runtime. Renderers using the universal `state.eventRenderer` keep working unchanged; renderers that explicitly switched on `ctx.layout.kind` should now match the corrected values.

### Fixed

* **`@cocoar/vue-fragment-parser` — `vue-router` peer range widened to `^4.5.0 || ^5.0.0`**: consumer apps already on `vue-router@5.x` got a peer-dependency warning because the published range was still capped at `^4.5.0`. The package only uses `useRoute` / `useRouter` — both stable across vue-router 4 and 5 — so widening is safe. The monorepo itself runs on 5.x (playground + fragment-parser dev dep), the peer range was just lagging behind.
* **`@cocoar/vue-markdown-editor` — external `v-model` updates no longer dropped during Milkdown init**: a parent that initialised `v-model` synchronously to a placeholder and then assigned the real value asynchronously inside `onMounted` (typical store-load pattern) saw the editor stay locked on the placeholder. The watcher in `EditorImpl` bailed silently when `getInstance()` returned `null` during Milkdown's async init window, and the missed update was never replayed — so saving without further edits round-tripped the placeholder back to the API and overwrote the real document body. The watcher now buffers the latest external value while the editor isn't ready and a second watcher on Milkdown's `loading` ref flushes it via `replaceAll` once init completes. Found while migrating `cocoar-policy` knowledge docs to event sourcing.
* **`@cocoar/vue-calendar` — `<CoarCalendar>` honors `prefers-reduced-motion`**: `smoothScrollBodyTo` was reading `window.value.matchMedia(...)` where the local `window` const shadowed the global by binding to a `ViewWindow` computed (a `{ start, end, timezone }` POJO). The match-media check therefore always returned `undefined` and the animated scroll always fired, ignoring the user's reduced-motion preference. Reaches the browser's `window` via `globalThis` now; users with `prefers-reduced-motion: reduce` get instant scroll on `scrollToTime` / `scrollToDate`.
* **`@cocoar/vue-calendar` — phantom-event stubs use real Temporal objects**: the placeholder events passed to `phantom` and `invalid` variants of `<CoarTimeGridEvent>` / `<CoarTimeGridAllDayBar>` / `<CoarMonthPill>` / `<CoarMonthBar>` were typed as `CalendarEvent` but constructed with string `start` (`'1970-01-01'` / `'1970-01-01T00:00:00Z'`) — direct C1 violation in internal code. Now constructed with `Temporal.PlainDate.from(...)` / `Temporal.ZonedDateTime.from(...)`. Stubs are still "plumbing only, never observed at runtime" (the variants don't invoke their slots), so the change is purely a type-correctness fix.

### Internal

* **Workspace-wide TypeScript hygiene + CI hardening**: the `vite-plugin-dts` build emits TS errors to stdout but does not fail the build, so 144 silent type errors had accumulated across `@cocoar/vue-script-editor` (8), `@cocoar/vue-ui` (10), and `@cocoar/vue-calendar` (126) — all green CI runs were green-with-errors-in-the-log. Every error is fixed (Monaco 0.55 namespace migration, `useSlots()` typing in renderless wrappers, generic propagation through TMeta, `EventLayoutCtx.kind` alignment, `Props` interface inlining to bypass vue-tsc's TS4025 on script-setup-generic SFCs, slot signatures marked optional so `v-if="$slots.foo"` no longer trips TS2774, etc.). New `pnpm typecheck` script per package wired through a turbo task (`vue-tsc --noEmit`) and added as a CI step between Lint and Test in both `ci-develop` and `ci-pr-validation` workflows. Future TS regressions now fail the build instead of being logged and ignored.
* **`@cocoar/vue-markdown-editor` — first component-level test**: `CoarMarkdownEditor.test.ts` mounts the editor with `@vue/test-utils` + happy-dom + `CoarOverlayPlugin` and pins both the v-model race (external update before Milkdown ready) and the post-init external-update path. Test 1 fails deterministically without the v-model buffer fix.
* **`monaco-editor` deduplicated to `^0.55.1` across the workspace**: `apps/docs` and `apps/playground` were still on `^0.54.0` while `@cocoar/vue-script-editor`'s peer-range demanded `^0.55.1` — for `0.x` versions a caret pins the minor, so the two ranges did not overlap and the lockfile carried both `monaco-editor@0.54.0` and `@0.55.1` side-by-side. Apps bumped to `^0.55.1`; the duplicate is gone.
* **Lint cleanup — zero workspace-wide warnings**: `vue/one-component-per-file` and `vue/require-prop-types` disabled in `*.test.{ts,js}` / `**/__tests__/**` (multi-component test harnesses are the standard Vue test pattern, not a smell); `vue/attribute-hyphenation` disabled at the Vue-file level (Vue's `aria-*` / `data-*` fall-through-attribute treatment skips kebab→camel coercion, so binding `:ariaRowIndex` on a child must use camelCase to actually wire the prop). Two file-level disables for the deliberate multi-component layouts: `default-renderers.ts` (the entire markdown default registry in one place per the file-header comment) and `CoarMarkdownEditor.vue` (inner `EditorImpl` + `Toolbar` share the `MilkdownProvider` context).

***

## 1.16.0

### Added

* **`@cocoar/vue-calendar` — new package**: Vue 3 calendar component built around `Temporal`. Day / Week / Month / Agenda views, a top-level `<CoarCalendar>` shell with prev / today / next navigation and a segmented-control view switcher, and standalone composables (`useDayView()` / `useWeekView()` / `useMonthView()` / `useAgendaView()`) for embedding a single view without the shell. Public surface is `Temporal.ZonedDateTime` (timed events) or `Temporal.PlainDate` (all-day events) — never strings, `Date`, `PlainDateTime`, or `Instant`. Eight architecture invariants (C1–C8) drawn from the ["Time in Software, Done Right" article series](https://dev.to/bwi/why-a-date-is-not-a-point-in-time-ad8) are enforced structurally: Temporal-only public surface (C1), single drop pipeline through `applyMoveToEvent` (C2), per-endpoint source zones preserved across every drag mode including cross-zone events (C3), explicit `DstPolicy` argument on every wall-time → instant conversion (C4), display zone vs source zone surfaced separately on drop payloads (C5), independent `locale` / `dateStyle` / `timeStyle` / `hour12` decisions merged through a single `buildFormatOptions` (C6), reactivity-by-reads not setup-capture (C7), and `RecurringSeries` as a first-class type with a typed throwing-stub `expandSeries` until the recurrence engine lands (C8). Flat `CalendarBuilder` — every setter (`timeRange`, `slotDuration`, `maxEventsPerCell`, `agendaLengthDays`, …) lives on the same builder. Universal `eventRenderer((ctx) => ...)` with `ctx.layout.kind` discriminator (`'positioned' | 'allDayBar' | 'monthPill' | 'monthBar'`) covers every variant. Drag-and-drop with mouse / touch / keyboard, cluster-aware lane sizing, virtualized agenda surface, multi-day bars across month rows, "+ N more" overflow expansion via per-cell kebab menu. Wire helpers `parseScheduledTime` / `formatScheduledTime` / `parsePlainDate` mirror the Article-8 `{ local, timeZoneId }` shape that .NET / NodaTime backends and PostgreSQL `local_start text + time_zone_id text` storage natively speak.
* **`@cocoar/vue-calendar` — `Temporal` re-export**: `import { Temporal } from '@cocoar/vue-calendar'` for consumers that don't want a direct `@js-temporal/polyfill` dependency.
* **`@cocoar/vue-calendar` — default event renderers surface C3 / C5 zone semantics**: a shared decoration layer (`<CoarEventDecorations>`, internal) inserts a small globe icon + tooltip + sr-only announcement on the default time-grid event card, month pill, month multi-day bar, and agenda event row. Two semantics, mutually exclusive: (1) `start.timeZoneId === 'UTC'` → globe + tooltip "Global event — same instant worldwide" (Article 5 — UTC-anchored events render the same instant for everyone, regardless of display zone); (2) `start.timeZoneId !== displayZone` (and is not UTC) → globe + accent dot + tooltip "Source zone: \<iana>" (Article 3 — render the user's clock without hiding the source). Suppressed on multi-day bars when `clippedStart` so only the visible head decorates. The same logic ships as a public helper `getEventZoneHints(event, displayZone) → { isUtcAnchored, sourceZone }` for custom renderers. Three i18n keys: `coar.calendar.event.utcLabel`, `coar.calendar.event.utcGlobalHint`, `coar.calendar.event.crossZoneHint`.
* **`<CoarDisplayZoneSwitcher>` — drop-in display-zone selector** exported from `@cocoar/vue-calendar`: wraps `<CoarSelect>` with a curated 7-zone default list (Vienna / Berlin / London / New York / Los Angeles / Tokyo / UTC), automatically prepends the browser-detected zone if it isn't in the list, accepts an `:options` override for full IANA / domain-specific lists. `v-model` is the IANA id string the consumer passes into `builder.timezone(tz)`. Two i18n keys: `coar.calendar.zoneSwitcher.label`, `coar.calendar.zoneSwitcher.browserSuffix`.

### Internal

* **`@cocoar/vue-calendar` — 602 unit tests across 43 files**: timezone conformance suite at `src/core/__tests__/timezone/` pins every C1–C8 invariant; component tests cover the shell + each sub-view + the drop pipeline integration; `useViewWindow` tests pin the C5 single-writer invariant; zone-hint helper covered by 7 dedicated tests.

### Docs

* **New "Calendar" sidebar group** under Components — overview page, `<CoarCalendar>` (composer) reference with full builder API, per-view pages (Day, Week, Month, Agenda) with standalone-usage examples, and a manual performance bench in the playground (`/calendar-perf-bench`) for eyeballing wheel-scroll smoothness, view-switch latency, and drag-frame stability against documented Tier-A targets.

***

## 1.15.0

### Added

* **`@cocoar/vue-markdown-editor` — text color**: new `textColor` tool exposes a palette + native color-input picker in the floating toolbar and the sidebar (fixed mode). Selection-based `text_color` ProseMirror mark, full markdown round-trip as `<span style="color: …">…</span>`. Picker uses the shared overlay service (`menuPreset`): anchor-relative positioning, viewport flip, scroll-reposition, outside-click + escape dismissal — no bespoke layout. Active color shows as a thin indicator bar under the trigger icon. New exports: `COAR_TEXT_COLOR_PALETTE` (8 swatches), `textColor` plugin bundle, `textColorMark` and `textColorRemark` for advanced setups.
* **`@cocoar/vue-markdown-core` — color-span sanitizer + parser fold**: shared `sanitizeColor` / `sanitizeColorStyle` / `parseColorSpanOpen` / `isColorSpanClose` / `serializeColorSpanOpen` / `serializeColorSpanClose` helpers. Whitelist accepts hex (`#rgb`/`#rrggbb`/+alpha), `rgb()` / `rgba()` / `hsl()` / `hsla()` (legacy + modern syntax), and a small set of named CSS colors (`red`, `blue`, …, `transparent`, `currentcolor`); rejects `var(--token)`, `url(…)`, `expression(…)`, multi-declaration styles, foreign attributes, control characters. New `colorSpan` `MarkdownNodeType` with `attrs.color`; the parser folds matched `<span>` open/close pairs in inline children into a single node (depth-aware nesting). Serializer flat-maps colorSpan back to `html` opener + children + closer.
* **`@cocoar/vue-markdown` — `colorSpan` renderer**: `DefaultColorSpan` registered in `defaultMarkdownRenderers`. Re-validates the color attribute via `sanitizeColor` at render time (defence in depth) — invalid values strip the inline style and fall through to plain text. New `colorSpanColor` helper exported from `helpers.ts`.

### Changed

* **`@cocoar/vue-markdown` shared stylesheet — editor↔viewer parity**: rendering rules now cover both the viewer's class-based DOM (`<div class="coar-markdown-list-item">…`) *and* the editor's PM-managed bare-element DOM (`<li>` no class). Block-spacing and typography selectors extended with `.coar-markdown .ProseMirror > :where(…)` so the editor's `.ProseMirror`-wrapped blocks pick up the same vertical rhythm. New bare-element fallbacks for `:where(blockquote, ul, ol, li, code:not(pre code), a)`. User-agent margin on `<p>` inside `<li>` / `<td>` / `<th>` zeroed (PM wraps cell/list content in `<p>` — without the reset every editor row was one line taller than its viewer pendant). Table zebra rule rewritten with `:nth-child(<n> of :not([data-is-header]))` so Milkdown's `tr[data-is-header]` (which lives inside `<tbody>`, unlike the viewer's `<thead>`) is excluded from the alternation index — the first data row reads as "row 1" in both panes. Bare `<blockquote>` margin reset to `0` so the browser's user-agent `40px` margin doesn't indent editor blockquotes deeper than viewer blockquotes.
* **`@cocoar/vue-markdown` task-list rendering**: `DefaultListItem` no longer emits a native `<input type="checkbox">` + wrapping `<div class="coar-markdown-list-item-content">`. It now mirrors the editor's PM-emitted attributes — `data-item-type="task"` + `data-checked="true|false"` on the `<li>` directly — and the visual checkbox is a `::before` pseudo-element on the `<li>` (cocoar-style filled square + check). Strikethrough on completed items moved to the shared stylesheet so editor and viewer render identically.
* **`@cocoar/vue-markdown` shared stylesheet — `--coar-markdown-heading-block-start`** lowered from `var(--coar-spacing-xxxl, 4rem)` to `var(--coar-spacing-xl, 2rem)`. The previous 4rem/64px gap before every heading read as "blank lines" in both viewer and editor; 2rem/32px still marks sections clearly without pushing four lines of whitespace into view.
* **`@cocoar/vue-markdown-editor` styles trimmed**: deleted local typography overrides (`h1` / `h2` / `h3` / `p` / `ul` / `ol` / `li` / `blockquote` / `code` / `table` / `th` / `td` / `a` / `strong`) plus the task-list checkbox CSS — all now live in `@cocoar/vue-markdown/styles` and apply uniformly. Editor `<strong>` was rendering at `font-weight: 600` while the viewer used the browser's `bolder` (700); both now read 700.

### Fixed

* **`@cocoar/vue-markdown-editor` — color picker no longer flashes at (0,0)**: the previous manual `Teleport` + `getBoundingClientRect` positioning rendered the popover at the initial `{ left: '0px', top: '0px' }` style ref before reactivity flushed the measured anchor coordinates. Replaced with `useOverlay().open({ spec: menuPreset, anchor: { kind: 'element', element: trigger } })` so the overlay service measures + positions atomically before paint.
* **`@cocoar/vue-markdown-editor` — color picker now closes on outside click**: the previous custom `mousedown` handler exempted only `.coar-md-color-picker`, so clicks anywhere on the page outside that selector closed the picker via the floating-toolbar hide path — but the picker had no escape-key dismissal, no scroll-close, and was inconsistent with other Cocoar overlays. Now driven by `menuPreset` which gives `outsideClick: true` + `escapeKey: true` + `scroll.strategy: 'close'` for free.

***

## 1.14.0

### Added

* **`@cocoar/vue-ui` — `CoarSidebar` supports all four edges**: new `side` prop accepts `'left' | 'right' | 'top' | 'bottom'` (default `'left'`); `top` / `bottom` switch the layout to a horizontal toolbar (items in a row, scrolls horizontally) while `left` / `right` keep the classic vertical column. Tooltip placement, flyout direction, the active-state indicator border edge, and the collapsed dimension (width vs. height) all derive from `side` automatically. `CoarSidebarItem` and `CoarSidebarGroup` inject the side via a new `SIDEBAR_SIDE_KEY` to adapt their own internals — child group flyouts open right (left side), left (right), down (top), or up (bottom). Items inside a horizontal sidebar are `flex-shrink: 0` so the row genuinely overflows rather than squishing, which is what triggers the OverlayScrollbars horizontal scrollbar. The deprecated `position` prop still works for backwards compatibility but maps internally to `side`.
* **`@cocoar/vue-ui` — collapsed sidebar dimensions auto-scale with `size`**: previous `4rem` default for `--coar-sidebar-collapsed-width` was generous for nav rails but too wide for icon-only formatting toolbars. Per-size fallbacks now resolve to `2.25rem` (s), `2.75rem` (m), `3.25rem` (l) for both the collapsed width (vertical) and the new collapsed height (horizontal). Setting `--coar-sidebar-collapsed-width` / `--coar-sidebar-collapsed-height` explicitly still overrides the fallback — the variable becomes defined in the cascade and `var()` returns the inherited value instead of the per-size literal, so app-level / wrapper-level overrides keep working unchanged (the `@cocoar/vue-markdown-editor` wrapper relied on this and continues to win at `2.25rem`).
* **`@cocoar/vue-ui` — expanded-group children render as visually nested**: items inside a `<CoarSidebarGroup>`'s expand panel get tighter padding, smaller font, a `scale(0.85)` icon with reduced opacity, and an explicit opacity fade on the label. Rule applies in **all four** orientation × collapsed combinations, so children read as nested whether the sidebar is vertical or horizontal, collapsed or expanded — important for horizontal expand mode where children sit inline with their parents on the same row and indent alone is no longer a cue. Hover background stays at full strength because the opacity is on the icon and label individually, not the item.
* **`@cocoar/vue-markdown-editor` — `toolbarPosition` extended to all four edges**: type widened from `'left' | 'right'` to `'left' | 'right' | 'top' | 'bottom'`, so the formatting toolbar can sit above or below the editor as a horizontal strip. Editor root's `flex-direction` flips between `row` (left/right) and `column` (top/bottom), and the toolbar/editor border edge follows the chosen side. The wrap now sets both `--coar-sidebar-collapsed-width` and `--coar-sidebar-collapsed-height` so the toolbar stays at `2.25rem` in either orientation. Existing `'left'` / `'right'` consumers are unaffected — same default, same visuals.

### Fixed

* **`@cocoar/vue-ui` — `vTooltip` directive value type now allows `false` / `null` / `undefined`**: every collapsed-aware component (`CoarSidebarItem`, `CoarSidebarGroup`, `CoarMultiSelect`, …) returned a falsy value from its `tooltipConfig` computed to mean "do not render a tooltip" — which the directive's runtime already handled correctly but its TypeScript signature did not (`string | TooltipOptions` only). `vue-tsc` flagged the call sites, even though the runtime was fine. Type widened to `string | TooltipOptions | false | null | undefined` and `getOptions` now returns `{ content: '', disabled: true }` for falsy bindings instead of casting `false` to `TooltipOptions` (was a latent runtime smell — primitive-boolean property reads happened to return `undefined`, but `state.opts` was lying about its type).

***

## 1.13.1

### Fixed

* **`@cocoar/vue-data-grid` — wrapper column inner renderer config was shadowed by the wrapper config**: factory-created column renderers (`col.tag()`, `col.tree()`, `col.date()`, `col.number()`, `col.currency()`, `col.icon()`) all read their own configuration via `params.colDef.cellRendererParams.config`, but AG Grid hands the *outer* (wrapped) colDef to the renderer — so wrapped inner renderers were receiving the wrapper's config instead of their own, dropping `variantMap`, `showChildCount`, `decimals`, `currencyCode`, `includeTime`, and every other inner-renderer option. Tree columns stayed mostly functional (expand/collapse + indentation come from `grid.context.coarTree`, not `cellRendererParams`), but `showChildCount` was lost; tag, date, number, currency, and icon columns fell back to their defaults entirely when wrapped. `WrapperCellRenderer` now rebuilds the inner's `params.colDef.cellRendererParams` so nested factory columns see exactly what they would see unwrapped. New probe test replicates the factory renderers' read path to prevent regression.

***

## 1.13.0

### Added

* **`@cocoar/vue-markdown-editor` — new package**: WYSIWYG Markdown editor for Vue 3 based on Milkdown (Kit approach), styled with the Cocoar Design System. Markdown-first round-trip (lossless) — `v-model` is the persistence format, no JSON intermediate. Shares the same remark stack as `@cocoar/vue-markdown-core` and `<CoarMarkdown>`. Three toolbar modes: `floating` (default, appears on text selection, teleported to `<body>`), `fixed` (`CoarSidebar` collapsed strip with flyout submenus), and `both`. `toolbarPosition` (`'left'` | `'right'`) controls sidebar side. Reactive active-state highlights on every button (Bold lights up when the cursor is in `**bold**`, Bullet List when inside a list, etc.) — driven by Milkdown's `selectionUpdated` plugin hook with a `queueMicrotask` defer so the listener reads the freshly-committed `view.state` instead of the pre-apply snapshot.
* **`@cocoar/vue-markdown-editor` — 18 toolbar tools, configurable via `tools` whitelist**: `bold`, `italic`, `strikethrough`, `inlineCode`, `headings` (flyout H1–H6 + paragraph), `bulletList`, `orderedList`, `taskList`, `indent`, `outdent`, `blockquote`, `horizontalRule`, `codeBlock`, `table`, `tableOps`, `clearFormatting`, `undo`, `redo`. `tools` undefined → all 18 render; `tools` set → only the listed in canonical order, with auto-cleanup of orphan dividers. Constant `COAR_MARKDOWN_EDITOR_ALL_TOOLS` exported for consumer-side filtering. Migration mapping from richtext editors that exposed `font-size` / `align` / `font` / `color` / `underline` is documented in the docs page (those have no Markdown representation and are intentionally not exposed; `font-size` maps to `headings` for typographic hierarchy).
* **`@cocoar/vue-markdown-editor` — list & task semantics**: list-toggle button cycles "in same → lift / in other → switch / outside → wrap" (clicking Bullet inside a Bullet item un-lists it; clicking Ordered inside a Bullet swaps the type). Task list items render with proper checkboxes via CSS `::before` (filled accent + strikethrough text when checked, hollow box when open); clicking the checkbox toggles the `checked` attribute round-tripping through Markdown as `- [x]` / `- [ ]`. Indent (`sinkListItem`) is disabled outside any list; Outdent (`liftListItem`) is disabled at the top list level — leaving the list is the list-button's job.
* **`@cocoar/vue-markdown-editor` — sidebar context-aware table operations**: when the cursor lands inside a table cell, the sidebar grows by 5 items (Insert Row Above/Below, Insert Column Left/Right, Delete Cell). Lets users edit table structure in `fixed` toolbar mode without falling back to the floating toolbar.
* **`@cocoar/vue-markdown-editor` — `CoarFormField` integration**: `disabled`, `error`, `id`, `aria-describedby` propagate automatically when the editor is wrapped in `<CoarFormField>` (same `FORM_FIELD_INJECTION_KEY` injection used by `CoarTextInput` / `CoarScriptEditor`). Direct props win over the injected context. Editor wrapper carries `aria-invalid`, `aria-disabled`, `aria-readonly`, `aria-required`, `data-name` so screen readers and form tooling see the right state.
* **`@cocoar/vue-markdown-editor` — code-block view/edit toggle (NodeView)**: code blocks render as `CoarCodeBlock` (Prism-highlighted, language label, same look as the viewer) when the cursor sits elsewhere; switching to plain editable mode + `CoarSelect` for the language when the cursor moves inside. Toggle is driven by a custom ProseMirror NodeView + a small companion plugin that watches `selectionUpdated` so `TextSelection` (the natural cursor placement) flips the mode — PM's own `selectNode`/`deselectNode` only fire for `NodeSelection`. Header dimensions / background / border-radius mirror `CoarCodeBlock` so the toggle is visually flush.
* **`@cocoar/vue-markdown-editor` — `./styles` subpath export** (mirrors `@cocoar/vue-data-grid`): consumers `@import "@cocoar/vue-markdown-editor/styles"` to pull the bundled CSS. Same fix applied to **`@cocoar/vue-script-editor`**, which was missing the subpath export since 1.9.0.
* **`@cocoar/vue-markdown` — shared rendering registry**: the viewer (`<CoarMarkdown>`) and the editor (`@cocoar/vue-markdown-editor`) consume the **same** Vue component map for every node type, so a code block, table, blockquote, etc. looks identical whether the user is reading or writing. The registry is exposed as `MarkdownViewerRenderers` (a typed map of `MarkdownNodeType → Component`), with the Cocoar defaults available as `defaultMarkdownRenderers`. Apps override slots per-instance via `<CoarMarkdown :renderers="{...}" />` or app-wide via `app.provide(MARKDOWN_RENDERERS_KEY, ...)`. Resolution order: prop > inject > default. The recursive `<RenderNode>` dispatcher and the `renderMarkdownNodes` helper are exported for consumers writing custom complex renderers.
* **`@cocoar/vue-markdown` — shared block stylesheet** at `@cocoar/vue-markdown/styles`. Headings, paragraphs, lists, blockquotes, tables, inline code, links, etc. all live in one CSS file that both the viewer and the editor pull in via the `coar-markdown` outer class. The editor adds a deeper-specificity layer for compactness (smaller heading sizes for an editing surface) on top of the shared baseline.
* **Markdown table styling alignment**: Markdown tables in the editor inherit the same shared stylesheet rules as the viewer's tables — zebra rows, header surface, padding, border. The viewer's `DefaultTable` no longer wraps in `<CoarTable>` (was relying on `:deep()` scoped CSS that wouldn't reach the editor's contenteditable); both viewer and editor now emit a plain `<table class="coar-markdown-table">` that the shared stylesheet drives. Visual parity without a NodeView wrapper for tables.
* **`@cocoar/vue-data-grid` — Wrapper Column**: new `.wrap(inner)` factory on the column builder that decorates any column with left and/or right cell-body slots, ideal for status indicators, action icons, and inline badges without writing a custom `cellRenderer`. The inner builder stays a real `CoarGridColumnBuilder` — sort, filter, quickFilter, `valueFormatter`, `valueGetter`, comparator, `editable`, and even existing `cellRenderer`s (tag, date, number, currency, tree) all continue to work untouched; only the `cellRenderer` gets wrapped. Example: `col.wrap(col.field('name').header('Name').flex(1).sortable().option('editable', true)).left({ icon: (r) => r.starred ? 'star' : null, onClick: toggleStar }).right({ component: UnreadBadge, params: (r) => ({ count: r.unread }), show: (r) => r.unread > 0 })`. Slots accept three shapes: **icon shorthand** (`{ icon, source, size, color, tooltip, onClick, show }`), **component** (any Vue component; automatically receives `row: TData` as a prop, with optional `params(row)` to add/override props), and **text** (`{ text, tooltip }`). Each accessor (icon/color/text/tooltip) can be a static value or a per-row function. Pass an **array** to stack multiple items in the same slot — each with its own `show()` gate, `onClick`, and tooltip — e.g. two right-side icons for `isCritical` + `awaitingFeedback` plus a third component slot that renders a tag or icon based on a `priority` field. Slot `onClick` handlers call `event.stopPropagation()` automatically so they don't trigger row-click / cell-click. Edit mode is untouched: AG Grid swaps the renderer for the editor on double-click (wrapper disappears during editing, reappears on Escape/commit). Wrapper slots are intentionally not in the tab order — they're visual hints, Tab navigates cell-to-cell. Ships with `WrapperCellRenderer`, `CoarGridWrapperColumnBuilder`, and fully typed `WrapperSlotConfig` / `WrapperIconSlotConfig` / `WrapperComponentSlotConfig` / `WrapperTextSlotConfig` / `WrapperCellRendererConfig` exports.
* **17 new Lucide icons in the core registry**: `bold`, `italic`, `strikethrough`, `heading`, `pilcrow`, `list-ordered`, `text-quote`, `square-code`, `table`, `table-cells-merge`, `table-cells-split`, `columns`, `rows`, `between-horizontal-start`, `between-horizontal-end`, `between-vertical-start`, `between-vertical-end`, `indent-increase`, `indent-decrease`, `eraser`. Available to all consumers via the standard icon name lookup.

### Changed

* **`@cocoar/vue-markdown` package surface**: the viewer is no longer a thin wrapper. The package now hosts the registry, the default renderers, the recursive dispatcher, the helpers, and the shared CSS — all next to `<CoarMarkdown>`. Consumer-facing imports are unchanged (`CoarMarkdown` is still the top-level export); new exports (`defaultMarkdownRenderers`, `MARKDOWN_RENDERERS_KEY`, `MarkdownViewerRenderers`, `RenderNode`, …) sit alongside it. Internal-only `MarkdownBlockNode.vue` / `MarkdownInlineNode.vue` / `helpers.ts` were removed — their logic moved into the per-type default renderers in `default-renderers.ts`.

### Fixed

* **Playground — markdown editor body font fell back to bare `sans-serif`**: `App.vue` referenced a non-existent design token `var(--coar-font-family, sans-serif)` (the actual token is `--coar-body-base-family`). The fallback chain bottomed out at the bare keyword for everything inside the playground's `.app` wrapper, including the markdown editor's body text. Updated to use the correct token; Poppins now inherits cleanly through the editor area.

### Docs

* **New "Markdown Editor" component page** marked as **Preview**, with three live demos (basic `v-model`, sidebar mode, in-form integration with `CoarFormField`), Architecture Notes section explaining why Milkdown over TipTap/Crepe and why `@milkdown/components/table-block` is intentionally not used (CellSelection is ProseMirror-internal and doesn't fire `selectionchange`), Restricting the Toolbar section with the migration mapping table, "Code blocks — view / edit toggle" section documenting the toggle UX and supported languages, full Props/Events reference, and a TODO list for the deferred work (link-insert UI, image upload, placeholder, custom table edge-handles).
* **`/components/markdown` — Custom renderers section** with worked examples (per-instance override, app-wide `provide`, registry contract, why the registry matters cross-package).

### Internal

* **`@cocoar/vue-markdown-editor` test coverage**: 12 Vitest unit tests for the pure helpers (`isToolEnabled`, `decideListToggleAction`) extracted to `toolbar-helpers.ts`, plus 23 Playwright E2E tests against the playground covering mounting, floating-toolbar visibility, mark commands via sidebar, full-set / minimal / no-tables tool whitelisting, indent + outdent (including the disabled-state gating), bullet-list wrap on plain text, clear-formatting (mark stripping + heading→paragraph), task-checkbox toggle in both directions, readonly mode, and the code-block view/edit toggle including language-selector → markdown-source round-trip.
* **`@cocoar/vue-markdown` test coverage**: 9 viewer unit tests (7 existing for rendering + 2 new for the `renderers` prop override path).
* **Dependabot — 10 of 13 alerts cleared**. `pnpm update` + `pnpm dedupe` lifted `happy-dom`, `flatted`, `picomatch`, `minimatch`, and `brace-expansion` to patched versions. The remaining 3 alerts are `vite 5` issues that come in transitively via `vitepress 1.6.4` (which pins `vite 5` as a peer). An attempt to globally override `vite` to `^8` was reverted because vitepress 1 is incompatible with rolldown-vite (the engine vite 8 ships with). The remaining alerts are dev-tooling only — no production runtime impact for consumers — and will close out when vitepress 2 (currently alpha-only) ships stable.

***

## 1.12.2

### Fixed

* **`@cocoar/vue-script-editor` — `extraLibs` were invisible to the TypeScript worker, silently resolving to `any` on hover**: `useMonacoEditor` configured the shared TS/JS compiler options with `noResolve: true` (added in 1.11.0 alongside the `lib: ['es2024']` fix). With `noResolve` set, the TS language worker skips pulling `addExtraLib`-registered `.d.ts` files into compilation — so an identifier declared exclusively in an extraLib was accepted syntactically but resolved to `any`. `noResolve` is now removed from the shared options; library targeting stays constrained to `['es2024']`, so the original reason for the flag (keep the default DOM / WebWorker / WSH libs out of IntelliSense) is unaffected. Consumers using `extraLibs` immediately see correct hover types and IntelliSense with no code change.
* **`@cocoar/vue-script-editor` — `script-mode` swallowed legitimate `Cannot find name` errors**: `SCRIPT_MODE_DIAGNOSTIC_CODES` added TS code `2304` to Monaco's `diagnosticCodesToIgnore` alongside the structural wrapper artefacts (`1375` top-level await, `2695` unused comma-LHS, `1108` top-level return, `7027` unreachable code, `1208` isolatedModules). `2304` is a genuine semantic error — not a wrapper artefact — and suppressing it masked the `noResolve` bug above: undeclared identifiers rendered as `any` with no squiggle. Code `2304` is now removed from the suppression set; the other five codes remain. **Possible visible change for consumers:** code that previously compiled silently under `script-mode` with unresolved identifiers now shows red squiggles. Register the missing names via `extraLibs`, or extend `diagnosticCodesToIgnore` directly on `monaco.languages.typescript.*Defaults` to restore the old behavior.

***

## 1.12.1

### Fixed

* **`CoarDataGrid` — flex columns collapsed to ~36px when tree-mode grid started with empty `rowData`**: the flex-recalc workaround that re-applies `columnDefs` after first data arrives (introduced in 1.5.3 for the flat-data codepath) was missing from `#setTreeRowDataOnGrid`, and the one-shot flag `#flexApplied` was consumed prematurely in both codepaths by the initial empty set that Vue's `{ immediate: true }` watcher fires on mount. Net effect: a `treeDataRef(ref([]))` grid mounted with zero rows, and by the time real rows arrived the workaround had already fired (against an empty grid) and no further re-flex ever happened. Flex columns kept whatever width AG Grid had assigned at mount — in narrow-at-mount scenarios that bottoms out around 36px, clipping cell content and breaking Playwright `toBeVisible()` checks. The workaround is now applied in the tree codepath too, and the flag only flips once `result.length > 0`, so the one-shot is reserved for the actual 0→N transition. Consumers with `treeData(...)` + `flex(1)` columns + initially-empty row refs get the correct flex layout without a manual resize.

***

## 1.12.0

### Fixed

* **Overlay widgets inside modals — stacking + tree-aware dismissal**: `CoarSubFlyout`, `CoarContextMenu`, the Select family (`CoarSelect` / `CoarMultiSelect` / `CoarTagSelect`), and `CoarSidebarGroup` (in `mode="flyout"`) used to mount their panels via their own `<Teleport to="body">` with a hardcoded `z-index: var(--coar-z-overlay)` = 1000. Inside a dialog rendered through the overlay-service at `z-index: 1002`, those panels landed behind the dialog and clicks on them were treated as outside-the-dialog → the dialog closed. Each widget now opens its panel via `overlay.open({ parent: useOverlayParent() })`, so the service stacks it above the ancestor dialog (`1000 + instance.id * 2`) and treats clicks inside it as clicks inside the parent tree. All public APIs are unchanged — the migration is purely internal.
* **Overlay-service parent linking was a no-op when called from a descendant overlay**: `useOverlayParent()` returned an `OverlayInstance`, but `OverlayOpenOptions.parent` was typed `OverlayRef`; the service looked up `__instanceId` only, silently failing for every instance-shaped value. The widened lookup now resolves either shape. Before the fix, `instance.parent` stayed `null` and the tree-aware click-outside never closed child branches — clicks outside a popover in a dialog used to leave the popover lingering until a hover-out timer fired. After the fix, one outside click cascades through the entire branch.
* **Select dropdown `transform: translate3d()` containing-block trap**: the dropdowns used to position themselves with a transform, which CSS-spec-wise creates a containing block for every `position: fixed` descendant. Floating widgets rendered from inside a dropdown landed at the dropdown's offset instead of the viewport. The service's overlay host uses plain `top`/`left`, so the trap is no longer reachable through a select.
* **Select dropdown scroll behavior**: `selectPreset.scroll.strategy` changed from `'close'` to `'reposition'` — dropdowns now follow the trigger on scroll instead of closing abruptly, matching the pre-migration (`useSelectDropdown`) behavior.

### Changed

* **Overlay service — parent type widened**: `OverlayOpenOptions.parent` now accepts `OverlayRef | OverlayInstance`. Existing callers that passed an `OverlayRef` continue to work; descendants using `useOverlayParent()` no longer have to cast.
* **`selectPreset.a11y` dropped** (was `{ role: 'listbox' }`): the select panels already render an inner `role="listbox"` element that carries the referenced id and `aria-multiselectable`. Declaring the role on the outlet host duplicated the semantic element and misplaced the aria attribute.

### Internal

* **6 new panel components**: `CoarPopoverPanel` (pre-existing), `CoarTooltipPanel` (pre-existing), `CoarSubFlyoutPanel`, `CoarContextMenuPanel`, `CoarSelectDropdownPanel`, `CoarMultiSelectDropdownPanel`, `CoarTagSelectDropdownPanel`, `CoarSidebarFlyoutPanel`. Each is the lean visual shell the overlay-service mounts; the owning component keeps its state machine (hover/click/keyboard/cascade) and forwards reactive state via props or closures.
* **3 new overlay presets**: `subFlyoutPreset`, `contextMenuPreset`, `sidebarFlyoutPreset`.
* **Legacy helper removed**: `packages/ui/src/components/select/useSelectDropdown.ts` (dead after all three select variants migrated).
* **Playground diagnostic view extended**: `/overlay-stacking` now covers 8 scenarios (popover, tooltip, submenu, context menu, nested popover→tooltip, nested popover→popover, all three selects, sidebar flyout with nested groups). Used for chrome-devtools-driven verification of every migration.

***

## 1.11.0

### Added

* **`CoarListbox` — new component**: single-column list primitive with multi-select highlight (Ctrl/Shift/Keyboard), search (three layers of control — `searchFields`, `searchBy`, `filterWith`), grouping with sticky or non-sticky headings, custom item rendering via `itemComponents` (kind → component) or `#item` / `#item-<kind>` slots, per-item imperative API for inline actions, `displayOnly` mode for static rosters with ARIA `role="list"`, and both native keyboard nav (arrows, `Home`/`End`, `Space`, `Ctrl+A`, `Enter`) and `item-click` / `item-dblclick` / `item-activate` events. Fully generic over `T` (`CoarListboxOption<T>`); ships its own Kitchen-Sink-grade prop/event/slot surface.
* **`CoarDualListbox` — new component**: composes two `CoarListbox` instances + move buttons for the classic "available ↔ selected" pattern. Manages `v-model: T[]` (right column), forwards search / sort / grouping / custom-render / drag-drop / virtual props to both sides, exposes `moveRight` / `moveLeft` / `moveAllRight` / `moveAllLeft` / `clearHighlight` via template ref, and bubbles `item-remove` / `item-action` from custom renderers with a `side: 'available' \| 'selected'` annotation. Drag-drop between the two columns via one prop (`drag-drop`).
* **`CoarListboxItemApi<T>` — imperative handle for custom item renderers**: every component registered via `itemComponents` and every `#item` / `#item-<kind>` slot now receives an `api` prop with `highlight()` / `unhighlight()` / `toggleHighlight()` / `activate()` / `remove()` / `action(name, payload?)`. `remove` and `action` bubble up as `item-remove` and `item-action` events on the listbox — consumers update their own `options` array. Powers inline trash buttons, ×-to-remove in the selected column of a DualListbox, per-row context-menu actions.
* **Drag & drop — first-class feature** on `CoarListbox` and `CoarDualListbox`. Three layers of permission: `drag-group` (coarse name matching), `drag-id` + `drag-accept` (directional whitelists for asymmetric flows like box1→box2→box3 with no back-edges), and `can-drag` / `can-drop` callbacks for per-item source control and runtime target validation. Selection-aware: dragging a highlighted item carries the whole highlighted set. Visual feedback via `isDragOver` with `dropEffect='none'` cursor when a drop is refused. `items-add` / `items-remove` events fire synchronously on drop so there's no "duplicated items" frame between source and target re-renders. `CoarDualListbox` auto-wires an internal drag group when `drag-drop` is set.
* **Virtual scrolling** on `CoarListbox` and `CoarDualListbox` (`virtual` prop): renders only the rows inside the viewport + overscan. Supports mixed per-row heights (items vs. group headings), search/filter, custom components, drag-drop, and keyboard nav (`scrollToIndex` follows the focus). Tested with a 10,000-entry IPrincipal directory demo.
* **`useVirtualList` — new exported composable** (`@cocoar/vue-ui`): the framework-agnostic primitive behind virtual mode. Fixed or per-index `itemSize`, configurable `overscan`, `scrollToIndex(i, align?)`. Cumulative-offset table (O(log n) per scroll), reactive on count / size changes, `ResizeObserver` fallback for environments without one. Usable standalone in any Vue component that scrolls — not tied to the listbox.
* **`useDragDrop` — new exported composable** (`@cocoar/vue-ui`): the generic primitive behind listbox drag-drop. Same group / accept / canDrop / canDrag semantics, same cross-surface registry that carries live object identity through DataTransfer. Ships a module-level registry (`registerDrag` / `getDrag` / `getActiveDrag` / `deleteDrag` + `DRAG_MIME` constant) for advanced integrations. Reach for it when building any other Vue component that needs the same drag semantics — no need to reimplement.
* **Boolean-prop convention**: `displayOnly`, `hideSearch`, `hideMoveAll`, `hideCounts`, `sortSelectedBySource` — all new boolean props default `false`, matching the library-wide "features are opt-in" rule. Where a feature should feel on-by-default (e.g. search on `CoarDualListbox`), the prop name is inverted so the default can stay `false`.

### Fixed

* **Monaco `lib` configuration for Jint-backed runtimes** (`@cocoar/vue-script-editor`): `useMonacoEditor` now calls `setCompilerOptions({ lib: ['es2024'], target: ES2024, allowNonTsExtensions: true, noResolve: true })` on both TS and JS defaults on first mount. Previously Monaco fell back to its default `lib = ['es5', 'dom', 'webworker.importscripts', 'scripthost']`, autocompleting ~5485 browser / WSH / WebWorker APIs that don't exist in Jint — `fetch`, `document`, `localStorage`, `WScript`, `importScripts`, etc. — luring users into code that crashes at runtime. After the fix IntelliSense only surfaces standard ECMAScript APIs Jint actually runs; host-specific globals are layered back in explicitly via `extraLibs`. The enum value for the script target is resolved with fallback (`ES2024 ?? ES2023 ?? … ?? ES2020`) so the fix works across Monaco versions.

### Docs

* **New component pages**: Listbox, Dual Listbox — each with 5–7 live demos (basic, display-only, grouped, custom item component, directional DnD, virtual 10k, inline remove button, drag-drop columns) plus full API tables for props, events, slots, exposed methods.
* **New Utilities pages**: `useVirtualList` (with a standalone 50k-log-line demo built from plain `<div>`s — no listbox in sight) and `useDragDrop` (with a 3-column custom Kanban board, no listbox). Cross-linked from the component pages so consumers can discover the primitives.
* **Script Editor — "Runtime lib configuration" section**: explains the default Monaco lib set vs. what Jint provides, documents the applied override, and explains how to provide a different lib set for non-Jint scenarios.

### Internal

* **`@cocoar/vue-ui/composables` module**: new home for reusable composables. Currently `useVirtualList`, `useDragDrop`, and the `dragRegistry` primitives; wired into `CoarListbox` internally so there is one source of truth for virtual-scrolling math and DnD semantics across the library.
* **Test coverage**: +79 unit tests for the new surface (CoarListbox: 38, CoarDualListbox: 17, useVirtualList: 13, useDragDrop: 10, CoarScriptEditor: 1 for the Monaco fix). Full UI suite 1142/1142; script-editor 92/92.

***

## 1.9.0

### Added

* **`@cocoar/vue-script-editor` — new package**: Monaco-based code editor for Vue 3 with TypeScript, JavaScript, and JSON support. Peer-deps on `monaco-editor`. `v-model` is the persistence format, `extraLibs` for TypeScript type injection (IntelliSense on domain types), Cocoar light/dark Monaco themes with reactive `auto` detection that tracks `.dark-mode` class on `<html>`/`<body>` (Cocoar convention), `data-theme` attribute, or OS `prefers-color-scheme`. `getEditor()` / `getModel()` escape hatches for Monaco APIs not covered by props.
* **Constrained mode (`// @locked` line protection)**: any line of the source containing `// @locked` is protected against edits, deletion, and line-merging. Users can't touch the marker or its line; everything else is freely editable — including the file top, so TypeScript's Auto-Import quickfix works naturally. Markers stay in `v-model`, so the editor value round-trips through persistence with no extra schema. Powered by `ChangeGuard` (inclusive overlap check + multi-cursor atomic rollback via `editor.trigger('undo')`), `CursorGuard` (snap away from locked interiors), `DiagnosticsFilter` (hides TS error markers that fall on locked lines caused by in-progress bodies), and per-mount auto-feature policy (`formatOnType`, `formatOnPaste`, `linkedEditing` disabled to prevent cross-boundary reformats).
* **Authoring mode (`authoring` prop)**: suspends enforcement so template authors can edit locked lines and markers themselves. Markers render at full size with a warm accent colour to signal enforcement is off. Toggle back to resume enforcement with the current marker state.
* **`@reject` event**: emits `{ reason, range? }` when a guard rolls back an illegal edit — hookable for toast / shake / line-highlight feedback.
* **Pure helpers** (no editor mount required): `scanLockedLines`, `computeProtectedRanges`, `hasLockedMarkers`, `getEditableSegments`, `getSlots`, `getSlot`, `editIsProtected`, `snapOffsetAwayFromLocked`, `countLockedLines`, `isEverySegmentNonEmpty`, `validateSource`. Use for submit-gating, server-side validation, or tests. `SLOT_MARKER_PATTERN` is exported as a regex source string so server-side parsers (e.g. a C# Jint host) can mirror the same matching.
* **Named slots (`@slot:NAME`)**: attribute placed on a `// @locked` line that names the editable segment which follows. `getSlots(source)` returns a `{ slotName: bodyContent }` dictionary, `getSlot(source, name)` returns a single body (or `undefined` when the template does not declare it). Lets a consumer identify per-region fill state without knowing segment positions — ideal for templates where the user may fill in 0..N of several named function bodies and the runtime needs to decide which ones to invoke. Slot markers survive line shifts (e.g. auto-import at file top) because they're anchored to their locked line, not a fixed line number. First-wins on duplicate names; `LockedLine.slotName` exposes the parsed name for custom tooling.
* **Form integration (`CoarFormField`)**: `CoarScriptEditor` now auto-inherits `id`, `error`, `describedBy`, and `disabled` from `CoarFormField` the same way `CoarTextInput` does. New props: `disabled`, `error`, `placeholder`, `required`, `autofocus`, `id`, `name`, `height` (CSS string or number). New events: `focused`, `blurred`. New exposed method: `focus()`.
* **`variant: 'editor' \| 'inline'`**: compact form-field preset that turns off line numbers, gutter, folding, glyph margin, and context menu, and switches to tight padding + word-wrap + hover/focus ring matching `CoarTextInput`. `'editor'` (default) keeps the existing full-chrome IDE look.
* **`lineNumbers: boolean`**: explicit toggle that overrides the variant default (`'editor'` → on, `'inline'` → off). When line numbers are off a small decoration column stays visible so the text is not flush with the border.
* **`scriptMode: boolean`**: suppresses the diagnostic codes Monaco emits for "script body" code — top-level `return`/`await`/`export`, implicit any on injected globals, and unreachable-code warnings. Global side-effect on `typescriptDefaults`/`javascriptDefaults`; documented in the form-integration section of the Script Editor docs.
* **`preamble: string`**: hidden + auto-locked prefix providing per-editor type context (e.g. `"declare const query: TodoQuery;"`). Rendered invisibly above the user script via `setHiddenAreas`, protected from cursor/paste/edit by an internal preamble guard, and stripped from the emitted `modelValue` so it never round-trips through persistence.
* **Bundled `Cascadia Code` font**: `@cocoar/vue-ui/fonts` now also loads Cascadia Code (weights 400, 600, 700). Both `CoarCodeBlock` and `CoarScriptEditor` now prefer it over the previous Consolas/Monaco stack, with the same stack as fallback. Monaco gets `fontLigatures: true` so `!=`, `=>`, `===`, and friends render as combined glyphs. Consumers who import `@cocoar/vue-ui/fonts` get the upgrade for free; consumers who do not (or who ship their own font stylesheet) fall back to Consolas/Monaco as before.

### Docs

* **New "Script Editor" component page**: full guide with 6 live demos (basic TS, extraLibs, JSON, read-only + minimap, constrained mode with authoring toggle, and a form-integration demo with `CoarFormField` + preamble + extraLibs). Covers worker setup for SPA and SSR (VitePress / Nuxt / Astro), `theme="auto"` signal priority, JSON-schema configuration via Monaco escape hatch, security notes on untrusted `extraLibs.content`, and the full API reference with events and exposed methods.
* **Form-integration section** in the Script Editor page: explains `preamble` vs `extraLibs` with a decision table, documents the diagnostic codes `scriptMode` suppresses, and walks through the `variant="inline"` form-field look.

### Fixed

* **Overlay system — fixed-positioned descendants inside modals**: the `.coar-overlay-host` positioned itself via `transform: translate3d(...)`, which CSS spec-wise creates a containing block for every `position: fixed` descendant. Any component inside a dialog/menu/popover that relies on `position: fixed` for its own popups (Monaco's IntelliSense, floating tooltips, portal-style widgets) rendered at the overlay's offset instead of the viewport. Switched overlay positioning to plain `top`/`left` — stacking isolation is still provided by `position: fixed` + numeric `z-index`, and fixed descendants now resolve against the viewport as expected. Transparent to all existing Cocoar components.

### Internal

* **Playwright E2E infrastructure**: first end-to-end test suite in the repo, wired into `apps/playground`. Covers constrained-mode guards (`executeEdits` + keyboard flows), undo/redo granularity, paste-across-boundary, multi-cursor mixed-zone edits, authoring toggle, diagnostics filter, language switching, and editor-in-modal IntelliSense positioning. 54 unit tests + 31 E2E tests total for the new package.

***

## 1.8.0

### Added

* **Select sorting** (`sortGroups`, `sortOptions`): Two new props on `CoarSelect`, `CoarMultiSelect`, and `CoarTagSelect` to control the display order of groups and options. Both accept presets (`'asc'`, `'desc'`, `'none'`) or a custom comparator function. `sortOptions` works with and without groups — it sorts all options when ungrouped, or within each group when grouped. Defaults are backwards-compatible: `sortGroups='asc'` (alphabetical, as before), `sortOptions='none'` (input order, as before). New types: `CoarSelectSortGroups`, `CoarSelectSortOptions<T>`.

### Fixed

* **SubFlyout menu close chain**: Clicking a `CoarMenuItem` inside a `CoarSubFlyout` now closes the entire menu hierarchy (submenu + parent context menu). Previously, only the immediate submenu panel closed — the root `CoarContextMenu` stayed open, requiring consumers to manually call `menu.close()` in every handler.

### Docs

* **Select sorting section**: New "Sorting" section on the Select docs page with interactive `SortingDemo` (side-by-side grouped vs. ungrouped). All three playground demos (Select, MultiSelect, TagSelect) now include `sortGroups` and `sortOptions` controls. Props table updated with the new props.

***

## 1.7.0

### Added

* **CoarSelect / CoarMultiSelect — inline search**: When `searchable` is set, the trigger becomes an inline text input while the dropdown is open. Type to filter options in real-time. Space, Home, and End keys work correctly inside the search field.
* **CoarMultiSelect — selection tooltip**: When 2+ values are selected, hovering the trigger shows a tooltip listing all selected labels.
* **Select option grouping**: Options with a `group` property are now rendered under sticky group headers. Groups are sorted alphabetically; ungrouped options appear first. Works in all three variants (CoarSelect, CoarMultiSelect, CoarTagSelect).
* **CoarMenu — `#header` / `#footer` slots**: Fixed header and footer areas that stay in place while the menu content scrolls. Render only when the slot is provided.
* **CoarMenuHeading — `sticky` prop**: Opt-in sticky positioning so section headings stay visible while scrolling through long menus.

### Fixed

* **Tooltip not closing in collapsed sidebar**: Pointer-initiated focus (click/tap) no longer pins tooltips open via the `focus` reason. Only keyboard focus (Tab) keeps tooltips open until focus moves away. This fixes tooltips staying visible in the collapsed sidebar until clicking elsewhere.
* **CoarTagSelect — Space key in search**: Space now types a space character in the tag input instead of triggering option selection.

### Changed

* **Select search UX**: Replaced the dropdown search box with an inline search input in the trigger for CoarSelect and CoarMultiSelect, matching the pattern already used by CoarTagSelect. All three variants now use a consistent search approach.

### Docs

* **Select playground demos**: Interactive playgrounds for CoarSelect, CoarMultiSelect, and CoarTagSelect with toggleable props (searchable, clearable, grouped, disabled, readonly, error, size, appearance).
* **Select API table**: Documented missing props (searchable, clearable, readonly, appearance, compareWith, dropdownPosition).
* **Menu scrollable demo**: Updated with header (filter input), footer ("New project" action), and sticky headings toggle.

***

## 1.6.6

### Changed

* **`resetPersistedState(bucket?)`**: Now accepts an optional bucket parameter to reset only a specific width bucket (defaults to the current bucket). Previously reset all buckets.
* **`resetPersistedStates()`**: New method that resets all persisted column states across all buckets for a grid (the previous `resetPersistedState()` behavior).

***

## 1.6.5

### Added

* **Column state persistence** (`persistColumnState`): New builder method to persist column widths, order, visibility, and sort in IndexedDB. Grid width is rounded to configurable buckets (default: 100px) so different container sizes (monitor switch, sidebar collapse) each keep their own column layout. When no exact bucket exists, the nearest saved state is applied.
* **Live column sync**: Multiple grids sharing the same persistence key synchronize column changes instantly — resize, reorder, or hide a column in one grid and all others update immediately. Useful for comparison views with different filters on the same data structure.
* **`cleanupColumnStates(maxAgeDays)`**: Removes stale column state entries from IndexedDB that haven't been read or written within the specified number of days. Call once at application startup to prevent unbounded growth of persisted data.

### Changed

* **Dependency upgrades**: Vite 7→8, vue 3.5.32, vue-router 4→5, vitest 4.1, lucide-static 0.x→1.x, @vitejs/plugin-vue 6.0.5, eslint 10.2, typescript-eslint 8.58, maskito 5.2, turbo 2.9, overlayscrollbars 2.15, happy-dom 20.8, prettier 3.8.2, vitepress 1.6.4, mermaid 11.14, @js-temporal/polyfill 0.5.1, path-to-regexp 8.4.

***

## 1.6.4

### Changed

* **Form field label styling**: Labels now use `body-caption` tokens (`family`, `size`, `weight`) instead of `body-small-bold` / `component-m-label-font-size` for a more compact, consistent appearance across all form controls.
* **Tab padding**: Reduced tab button padding from `spacing-m / spacing-l` to `spacing-s / spacing-m` for tighter layout.

### Fixed

* **Date picker height mismatch**: `CoarPlainDatePicker`, `CoarPlainDateTimePicker`, and `CoarZonedDateTimePicker` reserved space for the hint/error message even when none was set, making them taller than other form controls (e.g. `CoarTextInput`). The message element is now conditionally rendered via `v-if`, and the fixed `height` / `min-height` + `visibility: hidden` workaround has been removed.

### Removed

* **`CoarLabel` component**: Removed the standalone `CoarLabel` component, its tests, exports, and documentation page. The component was unused by any input control or consumer app — labels are rendered directly by `CoarFormField` and the individual picker components.

***

## 1.6.3

### Added

* **Tag custom colors** (`variantFn`): New `variantFn` option on `TagCellRendererConfig` for dynamic tag styling. The function receives the raw cell value and can return:
  * A `TagVariant` string (`'success'`, `'error'`, …) for predefined variants
  * A CSS color string (`'#dc2626'`) — used as text+border color, background auto-calculated via `color-mix(in oklch)` for consistent light/dark mode appearance
  * A `TagColor` object (`{ bg, border?, text? }`) for full control
  * `undefined` to fall back to `variantMap`

### Fixed

* **Empty tag rendering**: `TagCellRenderer` no longer renders empty tags when a label is `""`, `undefined`, or `null`.

***

## 1.6.2

### Added

* **Locale-aware column renderers**: `date()`, `number()`, and `currency()` column factory methods now use cell renderer components with the localization system (`useL10n()`), updating reactively on locale change. Replaces the previous `valueFormatter`-based approach.
  * `date(field, config?)` — formats via `fmtDate()`, supports `{ includeTime: true }`
  * `number(field, config?)` — formats via `fmtNumber()`, supports `{ decimals: number }`
  * `currency(field, config?)` — formats via `fmtCurrency()`, supports `{ currencyCode: string }`
* **Locale switcher in docs**: VitePress nav bar now includes a `CoarSelect`-based locale switcher (`en-US`, `en-GB`, `de-DE`, `de-AT`, `fr-FR`, `ja-JP`) for live-testing locale-dependent rendering.

### Changed

* **`date()` replaces `localDate()`**: The `date()` factory method now uses the `DateCellRenderer` component (previously only available via `localDate()`). `localDate()` has been removed.
* **`number()` signature**: Changed from `number(field, decimals)` to `number(field, config?)` with `NumberCellRendererConfig`.
* **`currency()` signature**: Changed from `currency(field, currencyCode)` to `currency(field, config?)` with `CurrencyCellRendererConfig`.

### Fixed

* **TagCellRenderer variant matching**: `variantMap` now matches against the raw cell value instead of the formatted value, so `valueFormatter` no longer breaks variant resolution.
* **IconCellRenderer valueFormatter support**: Icon name now uses `valueFormatted` when available, keeping the raw value for sorting/filtering.
* **Currency symbol resolution**: `formatCurrency()` now resolves unknown currency symbols via `Intl.NumberFormat` instead of falling back to the raw currency code (e.g. `€` instead of `EUR`).
* **ja-JP date format**: Added `yyyy/mm/dd` date pattern and `zeroPad` flag to `CoarDateFormatData`. Japanese dates now correctly render as `2022/3/15` instead of `2022-03-15`.
* **Localization plugin init**: `setLanguage()` is now called on plugin install, so locale data is available immediately without requiring a manual language switch.

***

## 1.6.1

### Fixed

* **Data Grid dark mode**: Custom grid header (`CoarGridHeader`) now inherits `--ag-header-foreground-color` so text and sort icons render correctly in dark mode instead of staying black.

***

## 1.6.0

### Added

* **Sidebar navigation components**: New dedicated components for sidebar navigation, replacing the pattern of using `CoarMenu`/`CoarMenuItem` inside `CoarSidebar`:
  * **`CoarSidebarItem`**: Navigation item with `icon`, `label`, `active` state, and automatic tooltip in collapsed mode. No menu cascade/close logic — designed purely for persistent navigation.
  * **`CoarSidebarGroup`**: Expandable/flyout section with two modes:
    * `mode="expand"` (default): Animated inline panel (grid-based 0fr→1fr). Plus/minus icon indicator.
    * `mode="flyout"`: Floating panel positioned next to the sidebar via `Teleport`. Chevron icon indicator. Supports nested flyouts with parent-child cascade (hovering child keeps parent open).
  * **`CoarSidebarHeading`**: Section title that becomes a small spacer when collapsed (visual separation preserved without text).
  * **`CoarSidebarDivider`**: Simple visual separator line.
  * **`CoarSidebarSpacer`**: Vertical spacing component with `height` and `grow` props.
* **Flyout mode** (`mode="flyout"`) on `CoarSidebarGroup`: Opens a floating panel next to the sidebar instead of expanding inline. Flyout panels are teleported to `<body>` and positioned via `computeOverlayCoordinates`. Click-to-open by default, with optional `open-on-hover` prop for hover-triggered opening (200ms delay). Close-on-leave has a 300ms grace period so users can move to the panel without it closing.
* **Icon-only flyout** (`icon-only` prop on `CoarSidebarGroup`): Flyout items show as a vertical column of icons without labels, with tooltips on hover. Useful for compact action palettes. Nested flyout and expand groups inside icon-only flyouts automatically inherit the icon-only display.
* **Open on hover** (`open-on-hover` prop on `CoarSidebarGroup`): Opt-in hover-to-open behavior for flyout groups. Opens after 200ms hover delay, closes after 300ms leave delay. Touch-friendly default remains click-to-open.
* **Nested flyouts**: Flyout groups can be nested inside other flyouts. Parent-child cascade via `provide`/`inject` keeps parent panels open while interacting with children. Click-outside detection checks all flyout panels to prevent premature closing.
* **Expand in flyout**: Expand groups work inside flyout panels, including icon-only flyouts where children render as centered icons without labels or indentation.
* **Sidebar `size` prop**: Controls icon size — `'s'` (16px), `'m'` (20px, default), `'l'` (24px). Propagated to children via injection.
* **Sidebar collapsed UX**: `CoarSidebar` now provides its collapsed state to children via `inject`. Sidebar items automatically show right-aligned tooltips when collapsed. Smooth width transition on collapse/expand. Group triggers show icon badge (plus for expand, chevron for flyout) in collapsed mode.
* **Sidebar scoped slots**: `#header`, `#footer`, and the default slot now receive `{ collapsed }` so parent components can adapt their content (e.g. full logo vs. icon-only).
* **Sidebar CSS tokens**: New design tokens for sidebar items — `--coar-sidebar-item-padding`, `--coar-sidebar-item-hover`, `--coar-sidebar-item-active-color`, `--coar-sidebar-item-active-bg`, `--coar-sidebar-group-indent`, etc.
* **Force expand tree** (Data Grid): New `builder.forceExpanded(ref)` method. When the ref is `true`, all tree parents are expanded and chevron toggle is disabled. When it switches back to `false`, the previous open-state is restored.

### Changed

* **`CoarSidebar` collapsed prop**: Now emits `update:collapsed` for optional `v-model:collapsed` two-way binding. One-way `collapsed` prop still works as before.
* **Sidebar footer padding**: `--coar-sidebar-footer-padding` changed from `var(--coar-spacing-m)` to `0` so footer items stretch to full width like content items.

### Fixed

* **Tooltip empty rectangle**: `vTooltip` directive's `updated` hook now handles falsy values (`false`, `''`). Previously, switching tooltip config from an object to `false` left a visible empty rectangle.
* **Tooltip z-index**: Tooltip z-index increased to `calc(var(--coar-z-overlay,1000) + 1)` so tooltips render above flyout panels.

***

## 1.5.5

### Added

* **Custom data filter**: New `builder.customFilter((data, searchText) => filteredData | null)` method on `CoarGridBuilder`. Filters the **entire data array** before passing it to AG Grid, replacing the per-row quick filter. This enables filter logic that depends on related rows — e.g. keeping all siblings in a tree when any one matches the search. Returning `null` from the callback falls back to the default quick filter for that evaluation, allowing dynamic switching between custom and standard filtering.
* **Pipeline update triggers**: New `builder.updateOn(...sources)` method. Re-runs the data pipeline (filtering, tree flattening) when the given reactive sources change. Works with all pipeline modes (tree, flat+search, flat reactive) — useful when `customFilter` or `quickFilterFn` depends on external state like toggle flags.

***

## 1.5.4

### Fixed

* **Modal/Dialog centering**: Overlays now stay centered when their content grows after initial render (e.g. async data loading). Previously, `modalPreset` and `dialogPreset` skipped installing a `ResizeObserver` because their scroll strategy is `noop` — the overlay kept its initial position even as content changed size, resulting in more space above than below.

***

## 1.5.3

### Added

* **Scrollable Menu**: `CoarMenu` now uses overlay scrollbars (`v-scrollbar`) and scrolls automatically when content exceeds available height
* **`CoarSubFlyout`**: Renamed from `CoarSubmenuItem` for consistency with `CoarSubExpand`. Old name remains as deprecated alias for backwards compatibility.
* **Context Menu flyout demo**: New docs example showing flyout submenus inside context menus (status, priority selectors)

### Fixed

* **Context Menu flyout click**: Clicking a menu item inside a flyout submenu now correctly triggers the click handler. Previously the context menu closed before the handler fired because the teleported flyout panel was treated as "outside" the menu.
* **Cell text overflow**: Removed `display: flex` from `.ag-cell` — flex containers don't clip plain text children with `overflow: hidden`, causing text to bleed into adjacent cells. AG Grid handles vertical centering internally.
* **Scroll position reset**: Grid no longer jumps to top when data updates. Column definitions are now re-applied only once (on first data set) instead of on every update.
* **Toolbar padding**: Toolbar only has padding when `bordered` or `elevated` is set. Without those, only a gap between toolbar and grid is shown.
* **Empty toolbar visibility**: Toolbar is hidden when no slots have content and search is disabled (CSS `:has()` selector).

***

## 1.5.2

### Added

* **Unified toolbar**: `CoarDataGrid` now has built-in toolbar with `#toolbar-left`, `#toolbar-right` slots and `show-search` prop — replaces the need for `CoarDataGridPanel`. Toolbar appears automatically when search is enabled or any slot is used. Search input fills available space (`flex: 1`), actions are pushed to the right.
* **Appearance props**: `bordered` and `elevated` props on `CoarDataGrid` for border and elevation shadow. When toolbar is active, it gets padding while the grid sits flush.
* **Data Grid styles export**: `@cocoar/vue-data-grid/styles` now works without a Vite alias — added `./styles` to the package exports map.

### Changed

* **`CoarDataGridPanel` deprecated**: Use `CoarDataGrid` with `show-search` and `#toolbar-right` slot instead. `CoarDataGridPanel` remains as a thin wrapper for backwards compatibility.
* **Event handler composition**: `onRowClicked`, `onRowDoubleClicked`, `onCellClicked`, `onCellDoubleClicked` now use `#composeHandler` (multiple handlers are chained, not overwritten).
* **`onGridReady` isolation**: User's `builder.onGridReady()` handler no longer conflicts with internal grid initialization. `_bind()` always runs first, then the user handler.

### Fixed

* **Grid render flicker**: Fixed visible Layout Shift where columns animated from left to right on initial render. Root cause: AG Grid animates the `left` CSS property. Fix: `suppressColumnMoveAnimation` and `transition: none` on cells.
* **Flex columns with `rowDataRef`**: Fixed `flex()` and `autoSize('fitGridWidth')` not filling available width when using `rowDataRef()`. Column definitions are re-applied after data arrives to force a fresh flex layout pass.
* **Empty toolbar-right gap**: Fixed gap visible on the right side when no `#toolbar-right` slot content is provided.

***

## 1.5.1

### Fixed

* **Fragment parser bundle**: `vue`, `vue-router`, and `@cocoar/vue-ui` were embedded in the bundle instead of externalized, causing `injection "Symbol(route location)" not found` at runtime. Now correctly listed as rollup externals (bundle: 245 KB → 3.5 KB)

***

## 1.5.0

### Added

* **Quick Filter (Search)**: New `CoarDataGridSearch` and `CoarDataGridPanel` components for adding a search bar above the grid. `CoarDataGridPanel` combines search + grid in one component with a `#actions` slot for buttons. Search text filters row data before AG Grid using per-column configuration via `.quickFilter()`
* **Search highlighting**: `.searchHighlight()` on the builder enables the CSS Custom Highlight API to underline matching text in grid cells — no DOM manipulation, works with AG Grid virtualization
* **Tree Data**: `.treeData({ children, rowId })` enables hierarchical data with expand/collapse. New `col.tree()` column type renders indentation, animated chevron toggle, and child count. Search automatically expands matching branches
* **Row Drag & Drop**: `.rowDragManaged()` for flat list reordering with `.getDisplayedRowData()` to read the new order. `.onRowDragEnd()` callback for persisting changes
* **Tree Drag & Drop**: Drag rows between parents for reparenting. `.rowDragHighlight({ canDrop })` provides visual feedback — blue outline on valid targets, red dashed outline on invalid targets. Drop on empty area moves to root level
* **Tree meta access**: `builder.getTreeMeta(rowId)` exposes depth, hasChildren, isExpanded, and childCount — useful for custom `canDrop` validation (e.g., limiting nesting depth)
* **I18n column headers**: `.header('Name', 'i18n.key')` supports runtime language switching via `@cocoar/vue-localization` with automatic fallback when the package is not installed
* **Auto size**: `.autoSize('fitGridWidth')` and `.autoSize('fitCellContents')` for convenient column sizing
* **Fragment modal routing**: `@cocoar/vue-fragment-parser` now includes Vue composables for deep-linkable modals via URL fragments — `useFragmentNavigation()` (open/close modals by changing URL hash, `append` option for multi-modal), `useRoutedFragments()` (reactive fragment parsing), and `useRoutedModals()` (auto-open/close from URL). Two fragment types: `type: 'dialog'` (CoarDialog shell with header/title) and `type: 'modal'` (raw overlay, full control). Supports browser back/forward and deep-linking. `vue-router` and `@cocoar/vue-ui` are optional peer dependencies

### Fixed

* **Grid render flicker**: Fixed visible Layout Shift where columns animated from left to right on initial render. Root cause: AG Grid animates the `left` CSS property when positioning cells. Fix: `suppressColumnMoveAnimation` and `transition: none` on cells
* **Flex columns with `rowDataRef`**: Fixed `flex()` and `autoSize('fitGridWidth')` not filling available width when using `rowDataRef()`. Column definitions are re-applied after data arrives to force a fresh flex layout pass
* **Cell renderer scoped CSS**: Removed `scoped` from all AG Grid cell renderers (Tag, Icon, Date, Tree) — AG Grid doesn't apply Vue's `data-v-*` attributes, so scoped styles never matched
* **Cyclic dependency**: Removed unused `@cocoar/vue-fragment-parser` dependency from `@cocoar/vue-ui`
* **Turbo telemetry**: Disabled Turborepo telemetry in all CI workflows

### Docs

* **Data Grid**: Added interactive demos for Search, Tree Data, Row Drag & Drop, and Tree Drag & Drop with full API documentation including search highlighting, i18n headers, and auto size
* **Icons**: Added documentation for custom icon sources (SVG Map, HTTP Source, built-in overrides)
* **Fragment Parser & Modal Routing**: New documentation page with parser API, modal routing guide (composables, deep-linking, browser back), and step-by-step integration example
* **Playground app**: New `apps/playground/` for testing features that require Vue Router (fragment routing, etc.)
* **Markdown**: New documentation page for markdown parsing (`@cocoar/vue-markdown-core`) and rendering (`@cocoar/vue-markdown`)

***

## 1.3.0

### Added

* **Label position**: `CoarCheckbox` and `CoarRadioGroup` now support `labelPosition="before" | "after"` — place the label text before or after the control, matching the existing `CoarSwitch` API
* **Placeholder token**: New `--coar-text-placeholder` design token for consistent, clearly distinguishable placeholder styling across all input components

### Fixed

* **Placeholder color**: Placeholder text in all input components (TextInput, PasswordInput, NumberInput, Select, MultiSelect, TagSelect, PlainDatePicker, PlainDateTimePicker) was too dark and looked like actual input — now uses `--coar-text-placeholder` (`gray-400`) instead of `--coar-text-neutral-tertiary` (`gray-700`)

### Docs

* **Label Position demos**: New interactive examples for Checkbox, RadioGroup, and Switch showing `labelPosition="before"` vs `"after"`
* **API tables**: Updated props documentation for Checkbox and RadioGroup with the new `labelPosition` prop

***

## 1.2.0

### Added

* **Context Menu**: New `useContextMenu()` composable and `<CoarContextMenu>` component for right-click menus — handles positioning at cursor, viewport clamping, click-outside / Escape / scroll dismissal, and auto-close on item click
* **Data Grid context menu**: Works with `onCellContextMenu` and `onViewportContextMenu` — use separate `useContextMenu()` instances for cell vs. viewport right-clicks
* **Docs**: Context Menu documentation page with interactive demos (standalone, submenus, data grid integration)

***

## 1.1.0

### Added

* **Theming**: oklch-based color system — set `--coar-accent`, `--coar-success`, `--coar-error`, `--coar-warning`, `--coar-info` and all 10-step shade scales (50–900) auto-calculate for both light and dark mode
* **CoarSidebar**: New `variant` (`'primary' | 'secondary'`), `elevated`, and `borderless` props for visual customization
* **Kitchen Sink**: Full-page component showcase at `/foundations/kitchen-sink` for evaluating visual coherence
* **Theming guide**: New docs page at `/guide/theming` explaining color customization

### Fixed

* **Packaging**: `import '@cocoar/vue-ui/styles'` no longer crashes in consumer apps — moved OverlayScrollbars CSS import from `styles/all.css` (bare-specifier, unresolvable by PostCSS in consumer context) into `vScrollbar.ts` (bundled by Vite into `dist/index.css`)
* **Fonts export**: `@cocoar/vue-ui/fonts` now correctly points to compiled `dist/fonts.js` instead of unpublished `src/fonts.ts`
* **sideEffects**: Fixed `./src/fonts.ts` reference to `./dist/fonts.js` for correct tree-shaking

### Changed

* **Color primitives**: Replaced hand-picked hex values with oklch-based calculations — colors are now perceptually uniform across lightness levels, eliminating washed-out shades in dark mode and "baby blue" tints in light mode
* **Primary button**: Now uses `accent-500` (= exact brand color) instead of `accent-700` (darker shade) — `--coar-accent: #1183CD` means the primary button IS `#1183CD`
* **Build**: Added `fonts.ts` as second entry point, externalized `@fontsource/*` packages, removed `vite-plugin-css-injected-by-js` (not needed — hash mismatch was a misdiagnosis)
* **Sidebar variants**: `primary` = visually distinct from content (secondary background), `secondary` = same as content background

***

## 1.0.1

### Fixed

* **Temporal polyfill**: Moved `@js-temporal/polyfill` from optional peer dependency to regular dependency — fixes `Could not resolve "@js-temporal/polyfill"` errors in consuming apps using Vite

***

## 1.0.0

Initial release of the Cocoar Design System for Vue 3.

### Components

* **Form Controls**: Button, TextInput, PasswordInput, NumberInput, Select, MultiSelect, TagSelect, Checkbox, RadioGroup, Switch
* **Date & Time**: PlainDatePicker, PlainDateTimePicker, ZonedDateTimePicker, TimePicker, ScrollableCalendar
* **Navigation**: Menu, Sidebar, Navbar, Breadcrumb, Tabs, Pagination
* **Overlays**: Dialog, Popover, Popconfirm, Toast, Tooltip
* **Display**: Avatar, Badge, Card, CodeBlock, Divider, Label, Link, Note, ProgressBar, Spinner, Table, Tag
* **Utilities**: Icon, Scrollbar
* **Layout**: FormField — wrapper for label, hint, and validation around any form control
* **Transitions**: Fade, Slide, Scale, Collapse — pre-built Vue `<Transition>` wrappers using motion tokens
* **Data Grid**: AG Grid wrapper (`@cocoar/vue-data-grid`, separate package)
* **Markdown**: Markdown viewer (`@cocoar/vue-markdown`, separate package)

### Design System

* Two-layer token system: primitives referenced by semantic tokens
* 6 token categories: Color, Typography, Spacing, Radius, Shadow, Motion
* Light and dark mode via `.dark-mode` class (no JS at render time)
* CSS `@layer` cascade for predictable specificity
* Tablet-first design: touch interaction with desktop information density

### Localization

* All 57 built-in component strings (aria-labels, button text, placeholders) translatable via `useI18n()` from `@cocoar/vue-localization`
* English defaults — works without any configuration
* Locale-aware `firstDayOfWeek` detection via `Intl.Locale.getWeekInfo()`
* Date format pattern auto-detection from browser `Intl` API

### Responsive

* Date picker panels: viewport-clamped widths via CSS `min()`, stacked layout below 540px
* Overlay system: `shift` + `flip` positioning, `maxWidth: 'viewport'` constraint
* Typography scales across 3 breakpoints (1024px+, 768–1023px, <768px)

### Architecture

* Monorepo: pnpm workspaces + Turborepo
* 8 packages: `vue-ui`, `vue-data-grid`, `vue-markdown`, `vue-markdown-core`, `vue-localization`, `vue-fragment-parser`, docs, icons
* Self-hosted fonts via `@fontsource` (Poppins + Inter) — `import '@cocoar/vue-ui/fonts'`
* Overlay service with plugin architecture (`CoarOverlayPlugin` + `CoarOverlayHost`)
* Overlay companion detection for teleported dropdowns (Select inside overlays)
* Temporal API for date/time components — native in Chrome/Firefox/Edge, optional polyfill for Safari

### Accessibility

* ARIA attributes across all interactive components
* Keyboard navigation: roving tabindex in menus/tabs, arrow keys, Escape to close
* Focus management: focus trap in dialogs, focus restoration on close
* `prefers-reduced-motion` respected — all motion tokens collapse to 0ms
* Screen reader support: live regions for toasts, semantic roles, `aria-describedby` chains

### Documentation

* VitePress docs with 47 pages, deployed to docs.cocoar.dev via Shelf
* Interactive demos with source code preview
* i18n keys documented on each component page
* Design principles, typography, colors, spacing, motion foundations
* Localization guide: l10n formatting, i18n translations, timezone providers
* Form validation examples with vee-validate + Zod
* Error handling guide

### Bundle

* `@cocoar/vue-ui`: 378 KB JS (86 KB gzip), 167 KB CSS (17 KB gzip)
* Tree-shakeable: all dependencies externalized
* `@js-temporal/polyfill` included as dependency (Temporal API for date/time components)

---

---
url: /foundations/design-principles.md
---
# Design Principles

The foundation of the Cocoar Design System — six principles that guide every design decision across our Vue 3 component library.

***

### Clarity

Every element has a clear purpose. Reduce visual noise and make the important thing obvious.

* Consistent spacing creates visual rhythm that guides scanning
* Typography hierarchy directs attention to what matters most
* Limit each view to one primary action to reduce decision fatigue
* Use whitespace generously — empty space is not wasted space

***

### Consistency

Use the same patterns, tokens, and components everywhere. Predictability reduces cognitive load and builds trust.

* Shared token vocabulary across colors, spacing, radius, and motion
* Uniform component API patterns — props, events, and slots follow conventions
* Consistent interaction models — similar controls behave identically
* One way to do things, not many — fewer choices lead to better outcomes

***

### Accessibility

Design for everyone. Meet WCAG AA standards at minimum. Keyboard navigation is not optional — it is a core feature.

* **4.5 : 1** minimum contrast ratio for all text content
* Full keyboard navigation built into every interactive component
* Screen reader support with proper ARIA attributes
* Focus indicators that are visible and consistent
* Respect `prefers-reduced-motion` for users who need it

***

### Touch-First

All components work with **touch and focus** — hover is an enhancement, not a requirement. This is **tablet-first** design: touch interaction with desktop-appropriate information density. Not mobile-first — mobile phones have different constraints (small screens, portrait orientation, one-handed use). Tablets have similar screen real estate to laptops but use touch instead of mouse.

* Minimum **44 x 44 px** touch targets on all interactive elements
* Appropriate tap spacing to prevent accidental activation
* No hover-only interactions — every feature is reachable via tap or keyboard
* Use dimmed states instead of hiding; on focus/hover elements become prominent
* Desktop gets additional polish (hover states) as progressive enhancement

***

### Performance

Ship less, load faster. Icons are inlined SVGs. Components are tree-shakeable. CSS theming uses custom properties for zero runtime cost.

* Inline SVG icons eliminate icon font overhead
* Individual component imports enable dead-code elimination
* CSS custom property theming — no JavaScript at render time
* Lightweight component architecture with minimal dependencies

***

### Developer Experience

Strong TypeScript types. Composable APIs. Predictable naming. The system should be a joy to use, not a chore to learn.

* Full TypeScript support with exported types for every component
* Consistent `v-model` patterns across all form controls
* Self-documenting prop names — no guessing what `mode="3"` means
* Composable utilities (`useDialog`, `useToast`) for programmatic control

***

## Design Token Architecture

Cocoar uses a **two-layer token system**: raw primitives are referenced by semantic tokens. Always use semantic tokens in your components — they adapt automatically to light and dark mode.

| Category | Token Prefix | Description |
|---|---|---|
| **Color** | `--coar-color-*` | Raw color primitives (gray, slate, accent, green, red, amber) |
| **Background** | `--coar-background-*` | Semantic surface tokens for accent, brand, neutral, and status |
| **Text** | `--coar-text-*` | Text color tokens for all states and emphasis levels |
| **Border** | `--coar-border-*` | Border color tokens for interactive and structural elements |
| **Spacing** | `--coar-spacing-*` | Space scale from `xxs` (2 px) to `xxxl` (64 px) on a 4 px grid |
| **Radius** | `--coar-radius-*` | Border radius from `xxs` (1 px) to `full` (999 px) |
| **Shadow** | `--coar-shadow-*` | Elevation shadows `xs`–`xl` plus a focus ring |
| **Typography** | `--coar-titles-*` / `--coar-headings-*` / `--coar-body-*` | Font family, size, and weight tokens for each text role |
| **Motion** | `--coar-duration-*` / `--coar-ease-*` / `--coar-transition-*` | Duration, easing, and pre-composed transition tokens |

## Do's and Don'ts

::: tip Do

* Use semantic tokens — `--coar-text-neutral-primary`, not a raw hex value
* Follow the **4 px spacing grid** for all layout dimensions
* Use `v-model` for two-way binding on form controls
* Import components individually for tree-shaking: `import { CoarButton } from '@cocoar/vue-ui'`
* Test keyboard navigation for every interactive flow
* Provide `aria-label` for icon-only buttons
  :::

::: danger Don't

* Hardcode colors or spacing values in component styles
* Use primitive tokens directly in components (`--coar-color-gray-500`)
* Override component internals with `:deep()` selectors
* Create hover-only interactions that exclude touch and keyboard users
* Mix spacing values that are not on the 4 px grid
* Ignore `prefers-reduced-motion` in custom animations
  :::

::: info Dark Mode
Toggle dark mode by adding the `.dark-mode` class to `document.documentElement`. All tokens and components update automatically — no JavaScript required at render time.
:::

---

---
url: /foundations/colors.md
---
# Colors

Cocoar's color system is built on two layers: **primitives** (the raw palette) and **semantic tokens** (purpose-driven aliases). Semantic tokens adapt to light and dark mode automatically — always use them in your components instead of referencing primitives directly.

## Color Primitives

Six scales, ten shades each. These are the building blocks that semantic tokens reference under the hood.

::: tip When to use primitives
Almost never. Use semantic tokens in component code. Primitives are useful only when defining new semantic tokens or building one-off illustrations.
:::

## Semantic Colors

Semantic tokens give colors *meaning* — background, text, border, or status — so your UI stays consistent and adapts to theme changes without touching component code.

## Usage Example

A realistic card built entirely with semantic tokens. Toggle light/dark mode to see every color adapt.

## Token Naming Convention

All tokens follow a predictable pattern:

```
--coar-{usage}-{category}-{variant}
```

| Segment | Values | Examples |
|---------|--------|----------|
| **Usage** | `background`, `text`, `border`, `icon` | What the color is applied to |
| **Category** | `neutral`, `brand`, `accent`, `semantic-{status}` | The color family |
| **Variant** | `primary`, `secondary`, `tertiary`, `bold`, `subtle`, `hover`, `active`, `disabled` | Emphasis level or state |

## Token Reference

### Background

| Token | Usage |
|-------|-------|
| `--coar-background-neutral-primary` | Default page / card surface |
| `--coar-background-neutral-secondary` | Slightly raised surface |
| `--coar-background-neutral-tertiary` | Subtle fill for inputs, hover states |
| `--coar-background-accent-primary` | Primary accent (buttons, active states) |
| `--coar-background-accent-secondary` | Lighter accent fill |
| `--coar-background-accent-tertiary` | Subtlest accent fill |
| `--coar-background-accent-hover` | Accent hover state |
| `--coar-background-accent-active` | Accent pressed state |
| `--coar-background-brand-primary` | Brand-colored surface |
| `--coar-background-brand-secondary` | Lighter brand surface |
| `--coar-background-brand-tertiary` | Subtlest brand surface |

### Text

| Token | Usage |
|-------|-------|
| `--coar-text-neutral-primary` | Primary body text |
| `--coar-text-neutral-secondary` | Supporting / secondary text |
| `--coar-text-neutral-tertiary` | Placeholder, hint text |
| `--coar-text-neutral-disabled` | Disabled text |
| `--coar-text-accent-primary` | Accent-colored text (links, highlights) |
| `--coar-text-accent-secondary` | Lighter accent text |
| `--coar-text-brand-primary` | Brand-colored text |
| `--coar-text-on-bold` | White text on bold / colored surfaces |

### Border

| Token | Usage |
|-------|-------|
| `--coar-border-neutral-primary` | Strong border (emphasis) |
| `--coar-border-neutral-secondary` | Default visible border |
| `--coar-border-neutral-tertiary` | Subtle divider |
| `--coar-border-accent-primary` | Accent border (focus rings) |
| `--coar-border-accent-secondary` | Lighter accent border |
| `--coar-border-input` | Input field border |
| `--coar-border-input-hover` | Input border on hover |

### Status

| Token | Usage |
|-------|-------|
| `--coar-background-semantic-success-bold` | Success background (solid) |
| `--coar-background-semantic-success-subtle` | Success background (light) |
| `--coar-background-semantic-error-bold` | Error background (solid) |
| `--coar-background-semantic-error-subtle` | Error background (light) |
| `--coar-background-semantic-warning-bold` | Warning background (solid) |
| `--coar-background-semantic-warning-subtle` | Warning background (light) |
| `--coar-background-semantic-info-bold` | Info background (solid) |
| `--coar-background-semantic-info-subtle` | Info background (light) |
| `--coar-text-semantic-success-bold` | Success text (strong) |
| `--coar-text-semantic-error-bold` | Error text (strong) |
| `--coar-text-semantic-warning-bold` | Warning text (strong) |
| `--coar-text-semantic-info-bold` | Info text (strong) |

---

---
url: /foundations/typography.md
---
# Typography

Our type system creates clear visual hierarchy and ensures readability across all interfaces. Eleven styles cover everything from large display headings to fine-print footnotes.

## Type Scale

Each row shows the style rendered at its actual size, with font metadata alongside.

## Usage Example

Typography hierarchy applied to a realistic article layout — caption, title, subtitle, body, and footnote working together.

## CSS Classes Reference

Apply these utility classes directly to any HTML element.

| Class | Role | Font | Size | Weight |
|---|---|---|---|---|
| `.coar-display` | Display | Inter | 72 px | Bold |
| `.coar-title` | Title | Inter | 48 px | Bold |
| `.coar-subtitle` | Subtitle | Inter | 32 px | Regular |
| `.coar-heading` | Heading | Poppins | 24 px | SemiBold |
| `.coar-subheading` | Subheading | Poppins | 20 px | Regular |
| `.coar-body` | Body | Poppins | 16 px | Regular |
| `.coar-body-bold` | Body Bold | Poppins | 16 px | Bold |
| `.coar-body-small` | Body Small | Poppins | 14 px | Regular |
| `.coar-body-small-bold` | Body Small Bold | Poppins | 14 px | Bold |
| `.coar-caption` | Caption | Poppins | 12 px | Medium, Uppercase |
| `.coar-footnote` | Footnote | Poppins | 10 px | Regular |

## Usage

```html
<h1 class="coar-title">Page Title</h1>
<p class="coar-subtitle">Supporting subtitle text</p>
<p class="coar-body">Main body content goes here.</p>
<span class="coar-caption">LABEL TEXT</span>
```

::: tip Font Loading
The type scale uses **Inter** for display-level text and **Poppins** for body and UI text. Import `@cocoar/vue-ui/fonts` to self-host both fonts — no external CDN required.
:::

---

---
url: /foundations/spacing.md
---
# Spacing & Effects

Layout rhythm, corner shapes, and depth — the visual building blocks that give the system its feel.

## Border Radius

Seven radius tokens shape everything from subtle input rounding to fully circular avatars.

## Spacing Scale

All spacing is built on a **4 px grid**. These tokens control padding, margins, and gaps throughout the system.

## Stroke Width

Border thickness for dividers, outlines, and component borders.

| Token | Value | Use case |
|-------|-------|----------|
| `--coar-stroke-width-xs` | 0.5 px | Hairline dividers |
| `--coar-stroke-width-s` | 1 px | Default borders |
| `--coar-stroke-width-m` | 2 px | Emphasis borders |
| `--coar-stroke-width-l` | 4 px | Heavy accents |

## Shadows & Elevation

Six shadow levels create the illusion of depth. The shadow *is* the demo — notice how each card lifts further off the surface.

## Token Reference

### Spacing

| Token | Value | Usage |
|-------|-------|-------|
| `--coar-spacing-xxs` | 2 px | Tight inner gaps |
| `--coar-spacing-xs` | 4 px | Small padding, icon gaps |
| `--coar-spacing-s` | 8 px | Compact padding, list gaps |
| `--coar-spacing-m` | 16 px | Default padding and gaps |
| `--coar-spacing-l` | 24 px | Section padding |
| `--coar-spacing-xl` | 32 px | Large section gaps |
| `--coar-spacing-xxl` | 48 px | Page-level spacing |
| `--coar-spacing-xxxl` | 64 px | Hero / splash spacing |

### Border Radius

| Token | Value |
|-------|-------|
| `--coar-radius-xxs` | 1 px |
| `--coar-radius-xs` | 2 px |
| `--coar-radius-s` | 3 px |
| `--coar-radius-m` | 4 px |
| `--coar-radius-l` | 5 px |
| `--coar-radius-xl` | 6 px |
| `--coar-radius-full` | 999 px |

### Shadows

| Token | Usage |
|-------|-------|
| `--coar-shadow-xs` | Subtle lift for hover states |
| `--coar-shadow-s` | Cards and raised elements |
| `--coar-shadow-m` | Dropdowns and popovers |
| `--coar-shadow-l` | Modals and dialogs |
| `--coar-shadow-xl` | Elevated overlays |
| `--coar-shadow-focus` | Keyboard focus ring |

---

---
url: /foundations/icons.md
---
# Icons

A flexible icon system with built-in SVG icons. Icons support multiple sizes, colors, rotation, and animations.

```ts
import { CoarIcon } from '@cocoar/vue-ui';
```

## Icon Gallery

## Sizes

Icons come in 5 preset sizes and can use any valid CSS value.

## Colors

Icons inherit color by default. Override with any valid CSS color value.

## Rotation

Rotate icons to any angle using the `rotate` prop.

## Spin Animation

Enable continuous spinning for loading indicators.

## Custom Icon Sources

Register your own icons alongside the built-in set. Cocoar supports multiple icon sources with automatic fallback.

### SVG Map (Inline Icons)

Register a set of SVG strings — resolved synchronously, no network requests.

```ts
// main.ts
import { CoarIconPlugin, CoarIconMapSource } from '@cocoar/vue-ui';

app.use(CoarIconPlugin, {
  sources: [
    {
      key: 'app',
      source: new CoarIconMapSource({
        'logo': '<svg viewBox="0 0 24 24">...</svg>',
        'dashboard': '<svg viewBox="0 0 24 24">...</svg>',
      }),
    },
  ],
  defaultSource: 'app', // check custom icons first
});
```

```vue
<template>
  <!-- Resolves from 'app' source first, then built-in -->
  <CoarIcon name="logo" size="xl" />

  <!-- Explicitly target a source -->
  <CoarIcon name="settings" source="coar-builtin" />
</template>
```

### HTTP Source (Remote Icons)

Load icons on demand from a URL. Responses are cached automatically.

```ts
import { CoarIconPlugin, CoarHttpIconSource } from '@cocoar/vue-ui';

app.use(CoarIconPlugin, {
  sources: [
    {
      key: 'cdn',
      source: new CoarHttpIconSource(
        (name) => `https://cdn.example.com/icons/${name}.svg`,
      ),
    },
  ],
});
```

```vue
<!-- Fetched async, shows nothing while loading -->
<CoarIcon name="custom-icon" source="cdn" />
```

### Override Built-in Icons

Replace specific built-in icons without creating a full source:

```ts
app.use(CoarIconPlugin, {
  builtInOverrides: {
    'settings': '<svg viewBox="0 0 24 24"><!-- your custom settings icon --></svg>',
  },
});
```

### Resolution Order

When no `source` prop is specified, icons are resolved in this order:

1. **Default source** (set via `defaultSource` option)
2. **Additional sources** (in registration order)
3. **Built-in icons** (`coar-builtin`)

The first source that returns a match wins. Use the `source` prop to bypass fallback and target a specific source directly.

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | `—` | Icon name from the registered icon set |
| `source` | `string` | — | Target a specific icon source (bypasses fallback) |
| `size` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl' \| string` | `'m'` | Icon size (preset or custom CSS value) |
| `color` | `string` | `'inherit'` | Icon color (any valid CSS color) |
| `strokeWidth` | `number` | — | Override stroke width for stroke-based icons |
| `rotate` | `number` | `0` | Rotation angle in degrees |
| `rotateTransition` | `number \| string` | — | Rotation animation (ms or CSS transition) |
| `spin` | `boolean` | `false` | Enable continuous spinning animation |
| `label` | `string \| number` | — | Text label displayed next to the icon |

### Size Reference

| Size | Pixels |
|------|--------|
| `xs` | 12px |
| `s` | 16px |
| `m` | 20px |
| `l` | 24px |
| `xl` | 32px |

---

---
url: /foundations/motion.md
---
# Motion

Timing, easing, and pre-composed transitions that make the UI feel responsive and alive.

## Duration

How long an animation takes. Short durations suit small changes; longer ones give complex movements room to breathe. Press **Play** to see each duration side by side.

## Easing

How animations accelerate and decelerate. Press **Play** to compare every curve at the same duration.

## Pre-composed Transitions

Ready-made `transition` values that pair a duration with an easing curve. Hover each button to see the effect it controls.

## Usage

### Basic transition

```css
.my-element {
  transition: var(--coar-transition-default);
}
```

### Custom transition with tokens

```css
.my-element {
  transition:
    background-color var(--coar-duration-normal) var(--coar-ease-out),
    transform var(--coar-duration-fast) var(--coar-ease-bounce);
}
```

### Animation with duration

```css
@keyframes slide-in {
  from { transform: translateY(-8px); opacity: 0; }
  to   { transform: translateY(0);    opacity: 1; }
}

.my-element {
  animation: slide-in var(--coar-duration-normal) var(--coar-ease-out);
}
```

## Accessibility

All motion tokens respect the `prefers-reduced-motion` media query. When a user opts for reduced motion, every duration collapses to `0 ms` — transitions become instant and nothing moves unexpectedly.

```css
@media (prefers-reduced-motion: reduce) {
  :root {
    --coar-duration-fast:    0ms;
    --coar-duration-normal:  0ms;
    --coar-duration-slow:    0ms;
    --coar-duration-slower:  0ms;
    --coar-duration-slowest: 0ms;
  }
}
```

::: info
Always use COAR duration tokens instead of hardcoded values. This ensures animations are automatically disabled for users who prefer reduced motion.
:::

## Token Reference

### Duration

| Token | Value | Usage |
|-------|-------|-------|
| `--coar-duration-instant` | 0 ms | No animation (immediate) |
| `--coar-duration-fast` | 100 ms | Micro-interactions, hover states |
| `--coar-duration-normal` | 200 ms | Most transitions |
| `--coar-duration-slow` | 300 ms | Complex state changes |
| `--coar-duration-slower` | 400 ms | Large movements |
| `--coar-duration-slowest` | 600 ms | Page-level transitions |

### Easing

| Token | Usage |
|-------|-------|
| `--coar-ease-linear` | Constant speed — for opacity, color |
| `--coar-ease-out` | Fast start, slow end — most UI motion |
| `--coar-ease-in` | Slow start, fast end — dismissals |
| `--coar-ease-in-out` | Slow start and end — complex motions |
| `--coar-ease-bounce` | Elastic overshoot — playful feedback |

### Pre-composed Transitions

| Token | Usage |
|-------|-------|
| `--coar-transition-default` | General-purpose transition |
| `--coar-transition-fast` | Quick micro-interactions |
| `--coar-transition-colors` | Background and text color changes |
| `--coar-transition-transform` | Scale, rotate, translate |
| `--coar-transition-opacity` | Show / hide transitions |
| `--coar-transition-shadow` | Elevation changes on hover |

---

---
url: /foundations/localization/setup.md
---
# Localization Setup

A complete localization system for Vue 3 covering locale-aware formatting (l10n), translations (i18n), and timezone detection. Provided by the optional `@cocoar/vue-localization` package.

::: info Separate Package
The localization system is shipped separately from `@cocoar/vue-ui` to keep the core bundle lean. Install it only when you need it.

```bash
pnpm add @cocoar/vue-localization
```

:::

## Setup

Register the plugin in your app entry point. The `createCoarLocalization()` factory creates both the plugin and the underlying service instance.

```ts
// main.ts
import { createApp } from 'vue';
import { createCoarLocalization } from '@cocoar/vue-localization';
import App from './App.vue';

const app = createApp(App);

app.use(createCoarLocalization({
  defaultLanguage: 'en',
  // Optional: load locale data from your server
  l10nUrl: (lang) => `/locales/${lang}.json`,
  // Optional: load translations from your server
  i18nUrl: (lang) => `/i18n/${lang}.json`,
}));

app.mount('#app');
```

The `defaultLanguage` is loaded automatically on startup using the browser's `Intl` API as a data source. No JSON files are needed for basic formatting -- the system derives number separators, date patterns, currency symbols, and more directly from `Intl`.

### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `defaultLanguage` | `string` | `'en'` | Initial language code |
| `l10nUrl` | `(lang: string) => string` | `undefined` | URL builder for locale data JSON (overrides Intl defaults) |
| `i18nUrl` | `(lang: string) => string` | `undefined` | URL builder for translation JSON |
| `timezoneProviders` | `CoarTimezoneProvider[]` | `[]` | Custom timezone providers (checked before browser default) |

## Changing Language at Runtime

Use the service directly to switch languages. Data is loaded on demand and cached.

```ts
import { useLocalization } from '@cocoar/vue-localization';

const service = useLocalization()!;

// Switch language (loads locale data + translations if not cached)
await service.setLanguage('de');

// Preload without switching (useful for instant switching later)
await service.preloadLanguage('fr');

// Force reload from all sources (e.g. after server-side data changes)
await service.reloadLanguage();
```

## Service API

The `useLocalization()` composable returns the full `CoarLocalizationService` instance for advanced use cases.

| Method / Property | Type | Description |
|-------------------|------|-------------|
| `language` | `Ref<string>` | Current language (reactive) |
| `loading` | `Ref<boolean>` | Whether data is currently being loaded |
| `localeData` | `ComputedRef<CoarLocalizationData \| undefined>` | Locale data for the current language |
| `setLanguage(lang)` | `(string) => Promise<void>` | Switch language and load data |
| `preloadLanguage(lang)` | `(string) => Promise<void>` | Preload data without switching |
| `reloadLanguage(lang?)` | `(string?) => Promise<void>` | Force reload data from all sources |
| `t(key, params?, fallback?)` | `(string, Record?, string?) => string` | Translate a key |
| `getDefaultLanguage()` | `() => string` | Get the configured default language |
| `i18nStore` | `CoarTranslationStore` | Direct access to the translation store |
| `l10nStore` | `CoarLocalizationDataStore` | Direct access to the locale data store |
| `timezoneService` | `CoarTimezoneService` | Direct access to the timezone service |
| `addLocaleDataSource(source)` | `(CoarLocaleDataSource) => void` | Add a custom locale data source |
| `addTranslationSource(source)` | `(CoarTranslationSource) => void` | Add a custom translation source |

---

---
url: /foundations/localization/formatting.md
---
# Formatting

Locale-aware formatting for numbers, currencies, percentages, and dates. All formatters react to language changes automatically via the `useL10n()` composable from `@cocoar/vue-localization`.

## Number and Currency Formatting

Toggle between locales to see how separators, grouping, and currency symbols adapt.

### Usage

```vue
<script setup lang="ts">
import { useL10n } from '@cocoar/vue-localization';

const { language, fmtNumber, fmtCurrency, fmtPercent } = useL10n();
</script>

<template>
  <p>{{ fmtNumber(1234567.89) }}</p>       <!-- "1,234,567.89" in en -->
  <p>{{ fmtNumber(1234567.89, 0) }}</p>    <!-- "1,234,568" in en -->
  <p>{{ fmtCurrency(9999.99) }}</p>         <!-- "$9,999.99" in en -->
  <p>{{ fmtCurrency(9999.99, 'EUR') }}</p>  <!-- "EUR9,999.99" in en -->
  <p>{{ fmtPercent(0.256) }}</p>            <!-- "26%" in en -->
  <p>{{ fmtPercent(0.256, 2) }}</p>         <!-- "25.60%" in en -->
</template>
```

### `useL10n()` API

| Property | Type | Description |
|----------|------|-------------|
| `language` | `Ref<string>` | Current language (reactive) |
| `localeData` | `ComputedRef<CoarLocalizationData \| undefined>` | Full locale data for the current language |
| `fmtNumber(value, decimals?)` | `(number, number?) => string` | Format a number with locale separators |
| `fmtCurrency(value, currencyCode?)` | `(number, string?) => string` | Format as currency (defaults to locale's currency) |
| `fmtPercent(value, decimals?)` | `(number, number?) => string` | Format as percentage (0.25 becomes "25%") |
| `fmtDate(value, includeTime?)` | `(Date \| string, boolean?) => string` | Format a date (optionally with time) |

## Date Formatting

Dates are formatted according to the locale's date pattern. The system detects whether the locale uses `dd/mm/yyyy`, `mm/dd/yyyy`, `dd.mm.yyyy`, or `yyyy-mm-dd` from the browser's `Intl` API. Switch locales to see both the formatted output and the underlying locale metadata.

### Usage

```vue
<script setup lang="ts">
import { useL10n } from '@cocoar/vue-localization';

const { fmtDate } = useL10n();
</script>

<template>
  <p>{{ fmtDate(new Date()) }}</p>                   <!-- date only -->
  <p>{{ fmtDate(new Date(), true) }}</p>              <!-- date + time -->
  <p>{{ fmtDate('2025-12-31T23:59:00') }}</p>         <!-- from ISO string -->
</template>
```

## Regional Locales

Same language, different region — `en-US` vs `en-GB`, `de-DE` vs `de-AT`, `fr-FR` vs `fr-CH`. The system loads the base locale first, then merges regional overrides on top. This means currency symbols, date patterns, and number formatting automatically adapt to the user's region without duplicating the entire locale definition.

## Locale Data Structure

When providing locale data via HTTP (the `l10nUrl` option), the JSON should follow the `CoarLocalizationData` shape:

```json
{
  "code": "de",
  "date": {
    "pattern": "dd.mm.yyyy",
    "firstDayOfWeek": 1,
    "monthNames": ["Januar", "Februar", "..."],
    "monthNamesShort": ["Jan", "Feb", "..."],
    "dayNames": ["Sonntag", "Montag", "..."],
    "dayNamesShort": ["So", "Mo", "..."],
    "amPm": ["AM", "PM"]
  },
  "number": {
    "decimal": ",",
    "group": ".",
    "grouping": [3]
  },
  "currency": {
    "default": "EUR",
    "symbols": { "EUR": "\u20ac", "USD": "$" },
    "position": "after",
    "spacing": true,
    "decimals": 2
  },
  "percent": {
    "symbol": "%",
    "spacing": true,
    "decimals": 0
  }
}
```

::: tip
You typically do not need to provide locale JSON files. The built-in `IntlLocaleDataSource` derives all of this from the browser's `Intl` API. HTTP sources are useful when you need to override specific values (e.g. custom currency symbols or non-standard grouping).
:::

---

---
url: /foundations/localization/translations.md
---
# Translations

The `useI18n()` composable provides translation lookup with parameter interpolation. Translations can come from HTTP sources (configured via `i18nUrl`) or be registered directly in code using the service's `i18nStore`.

Parameters use `{name}` syntax and are replaced at runtime. Nested translation objects are automatically flattened to dot-separated keys.

## Usage

```vue
<script setup lang="ts">
import { useI18n } from '@cocoar/vue-localization';

const { t, tRef, language } = useI18n();

// Immediate value (call in template for reactivity)
// t('greeting', { name: 'Alice' })  →  "Hello, Alice!"

// Computed ref (reacts to language changes automatically)
const title = tRef('app.title');
</script>

<template>
  <h1>{{ title }}</h1>
  <p>{{ t('greeting', { name: 'Alice' }) }}</p>
  <p>{{ t('missing.key', {}, 'Fallback text') }}</p>
</template>
```

## Registering Translations in Code

For cases where HTTP loading is not appropriate (tests, demos, embedded apps), you can register translations directly on the service.

```ts
import { useLocalization } from '@cocoar/vue-localization';

const service = useLocalization()!;

service.i18nStore.setTranslations('en', {
  greeting: 'Hello, {name}!',
  actions: {
    save: 'Save',
    cancel: 'Cancel',
  },
});

service.i18nStore.setTranslations('de', {
  greeting: 'Hallo, {name}!',
  actions: {
    save: 'Speichern',
    cancel: 'Abbrechen',
  },
});
```

Nested keys are automatically flattened: `actions.save` resolves `'Save'` for English.

## `useI18n()` API

| Property | Type | Description |
|----------|------|-------------|
| `language` | `Ref<string>` | Current language (reactive) |
| `t(key, params?, fallback?)` | `(string, Record?, string?) => string` | Translate a key with optional interpolation |
| `tRef(key, params?, fallback?)` | `(string, Record?, string?) => ComputedRef<string>` | Computed translation that reacts to language changes |

## Translation Fallback Behavior

1. Look up the key in the current language (e.g. `de-AT`)
2. If not found and locale is regional, try the base language (`de`)
3. If still not found, use the provided `fallback` argument
4. If no fallback, return the key itself

## Translating Component Strings

All built-in text in Cocoar UI components -- `aria-label`s, button labels, empty state messages, screen-reader announcements -- defaults to English and can be translated by providing a `coar.ui.*` namespace in your translation JSON.

If the localization plugin is **not** installed, every string falls back to its English default automatically. Nothing breaks, nothing needs to be configured.

```
Plugin not installed        →  English fallbacks (default)
Plugin installed            →  Translated strings, if the key exists in your JSON
Plugin installed, key missing  →  English fallback
```

Your translation file only needs to contain the keys you want to override:

```json
{
  "coar": {
    "ui": {
      "dialog": { "dialog": "Dialog", "close": "Schließen" },
      "select": { "noResults": "Keine Ergebnisse", "noOptions": "Keine Optionen verfügbar" },
      "datePicker": {
        "dialog": "Datumsauswahl",
        "clearDate": "Datum löschen",
        "previousYear": "Vorheriges Jahr",
        "nextYear": "Nächstes Jahr",
        "months": "Monate"
      },
      "toast": { "dismiss": "Benachrichtigung schließen" }
    }
  }
}
```

Each component's documentation page lists its translatable keys under an **i18n Keys** section. Check the component page you're working with for the exact keys available.

::: tip Props as alternative
If you only need to change a single string in one place, some components offer direct props -- for example `CoarSpinner` has a `label` prop, `CoarPopconfirm` has `confirmText` and `cancelText`. Check the component's **Props** table first before reaching for i18n.
:::

---

---
url: /foundations/localization/timezones.md
---
# Timezones

The `useTimezone()` composable provides the browser's detected IANA timezone identifier as a reactive ref. The date/time picker components in `@cocoar/vue-ui` use this automatically.

## Usage

```vue
<script setup lang="ts">
import { useTimezone } from '@cocoar/vue-localization';

const { timezone, refresh } = useTimezone();

// timezone.value → "Europe/Berlin", "America/New_York", etc.
</script>

<template>
  <p>Your timezone: {{ timezone }}</p>
  <button @click="refresh()">Re-detect</button>
</template>
```

## Custom Timezone Providers

You can supply custom providers (e.g. from a user profile API) that are checked before the browser default.

```ts
import { createCoarLocalization } from '@cocoar/vue-localization';
import type { CoarTimezoneProvider } from '@cocoar/vue-localization';

const userTimezone: CoarTimezoneProvider = {
  getTimezone() {
    // Return from user settings, or null to defer to next provider
    return userStore.timezone ?? null;
  },
};

app.use(createCoarLocalization({
  timezoneProviders: [userTimezone],
}));
```

## `useTimezone()` API

| Property | Type | Description |
|----------|------|-------------|
| `timezone` | `Ref<string>` | Current IANA timezone identifier (reactive) |
| `refresh()` | `() => void` | Re-resolve timezone from providers |

---

---
url: /components/button.md
---
# Button

Buttons trigger actions and communicate what will happen when pressed.

```ts
import { CoarButton } from '@cocoar/vue-ui';
```

## Variants

Choose the appropriate variant based on the action's importance and context.

**When to use each variant:**

* **Primary** — Main call-to-action. Use sparingly, typically once per view.
* **Secondary** — Alternative actions. Pairs well with primary buttons.
* **Tertiary** — Low-emphasis actions with brand color hint.
* **Danger** — Destructive actions like delete or remove.
* **Ghost** — Minimal emphasis, often for cancel or dismiss.

## Sizes

Four sizes to fit different contexts and layouts.

## Icons

Add icons before or after the label to enhance meaning.

## Loading State

Show a spinner while an async action is in progress. Click to test.

## Disabled State

Disable buttons when actions are not available.

## Full Width

Buttons can expand to fill their container.

## Accessibility

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Tab` | Move focus to button |
| `Shift + Tab` | Move focus backward |
| `Enter` | Activate button |
| `Space` | Activate button |

::: info
Disabled and loading buttons cannot be activated via keyboard.
:::

### Screen Reader Support

* Button text or `aria-label` announces on focus
* Disabled state properly communicated
* Loading state indicates button is busy
* Icon-only buttons should include `aria-label`
* `type` attribute ensures correct form behavior

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'danger' \| 'ghost'` | `'primary'` | Button style variant |
| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Button size |
| `iconStart` | `string` | `undefined` | Icon name before label |
| `iconEnd` | `string` | `undefined` | Icon name after label |
| `loading` | `boolean` | `false` | Show loading spinner |
| `disabled` | `boolean` | `false` | Disable the button |
| `fullWidth` | `boolean` | `false` | Expand to fill container |
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | HTML button type |

### Events

| Event | Payload | Description |
|-------|---------|-------------|
| `click` | `MouseEvent` | Emitted when clicked (not when disabled/loading) |

## i18n Keys

These keys can be translated via [`@cocoar/vue-localization`](/foundations/localization/translations).

| Key | Default (English) | Used as |
|-----|-------------------|---------|
| `coar.ui.button.loading` | `'Loading'` | Screen reader announcement when `loading` is true |

---

---
url: /components/form-field.md
---
# Form Field

A wrapper component that provides a label, hint text, and error message around any form control. Instead of each input managing its own label and validation display, `CoarFormField` handles these concerns in one place.

```ts
import { CoarFormField } from '@cocoar/vue-ui';
```

## Basic Usage

Wrap any form control in `CoarFormField` and pass `label`, `hint`, or `error` props. The label is automatically associated with the input inside via generated IDs.

## Grouping Controls

Use `CoarFormField` to add a group label and shared error to a set of checkboxes or radio buttons. Each checkbox keeps its own inline `label` prop for the option text.

## Registration Form

A complete registration form with submit-on-click validation. Errors only appear after the user attempts to submit.

## Settings Panel

A settings page using every form control type — text inputs, textareas, selects, checkboxes, radio groups, and switches — all wrapped in `CoarFormField` for consistent layout.

## Validation with vee-validate

`CoarFormField` integrates seamlessly with [vee-validate](https://vee-validate.logaretm.com/) and [Zod](https://zod.dev/) schemas. Use `useField()` to get reactive `value` and `errorMessage` refs, then bind them to the input and `CoarFormField` respectively.

::: tip Other validation libraries
`CoarFormField` is library-agnostic — it just takes an `error` string. Any validation approach works: vee-validate, vuelidate, or plain computed properties.
:::

## Standalone Form Controls

Form controls work without `CoarFormField` when no label or validation is needed — inline search inputs, table checkboxes, toolbar buttons.

```vue
<!-- No label needed -->
<CoarTextInput v-model="search" placeholder="Search..." />

<!-- Inline checkbox with its own label -->
<CoarCheckbox v-model="agree" label="I agree" />
```

## Accessibility

`CoarFormField` generates unique IDs automatically:

* **Label**: `<label for="...">` points to the input — clicking the label focuses the control
* **Error/Hint**: linked via `aria-describedby` — screen readers announce the message on focus
* **Required**: asterisk is `aria-hidden="true"` — use `required` on the input for semantics

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | `undefined` | Label text displayed above the input |
| `error` | `string` | `''` | Error message — overrides hint when set |
| `hint` | `string` | `''` | Hint text displayed below the input |
| `required` | `boolean` | `false` | Show required asterisk next to label |
| `disabled` | `boolean` | `false` | Disabled state — propagated to child inputs |
| `id` | `string` | auto | Explicit input ID (auto-generated if omitted) |

### Slots

| Slot | Description |
|------|-------------|
| `default` | The form control(s) to wrap |

---

---
url: /components/text-input.md
---
# Text Input

The go-to component for collecting short text from users -- names, emails, search queries, and more. It handles labels, validation, prefix/suffix decorations, and can even stretch into a textarea when you need longer content.

```ts
import { CoarTextInput, CoarFormField } from '@cocoar/vue-ui';
```

## Basic Usage

Wire up a text input with `v-model` and wrap it in a `CoarFormField` to add a label, placeholder, and optional hint to guide the user.

## Validation States

Add `required` to both `CoarFormField` (for the asterisk) and the input (for the HTML attribute). Pass an `error` string to `CoarFormField` to surface validation feedback beneath the input.

## Disabled & Readonly

Use `disabled` when the field should be completely non-interactive, and `readonly` when users should be able to see and copy the value but not change it.

## Prefix & Suffix

Prefix and suffix slots help users understand the expected format -- think currency symbols, units, or domain names.

## Clear Button

When `clearable` is enabled (the default), a small X button appears on hover or focus so users can quickly reset the field.

## Sizes

Four sizes let you match the input to its surroundings -- compact toolbars, standard forms, or spacious layouts.

## Multiline (Textarea)

Set `rows` to 2 or more and the input switches to a textarea, perfect for descriptions, notes, or any free-form content.

## Accessibility

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Tab` | Move focus to input |
| `Shift + Tab` | Move focus backward |
| `Escape` | Clear input (when clearable) |

::: info
Labels are automatically associated with their inputs. The required asterisk is announced by screen readers.
:::

### Screen Reader Support

* Label text announces on focus
* Required state properly communicated
* Error messages are linked via `aria-describedby`
* Hint text is accessible to assistive technology

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `v-model` | `string` | `''` | Current input value (two-way binding) |
| `placeholder` | `string` | `''` | Placeholder text when empty |
| `prefix` | `string` | `''` | Prefix text before the input |
| `suffix` | `string` | `''` | Suffix text after the input |
| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Input size |
| `rows` | `number` | `1` | Rows >= 2 enables textarea mode |
| `clearable` | `boolean` | `true` | Show clear button when input has value |
| `error` | `boolean` | `false` | Error state (auto-injected from `CoarFormField`) |
| `disabled` | `boolean` | `false` | Disable the input |
| `readonly` | `boolean` | `false` | Make read-only |
| `required` | `boolean` | `false` | HTML required attribute |

::: tip
Label, hint, and error are provided by [`CoarFormField`](/components/form-field). Wrap inputs in a `CoarFormField` to add these features.
:::

## i18n Keys

These keys can be translated via [`@cocoar/vue-localization`](/foundations/localization/translations).

| Key | Default (English) | Used as |
|-----|-------------------|---------|
| `coar.ui.textInput.clear` | `'Clear'` | Clear button `aria-label` |

---

---
url: /components/number-input.md
---
# Number Input

A purpose-built input for numeric values. It enforces min/max bounds, supports configurable step increments, and offers optional stepper buttons so users can nudge values up or down without typing.

```ts
import { CoarNumberInput } from '@cocoar/vue-ui';
```

## Basic Usage

Bind a number with `v-model`. The component handles parsing and formatting automatically -- users can only enter valid numeric characters.

## Min / Max / Step

Set boundaries with `min` and `max`, and control the increment size with `step`. Values are clamped on blur and via stepper controls.

## Stepper Buttons

Show `'increment'`, `'decrement'`, or `'both'` stepper buttons, or hide them with `'none'` (the default). Useful for quantity selectors, rating inputs, and anywhere precision matters.

## States

All the standard form states are supported: `disabled`, `readonly`, `required`, and `error`.

## Sizes

Four size variants that align with every other Cocoar form control, so your layouts stay consistent.

## Accessibility

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Tab` | Move focus to input |
| `Arrow Up` | Increment value by step |
| `Arrow Down` | Decrement value by step |

::: info
Stepper buttons are keyboard accessible. Min/max bounds are enforced on blur and via stepper controls.
:::

### Screen Reader Support

* Label text announces on focus
* Required state properly communicated
* Error messages linked via `aria-describedby`
* Value constraints announced through `aria-valuemin`, `aria-valuemax`

## i18n Keys

These keys can be translated via [`@cocoar/vue-localization`](/foundations/localization/translations).

| Key | Default (English) | Used as |
|-----|-------------------|---------|
| `coar.ui.numberInput.clear` | `'Clear'` | Clear button `aria-label` |
| `coar.ui.numberInput.decrease` | `'Decrease value'` | Decrement button `aria-label` |
| `coar.ui.numberInput.increase` | `'Increase value'` | Increment button `aria-label` |

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `v-model` | `number \| null` | `null` | Current numeric value |
| `placeholder` | `string` | `''` | Placeholder text |
| `min` | `number` | `undefined` | Minimum allowed value |
| `max` | `number` | `undefined` | Maximum allowed value |
| `step` | `number` | `1` | Step increment |
| `decimals` | `number` | `0` | Number of decimal places |
| `prefix` | `string` | `''` | Prefix text |
| `suffix` | `string` | `''` | Suffix text (e.g. '%', 'EUR') |
| `stepperButtons` | `'none' \| 'increment' \| 'decrement' \| 'both'` | `'none'` | Stepper button mode |
| `clearable` | `boolean` | `true` | Show clear button when input has value |
| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Input size |
| `disabled` | `boolean` | `false` | Disable the input |
| `readonly` | `boolean` | `false` | Make read-only |
| `required` | `boolean` | `false` | Mark as required |
| `error` | `boolean` | `false` | Error state (auto-injected from `CoarFormField`) |

---

---
url: /components/password-input.md
---
# Password Input

A text input tailored for passwords. It masks characters by default and provides a built-in eye toggle so users can temporarily reveal what they typed -- reducing frustration without sacrificing security.

```ts
import { CoarPasswordInput } from '@cocoar/vue-ui';
```

## Basic Usage

Works just like a text input, but the value is masked. Click the eye icon to peek at the password.

## With Validation

Wrap in `CoarFormField` to add labels, hints, and error messages. The component reads the error state from the field context automatically.

## States

Use `disabled` for locked accounts or `readonly` when displaying a masked placeholder that the user cannot modify.

## Sizes

Four sizes to keep password fields visually consistent with the rest of your form.

## Accessibility

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Tab` | Move focus to input / toggle button |
| `Enter` / `Space` | Toggle password visibility (on eye icon) |

::: info
The visibility toggle button has an accessible label that updates based on the current state ("Show password" / "Hide password").
:::

### Screen Reader Support

* Label text announces on focus
* Password visibility toggle state is communicated
* Error messages linked via `aria-describedby`
* Input type switches between `password` and `text`

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `v-model` | `string` | `''` | Password value |
| `placeholder` | `string` | `''` | Placeholder text |
| `error` | `boolean` | `false` | Error state (auto-injected from `CoarFormField`) |
| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Input size |
| `disabled` | `boolean` | `false` | Disable the input |
| `readonly` | `boolean` | `false` | Make read-only |
| `required` | `boolean` | `false` | Mark as required |
| `clearable` | `boolean` | `true` | Show clear button when input has value |

## i18n Keys

These keys can be translated via [`@cocoar/vue-localization`](/foundations/localization/translations).

| Key | Default (English) | Used as |
|-----|-------------------|---------|
| `coar.ui.passwordInput.showPassword` | `'Show password'` | Toggle visibility button `aria-label` |
| `coar.ui.passwordInput.hidePassword` | `'Hide password'` | Toggle visibility button `aria-label` (when visible) |
| `coar.ui.passwordInput.clear` | `'Clear'` | Clear button `aria-label` |

---

---
url: /components/otp-input.md
---
# OTP Input&#x20;

The N-cell input for verification codes — 2FA / TOTP from authenticator apps, SMS one-time passwords, claim codes, short PINs. Auto-advances as the user types, jumps back on Backspace, spreads pasted codes across cells, and fires a `complete` event the moment the last cell fills so you can submit without a button click.

```ts
import { CoarOtpInput, CoarFormField } from '@cocoar/vue-ui';
```

## Basic Usage

Wire it up with `v-model` and listen to `@complete` for auto-submit. The value is the assembled string — `"123456"` once all six cells are filled.

## Length

The default 6 cells match TOTP / SMS codes (RFC 6238). For shorter PINs or longer backup codes, override with the `length` prop.

## Type

`type="numeric"` (the default) rejects non-digits at the keystroke level and tells mobile browsers to open the numeric keyboard via `inputmode="numeric"`. `"alphanumeric"` accepts `[A-Za-z0-9]` for claim / recovery codes. `"text"` accepts any single character.

`mask` renders the cells as `<input type="password">` — the value is visually hidden while the keyboard interaction stays normal. Useful for PINs or sensitive codes in shared-screen contexts.

## Custom filtering: `transform` and `accept`

The built-in `type` classes (`numeric` / `alphanumeric` / `text`) cover the common cases, but real codes have quirks. Two hooks let you fine-tune per character without losing the rest of the input pipeline:

* **`transform(char) => string`** — runs FIRST. Rewrites a character before it's committed. Return a different char to substitute, return `''` to drop. Classic use: `c => c.toUpperCase()` so the user can type lowercase but the code stays canonical.
* **`accept(char) => boolean`** — runs AFTER `type` + `transform`. Reject characters the built-in class would otherwise allow. Classic use: block visually-ambiguous chars in printed claim codes so `O` (letter) and `0` (number) don't get confused.

Both hooks fire on every keystroke AND on every character of a pasted string — paste-spread runs through the same sanitizer, so a clipboard payload of `"abc123"` ends up as `"ABC123"` if `transform` uppercases.

## Validation

Drop the OTP input inside `CoarFormField` and the error state flows in automatically — the field's red ring + error message work the same as any other input. The `@complete` event is your "user finished typing" signal; verify against your backend and surface the result via `error`.

## Sizes

Four sizes match the rest of the form-input family (`CoarTextInput`, `CoarNumberInput`, etc.) — `xs` / `s` / `m` (default) / `l`. Cell width tracks the size token, so the OTP input lines up vertically with neighbouring inputs in a form.

## Behavior

| Interaction | Result |
|---|---|
| Type a character in cell `i` | Cell fills, focus auto-advances to `i + 1`. |
| Backspace on a filled cell | Clears the cell (stays put). |
| Backspace on an empty cell | Jumps to `i − 1` and clears it. |
| Delete on a filled cell | Clears the cell (stays put). |
| Arrow Left / Right | Moves focus between cells. |
| Home / End | First / last cell. |
| Type into a filled cell | Replaces its content (selection ensures overwrite). |
| Paste `"123456"` in cell 0 | Spreads across cells 0–5. Strips chars that don't match `type`. |
| Paste a 6-char code in cell 2 | Spreads from cell 2 onward, stopping at the last cell. |
| All cells filled | Fires `@complete` with the assembled string. |
| Tab | Moves focus *out* of the group from any cell — the entire OTP input is one tab-stop in practice. |

### Mobile SMS autofill

The first cell carries `autocomplete="one-time-code"` by default, so iOS and Android offer the SMS autofill chip when a verification text arrives. Override via the `autocomplete` prop if your app uses a different signal (`autocomplete="off"` to opt out entirely).

## API

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `modelValue` (`v-model`) | `string` | `''` | The assembled code. Partial fills work — `"12"` means cells 0–1 are filled, the rest empty. |
| `length` | `number` | `6` | Number of cells. |
| `type` | `'numeric' \| 'alphanumeric' \| 'text'` | `'numeric'` | Character class accepted per cell. |
| `mask` | `boolean` | `false` | Render cells as `type="password"`. |
| `autoFocus` | `boolean` | `false` | Focus the first cell on mount. |
| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Cell size — matches the form-input family. |
| `disabled` | `boolean` | `false` | Disable all cells. |
| `readonly` | `boolean` | `false` | All cells read-only. |
| `required` | `boolean` | `false` | Marks the group as required (picked up by `CoarFormField`). |
| `error` | `boolean` | `false` | Error state. Auto-injected from `CoarFormField`. |
| `placeholder` | `string` | `''` | Single-char placeholder shown in empty cells. |
| `id` | `string` | *auto* | HTML `id` for the first cell (and aria reference target). |
| `name` | `string` | `''` | HTML `name` prefix — each cell gets `${name}-${i}`. |
| `autocomplete` | `string` | `'one-time-code'` | First cell's `autocomplete` value. |
| `transform` | `(char: string) => string` | *none* | Rewrite a character before commit. Return `''` to drop. Runs before `type` + `accept`. |
| `accept` | `(char: string) => boolean` | *none* | Per-character accept predicate ANDed with `type`. Return `false` to reject. |

### Events

| Event | Payload | Notes |
|---|---|---|
| `update:modelValue` | `string` | Standard `v-model` emit. |
| `complete` | `string` | All cells filled — assembled string. Wire to your verify call. |
| `focused` | `FocusEvent` | A cell gained focus. |
| `blurred` | `FocusEvent` | A cell lost focus. |

## Accessibility

* The component is a `role="group"` with `aria-label="Verification code, N digits"`.
* Each cell is a real `<input>` with `aria-label="Digit i of N"` so screen readers announce position.
* `aria-invalid` propagates to every cell when the error state is set.
* Cell focus is keyboard-driven (Tab into the first cell, arrows / auto-advance inside, Tab out at any cell).
* Mobile screen readers respect the per-cell input semantics — the SMS-autofill chip on iOS Safari also targets the first cell correctly.

---

---
url: /components/select.md
---
# Select

Select components for single and multiple value selection. Choose between Single Select, Multi Select, or Tag Select variants.

```ts
import { CoarSelect, CoarMultiSelect, CoarTagSelect } from '@cocoar/vue-ui';
import type { CoarSelectOption } from '@cocoar/vue-ui';
```

## Single Select

Select a single option from a dropdown list. Toggle props to explore all options.

## Multi Select

Select multiple values with checkmarks. Toggle props to explore options.

## Tag Select

Select multiple values as removable tags. Search is always active — type to filter or create new tags.

## Options Format

Options must follow the `CoarSelectOption<T>` interface:

```ts
interface CoarSelectOption<T> {
  value: T;
  label: string;
  disabled?: boolean;
  group?: string;
  icon?: string;
}

const options: CoarSelectOption<string>[] = [
  { value: 'apple', label: 'Apple', group: 'Fruits' },
  { value: 'banana', label: 'Banana', group: 'Fruits', disabled: true },
  { value: 'carrot', label: 'Carrot', group: 'Vegetables' },
];
```

## Sorting

Control the order of groups and options via `sortGroups` and `sortOptions`. Both accept preset strings or a custom comparator function.

* `sortOptions` works **with and without groups** — it sorts all options, or within each group respectively
* `sortGroups` only applies when options have a `group` property
* `'none'` preserves the order as passed — giving you full control from the consumer side
* Pass a custom comparator `(a, b) => number` for special sorting (e.g. by priority, numeric values)

```ts
import type { CoarSelectSortGroups, CoarSelectSortOptions } from '@cocoar/vue-ui';
```

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `v-model` | `T \| null` | `null` | Selected value (the option's `value` field) |
| `options` | `CoarSelectOption<T>[]` | `[]` | Array of `{ value, label }` option objects |
| `placeholder` | `string` | `''` | Placeholder when empty |
| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Input size |
| `searchable` | `boolean` | `false` | Enable inline search to filter options by typing |
| `clearable` | `boolean` | `false` | Show a clear button when a value is selected |
| `disabled` | `boolean` | `false` | Disable the select |
| `readonly` | `boolean` | `false` | Read-only state |
| `error` | `boolean` | `false` | Error state (auto-injected from `CoarFormField`) |
| `appearance` | `'outline' \| 'inline'` | `'outline'` | Visual appearance variant |
| `compareWith` | `(a: T, b: T) => boolean` | `===` | Custom comparison function for matching values |
| `dropdownPosition` | `'auto' \| 'top' \| 'bottom'` | `'auto'` | Dropdown position preference |
| `sortGroups` | `'asc' \| 'desc' \| 'none' \| (a, b) => number` | `'asc'` | Sort order for groups |
| `sortOptions` | `'asc' \| 'desc' \| 'none' \| (a, b) => number` | `'none'` | Sort order for options (within each group, or all if ungrouped) |

## i18n Keys

These keys can be translated via [`@cocoar/vue-localization`](/foundations/localization/translations).

These keys apply to `CoarSelect`, `CoarMultiSelect`, and `CoarTagSelect`.

| Key | Default (English) | Used as |
|-----|-------------------|---------|
| `coar.ui.select.clearSelection` | `'Clear selection'` | Clear button `aria-label` |
| `coar.ui.select.options` | `'Options'` | Options listbox `aria-label` |
| `coar.ui.select.noResults` | `'No results found'` | Empty state text when search returns no matches |
| `coar.ui.select.noOptions` | `'No options available'` | Empty state text when options list is empty |
| `coar.ui.tagSelect.remove` | `'Remove'` | Tag remove button `aria-label` |
| `coar.ui.tagSelect.options` | `'Options'` | Tag select listbox `aria-label` |

---

---
url: /components/listbox.md
---
# Listbox

A single-column list of selectable items with grouping, search, custom renderers, and multi-select highlighting. Use it as a form control (v-model of highlighted values), as a display-only roster, or as the foundation for [`CoarDualListbox`](./dual-listbox).

```ts
import { CoarListbox } from '@cocoar/vue-ui';
import type { CoarListboxOption } from '@cocoar/vue-ui';
```

## Basic

Multi-select highlight via click, `Ctrl+Click`, `Shift+Click`, and keyboard (arrows, `Space`, `Ctrl+A`). Double-click (or `Enter`) emits `item-activate` — wire this up to move items, open a detail view, etc.

## Display only

Set `display-only` to render a static roster — for example, "current group members". Clicks don't highlight, keyboard navigation is off, ARIA role drops to `list`, but search and grouping still work.

## Grouped

Items with a `group` field render under sticky headings. Group order is controlled by `sortGroups` ('asc' by default); item order within a group by `sortOptions` ('none' by default).

## Custom item components

For per-kind polymorphic rendering, register Vue components via `itemComponents`. The component resolution order is:

1. `itemComponents[item.kind]` if provided
2. `#item-<kind>` slot if present
3. `#item` slot if present
4. Built-in `icon + label + subtitle` layout

Each renderer receives `{ item, highlighted, selectable, side }` as props / slot scope. Set `kindBy` if `kind` lives on a different field than `item.kind`.

```ts
// UserItem.vue
const props = defineProps<{
  item: CoarListboxOption<UserRow>
  highlighted: boolean
  selectable: boolean
}>()
```

## Flexible search

Three levels of control, from simplest to most powerful — set only one:

```ts
// (a) Extend the built-in search to additional fields
searchFields: ['label', 'subtitle', 'group']

// (b) Provide the searchable text for each item
searchBy: (item) => `${item.label} ${item.value.email}`

// (c) Full control — arbitrary matching logic
filterWith: (item, query) => fuse.search(query).includes(item)
```

`filterWith` wins over `searchBy` wins over `searchFields`. Items can also carry a `searchText` field to override the default per-item.

## Item API (inline actions)

Every item renderer — whether a component from `itemComponents` or the `#item` / `#item-<kind>` slot — receives a scoped `api` handle. Use it to trigger listbox behavior from inside the row: remove it from a trash button, toggle highlight from a checkbox, fire a custom action from a context menu.

The listbox emits the resulting event — `item-remove` or `item-action` with the name + payload — so the parent stays in charge of the data:

```ts
interface CoarListboxItemApi<T> {
  item: CoarListboxOption<T>
  highlighted: boolean
  highlight(): void
  unhighlight(): void
  toggleHighlight(): void
  activate(): void                              // emits `item-activate`
  remove(): void                                // emits `item-remove` → parent updates `options`
  action(name: string, payload?: unknown): void // emits `item-action`
}
```

Inside custom components:

```vue
<script setup lang="ts">
import type { CoarListboxOption, CoarListboxItemApi } from '@cocoar/vue-ui'
defineProps<{
  item: CoarListboxOption<Row>
  api: CoarListboxItemApi<Row>
}>()
</script>

<template>
  <div class="row">
    <span>{{ item.label }}</span>
    <button @click.stop="api.remove()">×</button>
  </div>
</template>
```

Use `@click.stop` on inline buttons so the click doesn't also trigger the row's click/highlight handler.

## Drag & drop between lists

Set `draggable` on lists items can leave, `droppable` on lists items can enter, and a shared `drag-group` name to link them. Use it for any layout — source/destination (one-way) or bidirectional peers (this Kanban-style example uses three lists):

* **Events:** the source emits `items-remove`, the target emits `items-add`. The parent updates each list's `options` accordingly. Both fire synchronously on drop — no flicker.
* **Selection-aware:** if the dragged item is part of the multi-highlight, the whole highlighted set is carried along.
* **Groups:** lists with different `drag-group` values reject each other's drops. No group at all = self-drops only.
* For a built-in two-column experience, see [`CoarDualListbox`'s `drag-drop` prop](./dual-listbox#drag-drop).
* The drag logic comes from the [`useDragDrop`](./drag-drop) composable — use it directly if you need the same semantics in a custom component that isn't a listbox.

### Directional flows

When `drag-group` is too coarse — e.g. *box1 can go to box2 or box3, but nothing can return to box1* — each list gets a stable `drag-id` and the targets whitelist sources via `drag-accept`:

```vue
<CoarListbox drag-id="box1" draggable drag-group="flow" />                  <!-- source only -->
<CoarListbox drag-id="box2" draggable droppable drag-group="flow"
             :drag-accept="['box1']" />                                      <!-- only box1 → box2 -->
<CoarListbox drag-id="box3" droppable drag-group="flow"
             :drag-accept="['box1', 'box2']" />                              <!-- box1 + box2 → box3, dead-end -->
```

### Per-item validation

`can-drag` controls which items can leave the source (applies per-item, also trims the multi-highlight payload). `can-drop` validates incoming drops at runtime — the cursor shows "not allowed" when it refuses:

```vue
<!-- Only users can be dragged; groups stay put. -->
<CoarListbox :options="principals" draggable :can-drag="p => p.value.kind === 'user'" />

<!-- Admin group caps at 5 members, no bulk drops exceeding that. -->
<CoarListbox
  v-model="admins"
  :options="admins"
  droppable
  :can-drop="p => admins.length + p.items.length <= 5"
/>
```

## Virtual scrolling

For very long lists (thousands of items), enable `virtual` — only the rows in/near the viewport are rendered. Group headings scroll naturally in this mode (they are not sticky; the non-virtual mode keeps sticky headings). Search, keyboard nav, highlight, drag & drop, and custom item components all still work.

```vue
<CoarListbox
  :options="tenThousand"
  virtual
  :item-height="32"
  :group-heading-height="28"
  :overscan="5"
/>
```

All items must have the same height (`item-height`). Headings can use a different height (`group-heading-height`). For a concrete example with 10k entries see the [DualListbox virtual demo](./dual-listbox#virtual-scrolling-large-datasets).

Virtual scrolling is built on top of the exported [`useVirtualList`](./virtual-list) composable — use it standalone in your own components.

## Options Format

```ts
interface CoarListboxOption<T> {
  value: T;
  label: string;          // required — used for default rendering, search, a11y
  kind?: string;          // drives itemComponents / #item-<kind>
  group?: string;
  icon?: string;          // default renderer only
  subtitle?: string;      // default renderer only
  tooltip?: string;       // native `title` attribute
  disabled?: boolean;
  searchText?: string;    // per-item override for default search
}
```

## Slots

| Slot | Scope | Purpose |
|------|-------|---------|
| `header` | `{ label, count, total }` | Replace the entire header row |
| `search` | `{ query, update }` | Replace the search input |
| `item` | `{ item, highlighted, selectable, side?, api }` | Render every item. `api` exposes `remove()`, `toggleHighlight()`, `activate()`, `action(name, payload?)` |
| `item-<kind>` | `{ item, highlighted, selectable, side?, api }` | Render items whose `kind` matches |
| `group-heading` | `{ group, items }` | Replace the group heading |
| `empty` | — | Replace the empty state |
| `footer` | — | Add a footer below the list |

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `v-model` | `T[]` | `[]` | Currently highlighted values |
| `options` | `CoarListboxOption<T>[]` | `[]` | Items to display |
| `label` | `string` | `''` | Header label |
| `showCount` | `boolean` | `false` | Show a count badge in the header |
| `showHeader` | `boolean` | *auto* | Override header visibility |
| `height` | `string` | *flex* | Fixed list height (e.g. `'280px'`); otherwise the list fills its parent |
| `displayOnly` | `boolean` | `false` | Disable click/keyboard interaction — render a static list. Downgrades ARIA role to `list` |
| `disabled` | `boolean` | `false` | Dim and ignore input |
| `readonly` | `boolean` | `false` | Keep appearance but ignore input |
| `searchable` | `boolean` | `false` | Render a search input above the list |
| `searchPlaceholder` | `string` | `'Search…'` | Search input placeholder |
| `searchFields` | `('label' \| 'subtitle' \| 'group')[]` | `['label']` | Fields searched by default |
| `searchBy` | `(item) => string` | — | Override the searchable text per item |
| `filterWith` | `(item, query) => boolean` | — | Full control over matching |
| `sortGroups` | `'asc' \| 'desc' \| 'none' \| (a,b) => number` | `'asc'` | Group order |
| `sortOptions` | `'asc' \| 'desc' \| 'none' \| (a,b) => number` | `'none'` | Item order |
| `hideGroupHeadings` | `boolean` | `false` | Omit group labels even when items have a `group` |
| `itemComponents` | `Record<string, Component>` | `{}` | Map of `kind` → renderer component |
| `kindBy` | `(item) => string` | `(i) => i.kind ?? ''` | Derive kind from a custom field |
| `compareWith` | `(a: T, b: T) => boolean` | `===` | Equality for values |
| `emptyText` | `string` | `'No items'` | Fallback empty state text |
| `draggable` | `boolean` | `false` | Allow items to be dragged out of this list |
| `droppable` | `boolean` | `false` | Accept drops from compatible listboxes |
| `dragGroup` | `string` | — | Shared name linking lists that can exchange items |
| `dragId` | `string` | auto | Stable identifier — pair with other lists' `dragAccept` for directional flow |
| `dragAccept` | `string[]` | — | Whitelist of source `dragId`s this list accepts. Unset = accept any source in the same `dragGroup`; empty array = accept nothing |
| `canDrag` | `(item) => boolean` | — | Per-item source permission. Items returning `false` are not draggable |
| `canDrop` | `(payload) => boolean` | — | Runtime drop validation; `payload` is `{ items, fromId, fromGroup, fromSelf }` |
| `virtual` | `boolean` | `false` | Enable virtual scrolling — only rows in/near the viewport are rendered |
| `itemHeight` | `number` | `32` | Row height in pixels (used only when `virtual` is on) |
| `groupHeadingHeight` | `number` | `28` | Heading height when `virtual` is on |
| `overscan` | `number` | `5` | Extra rows rendered above/below the viewport |

### Events

| Event | Payload | When |
|-------|---------|------|
| `update:modelValue` | `T[]` | Highlight changed |
| `item-click` | `{ item, event }` | Single click on an item |
| `item-dblclick` | `{ item, event }` | Double click on an item |
| `item-activate` | `{ item }` | Double-click or `Enter` on a highlighted item — idiomatic "move this / open this" hook |
| `item-remove` | `{ item }` | A custom renderer called `api.remove()` — parent should drop the item from `options` |
| `item-action` | `{ item, name, payload? }` | A custom renderer called `api.action(name, payload?)` — escape hatch for any custom inline operation |
| `drag-start` | `{ items }` | Drag has started on this list. `items` includes the whole highlighted set when the grabbed item was part of it, else just the one item |
| `drag-end` | `{ items, dropped }` | Drag ended — `dropped: true` if a target consumed it |
| `items-add` | `{ items, insertIndex, fromGroup, fromSelf }` | Drop accepted here. Parent should add `items` to its source of truth. `insertIndex` is the position of the item dropped on (or `null` if dropped in empty space) |
| `items-remove` | `{ items, toGroup }` | The dragged items were consumed by a target. Parent should remove them from this list's source of truth |

### Exposed methods

Accessible via template ref:

```ts
const box = useTemplateRef<CoarListboxExposed<string>>('box')
box.value?.clearHighlight()
box.value?.highlightAll()
box.value?.focus()
box.value?.clearSearch()
box.value?.visibleItems // current filtered + sorted items
```

---

---
url: /components/dual-listbox.md
---
# Dual Listbox

Two [`CoarListbox`](./listbox) columns side-by-side with move buttons — the classic pattern for moving items between "available" and "selected" sets. All the search, grouping, and custom-render features of `CoarListbox` carry over automatically.

```ts
import { CoarDualListbox } from '@cocoar/vue-ui';
import type { CoarListboxOption } from '@cocoar/vue-ui';
```

## Basic

`v-model` holds the currently-selected values (right column). Everything else from `options` lives in the left column.

## Grouped

Group headings appear in both columns. Search and sorting apply per column.

## Custom item components

Pass `itemComponents` and they're used on both sides. The component receives a `side` prop (`'available' | 'selected'`) so the same renderer can adapt per column if needed.

## Inline remove button (right side)

A common pattern: render an × button inside each selected item, and clicking it moves the user back to the available column. Since the right column is just `options ∩ modelValue`, "moving back" is simply *dropping the id from v-model* — the item re-appears on the left automatically.

The renderer uses the `side` prop to show the × only on the selected side; clicking it calls `api.remove()`, which bubbles up as `item-remove` with `side: 'selected'`, and the parent filters v-model:

```vue
<!-- UserCard.vue -->
<button v-if="side === 'selected'" @click.stop="api.remove()">×</button>
```

```vue
<!-- Parent -->
<CoarDualListbox v-model="selected" :options="..." @item-remove="onRemove" />

<script setup lang="ts">
function onRemove({ item, side }) {
  if (side !== 'selected') return
  selected.value = selected.value.filter(u => u.id !== item.value.id)
}
</script>
```

See [`CoarListboxItemApi`](./listbox#item-api-inline-actions) for the full api surface.

## Drag & drop

Set the `drag-drop` prop and items become draggable between the two columns. A unique drag group is wired up internally so the two sides exchange items with each other but not with unrelated listboxes on the page.

Selection-aware: if the dragged item is part of a multi-highlight, the whole highlighted set moves at once.

For a standalone two-listbox setup (or three+ lists), see the same feature on [`CoarListbox`](./listbox#drag-drop-between-lists).

## Virtual scrolling (large datasets)

For directories with thousands of entries, enable `virtual` — only the rows in and around the viewport are rendered. Group headings scroll naturally in this mode (they are not sticky).

The demo below loads 10,000 synthetic principals (users, groups, service accounts) client-side. Scroll, search, highlight, drag, and the inline × all still work.

```vue
<CoarDualListbox
  v-model="assigned"
  :options="principals"
  virtual
  :item-height="44"
  :group-heading-height="28"
/>
```

* Set `item-height` to the pixel height of a row — must be fixed, but you can pick whatever matches your custom item component.
* `overscan` controls how many extra rows are rendered above/below the viewport (default 5). Raise it if you see blank flashes on fast scrolls.
* Virtual mode uses the [`useVirtualList`](./virtual-list) composable, which is also exported for your own components.

## Interaction

* **Click**: highlight a single item
* **Ctrl / ⌘ + Click**: add/remove from highlight
* **Shift + Click**: range select
* **Double-click / Enter**: move that single item across
* **→ / ← buttons**: move all currently-highlighted items
* **≫ / ≪ buttons**: move all currently-visible items (respects the column's search filter). Hide with `hideMoveAll`.

## Slots

Shared slots apply to both columns; side-specific slots override only one side.

| Slot | Applies to | Scope |
|------|------------|-------|
| `item` | both | `{ item, highlighted, selectable, side }` |
| `item-<kind>` | both | `{ item, highlighted, selectable, side }` |
| `group-heading` | both | `{ group, items }` |
| `header-available` | left | `{ label, count, total }` |
| `header-selected` | right | `{ label, count, total }` |
| `empty-available` | left | — |
| `empty-selected` | right | — |
| `actions` | center | `{ moveRight, moveLeft, moveAllRight, moveAllLeft, canMoveRight, canMoveLeft, canMoveAllRight, canMoveAllLeft }` |

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `v-model` | `T[]` | `[]` | Selected values (right column contents, in order) |
| `options` | `CoarListboxOption<T>[]` | `[]` | All items — split into columns by `modelValue` membership |
| `availableLabel` | `string` | `'Available'` | Left column header |
| `selectedLabel` | `string` | `'Selected'` | Right column header |
| `height` | `string` | *flex* | Fixed list height for both columns |
| `disabled` / `readonly` | `boolean` | `false` | Standard form states |
| `hideSearch` | `boolean` | `false` | Hide the search input in both columns |
| `searchPlaceholder` | `string` | `'Search…'` | Placeholder for both search inputs |
| `searchFields` / `searchBy` / `filterWith` | — | — | Search config, forwarded to both columns — see [Listbox docs](./listbox#flexible-search) |
| `sortGroups` / `sortOptions` / `hideGroupHeadings` | — | — | Grouping / sorting config, forwarded to both columns |
| `itemComponents` / `kindBy` | — | — | Custom rendering, forwarded to both columns |
| `compareWith` | `(a, b) => boolean` | `===` | Value equality |
| `hideMoveAll` | `boolean` | `false` | Hide the ≫ / ≪ buttons |
| `hideCounts` | `boolean` | `false` | Hide count badges in headers |
| `emptyAvailable` | `string` | `'No items'` | Empty state for left column |
| `emptySelected` | `string` | `'None selected'` | Empty state for right column |
| `sortSelectedBySource` | `boolean` | `false` | When `true`, the right column is re-sorted by the order of items in `options` after every move. Default keeps the order in which the user moved items across |
| `dragDrop` | `boolean` | `false` | Enable drag-and-drop between the two columns |
| `canDrag` | `(item) => boolean` | — | Per-item source permission, applied to both columns. See [Listbox docs](./listbox#per-item-validation) |
| `canDrop` | `(payload) => boolean` | — | Runtime drop validation, applied to both columns |
| `virtual` | `boolean` | `false` | Enable virtual scrolling — render only rows in/near the viewport |
| `itemHeight` | `number` | `32` | Row height in pixels (used only when `virtual` is on) |
| `groupHeadingHeight` | `number` | `28` | Heading height when `virtual` is on |
| `overscan` | `number` | `5` | Extra rows rendered above/below the viewport |

### Events

| Event | Payload | When |
|-------|---------|------|
| `update:modelValue` | `T[]` | Selection changed |
| `move` | `{ direction: 'right' \| 'left', values: T[] }` | Any move action (button or double-click) |
| `item-remove` | `{ item, side }` | A custom renderer called `api.remove()` in either column |
| `item-action` | `{ item, name, payload?, side }` | A custom renderer called `api.action(...)` in either column |

### Exposed methods

```ts
const dual = useTemplateRef('dual')
dual.value?.moveRight()
dual.value?.moveLeft()
dual.value?.moveAllRight()
dual.value?.moveAllLeft()
dual.value?.clearHighlight()
```

---

---
url: /components/checkbox.md
---
# Checkbox

Checkboxes let users pick one or more options from a list, or flip a single boolean on or off. Reach for a checkbox when the choice does not take effect until the user explicitly submits -- for instant toggles, consider a [Switch](/components/switch) instead.

```ts
import { CoarCheckbox } from '@cocoar/vue-ui';
```

## Basic Usage

Bind a boolean with `v-model` and provide a `label`. That is all you need for a working checkbox.

## States

Checkboxes support `required`, `disabled`, and `error` states, giving you full control over form validation flows.

## Indeterminate

The indeterminate state shows a dash instead of a checkmark -- handy for "select all" controls where only some children are checked.

## Sizes

Four sizes to match different information densities, from compact data tables to spacious settings pages.

## Hint Text

Wrap in `CoarFormField` with a `hint` prop to give users extra context without cluttering the label itself.

## Label Position

Place the label before or after the checkbox with the `labelPosition` prop. Defaults to `'after'`.

## Without Label

For table rows or tight custom layouts you can omit the visible label -- just make sure to pass an `aria-label` so the checkbox remains accessible.

## Accessibility

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Tab` | Move focus to checkbox |
| `Space` | Toggle checked state |

::: info
The indeterminate state is visual only. Clicking an indeterminate checkbox toggles it to checked. Always provide `aria-label` when no visible label is used.
:::

### Screen Reader Support

* Label text or `aria-label` announces on focus
* Checked / unchecked state communicated
* Required and error states announced
* Hint text accessible via `aria-describedby`

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `v-model` | `boolean` | `false` | Checked state |
| `label` | `string` | `''` | Label text |
| `error` | `boolean` | `false` | Error state (auto-injected from `CoarFormField`) |
| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Checkbox size |
| `labelPosition` | `'before' \| 'after'` | `'after'` | Label position relative to the checkbox |
| `indeterminate` | `boolean` | `false` | Show indeterminate (dash) state |
| `disabled` | `boolean` | `false` | Disable the checkbox |
| `required` | `boolean` | `false` | Mark as required |

---

---
url: /components/radio-group.md
---
# Radio Group

When users must pick exactly one option from a small set of mutually exclusive choices, a radio group is the right tool. Each option is visible at a glance, unlike a select dropdown, which makes radios ideal when the list is short (roughly 2--5 items).

```ts
import { CoarRadioGroup, CoarRadioButton } from '@cocoar/vue-ui';
```

## Horizontal

Switch to `orientation="horizontal"` when labels are short and there are only a few choices.

## Vertical (Default)

The default vertical layout stacks options for easy scanning -- works well with longer labels or more than 4 choices.

## States

Mark the group as `required` to show an asterisk. Wrap in `CoarFormField` to display validation messages.

## Label Position

Place the label text before or after the radio control with the `labelPosition` prop on the group. All radio buttons inherit the setting.

## Disabled Buttons

Individual `CoarRadioButton` options can be disabled while the rest of the group stays interactive -- useful for temporarily unavailable plans or tiers.

## Sizes

Three sizes that stay in step with every other Cocoar form control.

## Accessibility

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Tab` | Move focus into / out of radio group |
| `Arrow Left` / `Arrow Up` | Select previous option |
| `Arrow Right` / `Arrow Down` | Select next option |
| `Space` | Select focused option |

::: info
Only one radio button in a group receives tab focus. Arrow keys move selection between options within the group.
:::

### Screen Reader Support

* Group label announced when entering the group
* Each option's label announces on focus
* Selected state properly communicated
* Disabled options announced as unavailable

## API

### CoarRadioGroup Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `v-model` | `unknown` | `undefined` | Currently selected value |
| `name` | `string` | — | **Required.** HTML name for the radio inputs |
| `label` | `string` | `''` | Group accessible label |
| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | Layout direction |
| `size` | `'s' \| 'm' \| 'l'` | `'m'` | Radio button size |
| `labelPosition` | `'before' \| 'after'` | `'after'` | Label position for all radio buttons |
| `disabled` | `boolean` | `false` | Disable all radio buttons |
| `required` | `boolean` | `false` | Mark as required |
| `error` | `boolean` | `false` | Error state (auto-injected from `CoarFormField`) |

### CoarRadioButton Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `unknown` | -- | Value emitted when selected |
| `disabled` | `boolean` | `false` | Disable this option |

---

---
url: /components/switch.md
---
# Switch

A toggle for boolean settings that take effect immediately -- think "Enable notifications" or "Dark mode". Unlike a [Checkbox](/components/checkbox), a switch signals instant action rather than a deferred choice that requires a submit button.

```ts
import { CoarSwitch } from '@cocoar/vue-ui';
```

## Basic Usage

Bind a boolean with `v-model` and provide a `label`. The switch flips on click or keyboard activation.

## With Hint Text

Wrap in `CoarFormField` with a `hint` prop to add a brief explanation, helping users understand the consequence of toggling.

## States

Supports `disabled` (both on and off), `required`, and `error` states for complete form validation coverage.

## Sizes

Three sizes so the switch fits naturally alongside other controls at any density.

## Label Position

Place the label before or after the switch with the `labelPosition` prop. Defaults to `'after'`.

## Settings Panel Example

Switches shine in settings panels where each row controls an independent feature. Here is a typical layout pattern.

## Accessibility

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Tab` | Move focus to switch |
| `Space` | Toggle on/off state |
| `Enter` | Toggle on/off state |

::: info
Switches use `role="switch"` with `aria-checked` to properly communicate state to screen readers.
:::

### Screen Reader Support

* Label text announces on focus
* On/off state properly communicated via `aria-checked`
* Hint text accessible via `aria-describedby`
* Error messages announced when present

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `v-model` | `boolean` | `false` | Switch on/off state |
| `label` | `string` | `''` | Label text |
| `error` | `boolean` | `false` | Error state (auto-injected from `CoarFormField`) |
| `size` | `'s' \| 'm' \| 'l'` | `'m'` | Switch size |
| `disabled` | `boolean` | `false` | Disable the switch |
| `labelPosition` | `'before' \| 'after'` | `'after'` | Label position relative to the switch |

---

---
url: /components/date-picker.md
---
# Date Picker

A calendar-backed date picker that returns a `Temporal.PlainDate` -- a date without time or timezone. Perfect for birthdays, deadlines, due dates, and any scenario where "which day" is all that matters.

```ts
import { CoarPlainDatePicker } from '@cocoar/vue-ui';
```

## Basic Usage

Click the input to open a calendar dropdown. The selected value is a proper `Temporal.PlainDate`, so date math and formatting are straightforward.

## Required & Error States

Combine `required` and `error` props for form validation. The required asterisk and error message integrate with the same patterns as every other Cocoar input.

## Disabled & Readonly

`disabled` greys out the entire picker; `readonly` lets users see the selected date but prevents changes.

## Date Range (Manual)

For start/end date pairs, use two pickers and pass the start date as `:min` on the end picker. This prevents users from selecting an end date before the start.

## Sizes

Four sizes to stay consistent with other form controls across your layout.

::: info
**Temporal.PlainDate:** This component uses the TC39 Temporal API (`@js-temporal/polyfill`). PlainDate represents a calendar date without time or timezone -- no more wrestling with midnight UTC offsets.
:::

## Accessibility

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Tab` | Move focus to input / calendar |
| `Enter` | Open calendar / select date |
| `Escape` | Close calendar dropdown |
| `Arrow Keys` | Navigate within the calendar |

### Screen Reader Support

* Label text announces on focus
* Selected date is read aloud
* Calendar navigation is keyboard accessible
* Required and error states announced

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `v-model` | `Temporal.PlainDate \| null` | `null` | Selected date |
| `label` | `string` | `''` | Label text |
| `placeholder` | `string` | `''` | Placeholder text |
| `min` | `Temporal.PlainDate` | `undefined` | Minimum selectable date |
| `max` | `Temporal.PlainDate` | `undefined` | Maximum selectable date |
| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Input size |
| `disabled` | `boolean` | `false` | Disable the picker |
| `readonly` | `boolean` | `false` | Make read-only |
| `required` | `boolean` | `false` | Mark as required |
| `error` | `string` | `''` | Error message |

## i18n Keys

These keys can be translated via [`@cocoar/vue-localization`](/foundations/localization/translations).

| Key | Default (English) | Used as |
|-----|-------------------|---------|
| `coar.ui.datePicker.previousYear` | `'Previous year'` | Previous year button `aria-label` |
| `coar.ui.datePicker.nextYear` | `'Next year'` | Next year button `aria-label` |
| `coar.ui.datePicker.jumpToToday` | `'Jump to today\'s month'` | Scroll-to-today button `aria-label` |
| `coar.ui.datePicker.months` | `'Months'` | Month grid `aria-label` |
| `coar.ui.datePicker.dialog` | `'Date picker'` | Overlay dialog `aria-label` |
| `coar.ui.datePicker.clearDate` | `'Clear date'` | Clear button `aria-label` |
| `coar.ui.datePicker.openPicker` | `'Open picker'` | Calendar button `aria-label` |

---

---
url: /components/date-time-picker.md
---
# DateTime Picker

Combines a calendar date picker with a time input and returns a `Temporal.PlainDateTime` -- a date and time without any timezone attached. Use this when the timezone is implicit (the user's local time) or irrelevant (an alarm, a reminder). If you need timezone awareness, reach for the [Zoned DateTime Picker](/components/zoned-date-time-picker) instead.

```ts
import { CoarPlainDateTimePicker } from '@cocoar/vue-ui';
```

## Basic Usage

Select a date from the calendar, then adjust the time. The bound value is a `Temporal.PlainDateTime` you can format, compare, or serialize as needed.

## States

Supports `required`, `error`, `disabled`, and `readonly` -- the same set of states you will find on every Cocoar form control.

## Sizes

Four sizes to match surrounding inputs and keep your forms visually balanced.

::: info
**PlainDateTime vs ZonedDateTime:** Choose `PlainDateTime` when the timezone is always the user's local time or when it simply does not matter (alarm clocks, recurring events). Choose `ZonedDateTime` when you need to pin a specific instant in time and derive UTC for storage or sharing across timezones.
:::

## Accessibility

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Tab` | Move focus between date and time inputs |
| `Enter` | Open calendar / confirm selection |
| `Escape` | Close calendar dropdown |
| `Arrow Keys` | Navigate within the calendar |

### Screen Reader Support

* Label text announces on focus
* Date and time portions are independently accessible
* Required and error states announced
* Calendar navigation is keyboard accessible

## i18n Keys

These keys can be translated via [`@cocoar/vue-localization`](/foundations/localization/translations).

| Key | Default (English) | Used as |
|-----|-------------------|---------|
| `coar.ui.dateTimePicker.dialog` | `'Date time picker'` | Overlay dialog `aria-label` |
| `coar.ui.dateTimePicker.clearDate` | `'Clear date'` | Clear button `aria-label` |
| `coar.ui.dateTimePicker.openPicker` | `'Open picker'` | Calendar button `aria-label` |
| `coar.ui.datePicker.jumpToToday` | `'Jump to today\'s month'` | Scroll-to-today button `aria-label` |
| `coar.ui.datePicker.previousYear` | `'Previous year'` | Previous year button `aria-label` |
| `coar.ui.datePicker.nextYear` | `'Next year'` | Next year button `aria-label` |
| `coar.ui.datePicker.months` | `'Months'` | Month grid `aria-label` |
| `coar.ui.timePicker.increaseHours` | `'Increase hours'` | Hours increment button `aria-label` |
| `coar.ui.timePicker.decreaseHours` | `'Decrease hours'` | Hours decrement button `aria-label` |
| `coar.ui.timePicker.hours` | `'Hours'` | Hours spinbutton `aria-label` |
| `coar.ui.timePicker.increaseMinutes` | `'Increase minutes'` | Minutes increment button `aria-label` |
| `coar.ui.timePicker.decreaseMinutes` | `'Decrease minutes'` | Minutes decrement button `aria-label` |
| `coar.ui.timePicker.minutes` | `'Minutes'` | Minutes spinbutton `aria-label` |

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `v-model` | `Temporal.PlainDateTime \| null` | `null` | Selected date+time |
| `label` | `string` | `''` | Label text |
| `placeholder` | `string` | `''` | Placeholder text |
| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Input size |
| `disabled` | `boolean` | `false` | Disable the picker |
| `readonly` | `boolean` | `false` | Make read-only |
| `required` | `boolean` | `false` | Mark as required |
| `error` | `string` | `''` | Error message |

---

---
url: /components/zoned-date-time-picker.md
---
# Zoned DateTime Picker

The full-featured datetime picker for timezone-aware values. It captures a date, time, and IANA timezone as a single `Temporal.ZonedDateTime`, making it easy to derive UTC instants for storage while preserving the user's original intent.

```ts
import { CoarZonedDateTimePicker } from '@cocoar/vue-ui';
```

::: info
**Store intent, derive math.** Persist the user's chosen local time and timezone. You can always recalculate the UTC instant later -- and if DST rules change in the future, the recalculation will still be correct.
:::

## Basic Usage

The picker defaults to the user's system timezone. Select a date, adjust the time, and optionally change the timezone. The bound value carries all three pieces of information.

## Working with UTC

Converting to a UTC instant for API calls or database storage is a one-liner:

```ts
// Get UTC instant from ZonedDateTime
const utcInstant = value.value?.toInstant().toString();
// → "2024-03-15T14:30:00Z"

// Get ISO string with offset
const isoString = value.value?.toString();
// → "2024-03-15T15:30:00+01:00[Europe/Berlin]"
```

## States

All standard form states are supported: `required`, `error`, `disabled`, and `readonly`.

## Sizes

Four sizes that stay visually aligned with every other Cocoar input component.

## Accessibility

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Tab` | Move focus between date, time, and timezone inputs |
| `Enter` | Open calendar / confirm selection |
| `Escape` | Close calendar dropdown |
| `Arrow Keys` | Navigate within the calendar |

### Screen Reader Support

* Label text announces on focus
* Date, time, and timezone portions are independently accessible
* Selected timezone is announced
* Required and error states announced

## i18n Keys

These keys can be translated via [`@cocoar/vue-localization`](/foundations/localization/translations).

| Key | Default (English) | Used as |
|-----|-------------------|---------|
| `coar.ui.zonedDateTimePicker.dialog` | `'Date, time and timezone picker'` | Overlay dialog `aria-label` |
| `coar.ui.zonedDateTimePicker.clearValue` | `'Clear value'` | Clear button `aria-label` |
| `coar.ui.zonedDateTimePicker.openPicker` | `'Open date and time picker'` | Calendar button `aria-label` |
| `coar.ui.zonedDateTimePicker.timezoneIndicator` | `'Timezone: {tz}'` | Timezone indicator `aria-label` |
| `coar.ui.zonedDateTimePicker.clickToToggle` | `'Click to toggle.'` | Timezone indicator `aria-label` suffix |
| `coar.ui.zonedDateTimePicker.searchTimezone` | `'Search timezone...'` | Timezone search placeholder |
| `coar.ui.zonedDateTimePicker.closeTimezoneSearch` | `'Close timezone search'` | Close search button `aria-label` |
| `coar.ui.zonedDateTimePicker.displayTimezone` | `'Display Timezone'` | Display timezone section label |
| `coar.ui.zonedDateTimePicker.eventTimezone` | `'Event timezone'` | Footer placeholder text |
| `coar.ui.zonedDateTimePicker.cancelTimezoneEdit` | `'Cancel timezone edit'` | Cancel button `aria-label` |
| `coar.ui.zonedDateTimePicker.changeEventTimezone` | `'Change event timezone'` | Settings button `aria-label` |
| `coar.ui.datePicker.jumpToToday` | `'Jump to today\'s month'` | Scroll-to-today button `aria-label` |
| `coar.ui.datePicker.previousYear` | `'Previous year'` | Previous year button `aria-label` |
| `coar.ui.datePicker.nextYear` | `'Next year'` | Next year button `aria-label` |
| `coar.ui.datePicker.months` | `'Months'` | Month grid `aria-label` |
| `coar.ui.timePicker.*` | *(see DateTime Picker)* | Time picker spinbutton labels |

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `v-model` | `Temporal.ZonedDateTime \| null` | `null` | Selected zoned datetime |
| `timezone` | `string` | user's timezone | IANA timezone ID (e.g. `'Europe/Berlin'`) |
| `label` | `string` | `''` | Label text |
| `placeholder` | `string` | `''` | Placeholder text |
| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Input size |
| `disabled` | `boolean` | `false` | Disable the picker |
| `readonly` | `boolean` | `false` | Make read-only |
| `required` | `boolean` | `false` | Mark as required |
| `error` | `string` | `''` | Error message |

---

---
url: /components/date-views.md
---
# Date Views&#x20;

The read-only display siblings of the picker family. When you have a `Temporal.PlainDate` / `Temporal.PlainDateTime` / `Temporal.ZonedDateTime` value and just want to show it (no editor, no panel) — use these.

```ts
import {
  CoarPlainDateView,
  CoarPlainDateTimeView,
  CoarZonedDateTimeView,
} from '@cocoar/vue-ui';
```

| | Value type | Renders |
|--|--|--|
| **`CoarPlainDateView`** | `Temporal.PlainDate \| null` | `12.05.2026` (locale-resolved format) |
| **`CoarPlainDateTimeView`** | `Temporal.PlainDateTime \| null` | `12.05.2026 14:30` (locale + 12h/24h auto) |
| **`CoarZonedDateTimeView`** | `Temporal.ZonedDateTime \| null` | `12.05.2026 14:30 GMT+2` (+ short zone label) |

Each view mirrors its picker's `formatValue` logic exactly — same `useDatePickerBase` for locale + date-format resolution, same `coarFormatPlainDate` + `coarFormatTime` helpers. A read-only display and the editor's resting state look identical.

## Basic Usage

Pass a `Temporal` value via `:value`. `null` renders the placeholder text (empty string by default). Use anywhere you'd show a date without an editor — cards, dialogs, list rows, table cells. The `@cocoar/vue-data-grid` date columns wrap these viewers internally.

## Locale resolution

The display format reacts to the consumer-app locale via `useL10n()` — switching language at runtime updates the view automatically. Pass `:locale="..."` to override per-instance.

## Cross-zone projection

By default, each `CoarZonedDateTimeView` renders its value **in that value's own zone** — a Tokyo event shows Tokyo wallclock, a Vienna event shows Vienna wallclock. Pass `displayTimeZone="..."` to project every value into a single zone (useful for cross-zone coordination views like "show every team's meeting in my zone").

Use `:show-time-zone="false"` to hide the trailing zone label entirely (compact contexts where the zone is already clear from surrounding UI).

## Cross-realm safety

All three views check the value's type via `Symbol.toStringTag` (matched against `"Temporal.PlainDate"` etc.), not `instanceof Temporal.X`. Why this matters: under pnpm's isolated dependency tree, two packages can resolve different physical copies of `@js-temporal/polyfill` — a `Temporal.PlainDate` instance constructed against one copy fails `instanceof Temporal.PlainDate` checked against another copy. The `Symbol.toStringTag` is part of the Temporal spec and identical across copies (and would be identical against the native `Temporal` once browsers ship it), so the views render correctly no matter which package created the value.

Non-matching values (e.g. an ISO string, a `Date`, or a `PlainDateTime` passed into a `CoarPlainDateView`) render as the placeholder. Convert at your data layer — the views are strict by design.

## API

### `CoarPlainDateView`

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `Temporal.PlainDate \| null` | `null` | The value to display |
| `locale` | `string` | *consumer locale* | BCP-47 tag override |
| `dateFormat` | `DateFormatConfig` | *resolved* | Format pattern override |
| `placeholder` | `string` | `''` | Shown when value is null / wrong type |
| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Font-size token |

### `CoarPlainDateTimeView`

Same as `CoarPlainDateView` plus:

| Prop | Type | Default | Description |
|---|---|---|---|
| `use24Hour` | `boolean \| 'auto'` | `'auto'` | 12h/24h clock; `'auto'` derives from locale |

### `CoarZonedDateTimeView`

Same as `CoarPlainDateTimeView` plus:

| Prop | Type | Default | Description |
|---|---|---|---|
| `displayTimeZone` | `string` | *value's own zone* | IANA zone to project every value into |
| `showTimeZone` | `boolean` | `true` | Append the `GMT+1`-style zone label |

---

---
url: /components/avatar.md
---
# Avatar

Use avatars to give users and entities a recognizable visual identity throughout your application. They display a profile image when available and gracefully fall back to generated initials, so every user always has a face -- even before they upload a photo.

```ts
import { CoarAvatar } from '@cocoar/vue-ui';
```

## Basic Usage

Pass a `name` and the avatar automatically extracts and displays initials. Ideal for user lists, comment threads, and anywhere you need a quick visual identifier.

## With Image

Provide a `src` URL to show a profile photo. If the image fails to load, the avatar seamlessly reverts to initials so the layout never breaks.

## Sizes

Six sizes let you match the avatar to its context -- use `xs` in dense tables or chat lists, and `xxl` for prominent profile headers.

## Shapes

Choose between circle (the default, great for people) and square (useful for teams, organizations, or app icons).

## Avatar Group

Stack avatars with negative margins to show team members or participants at a glance. Add a "+N" overflow indicator when the list is too long to display in full.

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | `''` | User's name (used for initials fallback) |
| `src` | `string` | `undefined` | Image URL |
| `size` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl' \| 'xxl'` | `'m'` | Avatar size |
| `shape` | `'circle' \| 'square'` | `'circle'` | Avatar shape |
| `initials` | `string` | `''` | Custom initials override |
| `clickable` | `boolean` | `false` | Make avatar interactive (button role) |

## i18n Keys

These keys can be translated via [`@cocoar/vue-localization`](/foundations/localization/translations).

| Key | Default (English) | Used as |
|-----|-------------------|---------|
| `coar.ui.avatar.avatar` | `'Avatar'` | `aria-label` and `alt` text fallback when no `name` prop is set |

---

---
url: /components/badge.md
---
# Badge

Badges draw attention to counts, statuses, or short labels. Attach them to icons, avatars, or buttons to surface information that needs a quick glance -- like unread messages, plan tiers, or live/offline indicators.

```ts
import { CoarBadge } from '@cocoar/vue-ui';
```

## Variants

Six semantic variants let you match the badge to its meaning -- use `success` for positive states, `error` for alerts, and so on.

## Sizes

Five sizes from tiny `xs` (great for inline status) to bold `xl` (ideal for dashboard counters).

## Text Content

Badges aren't limited to numbers. Use short text labels like "New", "Beta", or "Pro" to tag features and content.

## Max Value

Set a `max` to cap large numbers gracefully. Perfect for notification counts where "99+" is more useful than "1,247".

## Dot Mode

When you only need to signal presence or status without a specific value, `dot` mode provides a minimal, color-coded indicator.

## Pulse Animation

Add a pulse animation to catch the user's eye for time-sensitive updates like new notifications or live events.

## Bordered

The `bordered` prop adds a ring that prevents the badge from visually merging into its parent. Especially useful when badges sit on top of avatars or colored backgrounds.

## Interactive Demo

See badges in action -- increment and reset a notification counter to observe live updates and max-capping behavior.

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `content` | `string \| number` | `''` | Badge content (text or number) |
| `variant` | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'error' \| 'info'` | `'primary'` | Badge color variant |
| `size` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl'` | `'m'` | Badge size |
| `dot` | `boolean` | `false` | Show as a small dot with no content |
| `max` | `number` | `null` | Cap numeric content (e.g. 100 becomes "99+") |
| `pulse` | `boolean` | `false` | Add pulse animation |
| `bordered` | `boolean` | `false` | Add white border ring |

## i18n Keys

These keys can be translated via [`@cocoar/vue-localization`](/foundations/localization/translations).

| Key | Default (English) | Used as |
|-----|-------------------|---------|
| `coar.ui.badge.notificationIndicator` | `'Notification indicator'` | `aria-label` for dot badges (when no `content` value is set) |

---

---
url: /components/card.md
---
# Card

Cards group related content into a visually distinct container, making it easy for users to scan and interact with discrete chunks of information. Use them for dashboards, content feeds, settings panels, or anywhere you need clear visual boundaries.

```ts
import { CoarCard } from '@cocoar/vue-ui';
```

## Basic Usage

A straightforward card with a title and body text. Cards provide structure without imposing rigid layout rules -- just slot in whatever content you need.

## Elevated vs Outlined

Choose `elevated` for cards that need to stand out from the page (primary content), or `outlined` for a subtler border-based style that sits flatter in the layout.

## Color Variants

Semantic color variants add a tinted background to convey meaning at a glance -- info for tips, success for confirmations, warning and error for alerts.

## Padding Sizes

Adjust internal spacing to suit your content density. Use `s` for compact data cards, `m` for general use, and `l` when the card is the primary focus of the page.

## Rich Content Example

Cards shine when combining multiple elements. Here a header, tags, body text, and action buttons work together inside a single card.

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'neutral' \| 'outlined' \| 'info' \| 'success' \| 'warning' \| 'error' \| 'accent'` | `'neutral'` | Card color/style variant |
| `padding` | `'none' \| 's' \| 'm' \| 'l'` | `'m'` | Internal padding size |
| `elevated` | `boolean` | `false` | Add box shadow for elevation |
| `borderless` | `boolean` | `false` | Hide the border |

### Slots

| Slot | Description |
|------|-------------|
| `default` | Card content |
| `#header` | Fixed header area |
| `#footer` | Fixed footer area |
| `#inset` | Full-width inset area (negative margins) |

---

---
url: /components/code-block.md
---
# Code Block

Display source code with syntax highlighting, a one-click copy button, and optional collapsing. Use it in documentation, onboarding flows, or anywhere users need to read or copy code snippets.

```ts
import { CoarCodeBlock } from '@cocoar/vue-ui';
```

## Language Support

Built-in highlighting for TypeScript, HTML, CSS, Bash, JSON, and more. The language is detected from the `language` prop, so colors and tokens always match the syntax.

## Collapsible Behavior

Keep long snippets from dominating the page. Start them collapsed so users can expand on demand, or disable collapsing when the code should always be visible.

## Variants

The default `neutral` variant uses a neutral background. Other variants color the header area to match semantic context — `info`, `success`, `warning`, `error`, or `accent`.

## With Line Numbers

Enable line numbers for larger code blocks where users need to reference specific lines.

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `code` | `string` | `''` | The source code to display |
| `language` | `string` | `'html'` | Syntax highlighting language |
| `variant` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'error' \| 'accent'` | `'neutral'` | Header color variant |
| `title` | `string` | `''` | Optional title/filename label |
| `collapsible` | `boolean` | `true` | Show collapse/expand toggle |
| `collapsed` | `boolean` | `false` | Start in collapsed state |
| `showLineNumbers` | `boolean` | `false` | Show line numbers |
| `showCopy` | `boolean` | `true` | Show copy-to-clipboard button |
| `maxHeight` | `number` | `0` | Maximum height in px before scrolling (0 = no limit) |
| `borderless` | `boolean` | `false` | Hide border and border-radius |
| `elevated` | `boolean` | `false` | Add box shadow |

## i18n Keys

These keys can be translated via [`@cocoar/vue-localization`](/foundations/localization/translations).

| Key | Default (English) | Used as |
|-----|-------------------|---------|
| `coar.ui.codeBlock.copy` | `'Copy'` | Copy button text |
| `coar.ui.codeBlock.copied` | `'Copied!'` | Copy button text (after success) |
| `coar.ui.codeBlock.failed` | `'Failed'` | Copy button text (after error) |
| `coar.ui.codeBlock.copyLabel` | `'Copy code'` | Copy button `aria-label` |
| `coar.ui.codeBlock.toggleVisibility` | `'Toggle code visibility'` | Collapse/expand button `aria-label` |
| `coar.ui.codeBlock.code` | `'Code'` | Code block `aria-label` |

---

---
url: /components/divider.md
---
# Divider

Dividers create clear visual breaks between sections of content. They're especially useful in forms, settings panels, and feeds where distinct groups of information sit close together. Add an optional text label to give the break semantic meaning.

```ts
import { CoarDivider } from '@cocoar/vue-ui';
```

## Basic Divider

A clean horizontal line that separates content blocks. Drop it between any two sections to improve scannability.

## With Content

Embed text directly in the divider line via the default slot -- common in forms ("or continue with") and settings pages.

## Alignment

Position the content to the `left`, `center`, or `right` of the line to match your layout's reading flow.

## Variants

Two visual weights: `subtle` (the default) for light separation within a card, and `strong` for more prominent visual breaks.

## Real-world Usage

A classic login form pattern where a labeled divider separates OAuth sign-in buttons from the traditional email/password fields.

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `align` | `'left' \| 'center' \| 'right'` | `'center'` | Content alignment |
| `variant` | `'subtle' \| 'strong'` | `'subtle'` | Line visual weight |
| `width` | `number` | `90` | Divider width as a percentage (0–100) |
| `spacingTop` | `number` | `0` | Top spacing in pixels |
| `spacingBottom` | `number` | `0` | Bottom spacing in pixels |

### Slots

| Slot | Description |
|------|-------------|
| `default` | Optional content displayed centered on the line |

---

---
url: /components/link.md
---
# Link

Styled anchor elements with no wrapper component required -- just add CSS classes to native `<a>` tags. Use links for in-page navigation, external references, and any clickable text that isn't a button action.

```html
<!-- Import via @cocoar/vue-ui/styles -->
```

## Basic Link

The default style applies an accent color with an underline on hover, making links instantly recognizable in any context.

## Variants

Use the `accent` variant (default) for primary navigation and calls to action. Switch to `subtle` when the link should blend into surrounding body text.

## Sizes

Three size modifiers align with the typography scale, so links stay proportional whether they appear in footnotes or headings.

## Disabled State

Combine the `aria-disabled` attribute with the disabled class to visually and semantically deactivate a link while keeping it in the DOM for accessibility.

## Inline Usage

Links are designed to sit naturally inside running prose without disrupting line height or text flow.

## API

### CSS Classes

| Class | Description |
|-------|-------------|
| `.coar-link` | Base link style — accent color, underline on hover |
| `.coar-link--subtle` | Subtle variant with less color emphasis |
| `.coar-link--sm` | Small text size |
| `.coar-link--lg` | Large text size |
| `.coar-link--disabled` | Disabled appearance (use with aria-disabled) |

---

---
url: /components/note.md
---
# Note

Notes call attention to supplementary information without interrupting the main content flow. Use them for tips, requirements, deprecation warnings, or any contextual message that readers should notice but shouldn't be blocked by. A colored left border and tinted background create just enough contrast to stand out.

```ts
import { CoarNote } from '@cocoar/vue-ui';
```

## Color Variants

Six semantic variants communicate intent at a glance: `info` for tips, `success` for confirmations, `warning` for cautions, `error` for critical issues, `neutral` for general remarks, and `accent` for brand-specific callouts.

## Padding Sizes

Use `m` (the default) for standalone callouts, `s` inside compact layouts like cards or sidebars, and `l` for more prominent call-to-action notes.

## Rich Content

The default slot accepts any HTML, so you can include links, bold text, inline code, and multi-line content without limitations.

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'error' \| 'accent'` | `'neutral'` | Note color variant |
| `padding` | `'s' \| 'm' \| 'l'` | `'m'` | Internal padding size |

### Slots

| Slot | Description |
|------|-------------|
| `default` | Note content (supports rich HTML) |

---

---
url: /components/progress-bar.md
---
# Progress Bar

Progress bars keep users informed about ongoing operations -- file uploads, multi-step workflows, or background tasks. They reduce uncertainty by showing either a concrete completion percentage or an animated indicator when the duration is unknown.

```ts
import { CoarProgressBar } from '@cocoar/vue-ui';
```

## Basic Progress

Bind a numeric `value` (0--100) to show determinate progress. Ideal for file uploads, form completion, or any task where you can measure how much work remains.

## Indeterminate

When you can't predict how long an operation will take -- network requests, server-side processing -- switch to indeterminate mode for a continuous animation that signals "working on it."

## Color Variants

Match the bar color to its context: `accent` (default) for standard progress, `success` for completed uploads, `warning` for approaching limits, `error` for failed operations.

## Sizes

Three heights give you flexibility. Use `s` inside compact cards or table rows, `m` for standard layouts, and `l` when the progress bar is the focal point.

## Live Progress

A continuously animating example that shows how the bar transitions smoothly as the value changes.

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | `0` | Current progress value |
| `max` | `number` | `100` | Maximum progress value |
| `indeterminate` | `boolean` | `false` | Show animated indeterminate state |
| `variant` | `'accent' \| 'success' \| 'warning' \| 'error'` | `'accent'` | Color variant |
| `size` | `'s' \| 'm' \| 'l'` | `'m'` | Bar height |
| `label` | `string` | `''` | Accessible label for screen readers |
| `showValue` | `boolean` | `false` | Display the percentage value next to the bar |

---

---
url: /components/spinner.md
---
# Spinner

Spinners signal that something is loading when you can't show a progress bar. They tell users "we're working on it" for network requests, lazy-loaded content, or any asynchronous operation with an unpredictable duration.

```ts
import { CoarSpinner } from '@cocoar/vue-ui';
```

## Basic Spinner

Drop in a spinner wherever content is still loading. It animates continuously until you remove it or swap in the real content.

## Sizes

Four sizes to fit any context -- `xs` for inline loading indicators next to text, up to `l` for full-page or overlay states.

## With Loading Text

Pair a spinner with a descriptive message so users know what's being loaded, not just that something is happening.

## Full Page Overlay

Center a spinner in a container overlay to block interaction while critical data loads. This pattern works well for initial page loads and modal content.

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Spinner size |
| `label` | `string` | `'Loading'` | Accessible label for screen readers |

---

---
url: /components/table.md
---
# Table

A lightweight table wrapper that provides consistent styling, alternating row colors, and proper alignment out of the box. Use it whenever you need to present structured data -- user lists, order histories, configuration settings, or comparison grids.

```ts
import { CoarTable } from '@cocoar/vue-ui';
```

## Basic Usage

Wrap standard `thead`, `tbody`, `tr`, `th`, and `td` elements. Alternating row colors are applied automatically to improve readability in longer datasets.

## Rich Cells

Table cells aren't limited to plain text. Embed avatars, tags, badges, and other components directly in cells to create information-dense but scannable rows.

## Variants

The default striped style works well for most tables. Switch to `plain` for a minimal look, or `bordered` when you need explicit cell boundaries -- useful for dense data or comparison tables.

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'default' \| 'plain' \| 'bordered'` | `'default'` | Table style variant |
| `compact` | `boolean` | `false` | Use compact cell padding |
| `hover` | `boolean` | `true` | Highlight rows on hover |

### Slots

| Slot | Description |
|------|-------------|
| `default` | Native thead/tbody/tr/th/td elements |

---

---
url: /components/tag.md
---
# Tag

Tags label, categorize, and organize content. Use them for metadata (status labels, technology stacks), filter chips, or user-driven selections. Unlike badges, which show counts and status dots, tags convey descriptive information that users can read and often interact with.

```ts
import { CoarTag } from '@cocoar/vue-ui';
```

## Color Variants

Six semantic variants let you color-code categories, statuses, or priority levels consistently across your application.

## Sizes

Three sizes to match the surrounding context -- `s` for data tables, `m` for general use, and `l` for prominent labels.

## Closable Tags

Enable the `closable` prop to let users remove tags. Listen to the `@closed` event to update your data. Ideal for filter bars, selected options, and editable tag lists.

## Selectable Tags

Make tags toggleable for selection interfaces -- filter panels, interest pickers, or any multi-choice input that benefits from a visual, chip-style UI.

## Tag Groups

Cluster related tags together to label content. This pattern works well for article metadata, skill sets, and category breakdowns.

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'error' \| 'accent'` | `'neutral'` | Tag color variant |
| `size` | `'s' \| 'm' \| 'l'` | `'m'` | Tag size |
| `closable` | `boolean` | `false` | Show close button |

### Events

| Event | Payload | Description |
|-------|---------|-------------|
| `closed` | — | Emitted when the close button is clicked |

## i18n Keys

These keys can be translated via [`@cocoar/vue-localization`](/foundations/localization/translations).

| Key | Default (English) | Used as |
|-----|-------------------|---------|
| `coar.ui.tag.remove` | `'Remove tag'` | Close button `aria-label` (when `closable` is true) |

---

---
url: /components/menu.md
---
# Menu

Build context menus, action lists, and navigation panels with full keyboard support. Menus group related actions together, making them easy to discover and interact with. They support nested submenus, icons, section headings, and danger variants for destructive actions.

```ts
import { CoarMenu, CoarMenuItem, CoarMenuDivider, CoarMenuHeading, CoarSubExpand, CoarSubFlyout } from '@cocoar/vue-ui';
```

## Basic Menu

The simplest menu: a list of clickable items separated by dividers. Individual items can be disabled when an action is not available.

## With Headings

Use `CoarMenuHeading` to organize a longer menu into labeled sections. This helps users scan for the action they need without reading every item.

## With Icons

Leading icons give each item a visual anchor, making menus faster to scan. Use a trash icon on destructive actions like "Delete" to signal their intent.

## Nested Submenus

When a menu item leads to a group of related options, wrap them in `CoarSubExpand`. Submenus expand inline, keeping the user in context without opening a separate overlay.

## Flyout Submenus

Use `CoarSubFlyout` when the submenu should appear as a floating panel beside the trigger instead of expanding inline. The `label` prop sets the visible text; child items go in the default slot and render inside the flyout.

## Borderless (Sidebar)

Pass the `borderless` prop when embedding a menu inside a sidebar, panel, or card. This removes the outer border and background so the menu blends into its container.

## Scrollable Menu

When a menu has many items, it scrolls automatically. Use `#header` and `#footer` slots for fixed content above and below the scrollable area. `CoarMenuHeading` supports a `sticky` prop to keep section headers visible while scrolling.

## Accessibility

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Arrow Up` / `Arrow Down` | Move focus between items |
| `Enter` / `Space` | Activate focused item |
| `Escape` | Close nested submenus |
| `Tab` | Move focus out of the menu |

## API

### CoarMenu Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `showIconColumn` | `boolean` | `true` | Reserve icon column to prevent layout shift |
| `borderless` | `boolean` | `false` | Remove outer border/background |

### CoarMenu Slots

| Slot | Description |
|------|-------------|
| `default` | Menu items (scrollable area) |
| `header` | Fixed content above the scrollable area |
| `footer` | Fixed content below the scrollable area |

### CoarMenuHeading Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | `undefined` | Heading text (alternative to default slot) |
| `sticky` | `boolean` | `false` | Stick to top of scroll container |

### CoarMenuItem Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | `undefined` | Item label text (alternative to default slot) |
| `icon` | `string` | `undefined` | Leading icon name |
| `disabled` | `boolean` | `false` | Disable the item |

### CoarMenuItem Slots

| Slot | Description |
|------|-------------|
| `default` | Item label content |

### CoarMenuItem Events

| Event | Payload | Description |
|-------|---------|-------------|
| `clicked` | `MenuItemClickEvent` | Emitted when item is clicked |

```ts
interface MenuItemClickEvent {
  event: MouseEvent;
  keepMenuOpen(): void; // Call to prevent auto-close of the menu tree
}
```

---

---
url: /components/context-menu.md
---
# Context Menu

Open a menu at the pointer position on right-click. The `useContextMenu` composable manages open/close state and cursor coordinates, while `CoarContextMenu` renders the menu as a floating overlay with automatic viewport clamping.

```ts
import { useContextMenu, CoarContextMenu } from '@cocoar/vue-ui';
```

## Basic Usage

Call `useContextMenu()` to get a controller, bind `menu.open` to `@contextmenu`, and place your menu items inside `<CoarContextMenu>`. The menu closes automatically when an item is clicked, when clicking outside, pressing Escape, or scrolling.

## With Headings & Submenus

All standard menu features work inside context menus — headings, dividers, icons, and inline submenus via `CoarSubExpand`.

## Flyout Submenus

Use `CoarSubFlyout` inside a context menu for nested flyout panels — useful for status changes, priority selectors, etc.

## Data Grid Integration

Use separate `useContextMenu()` instances for cell and viewport right-clicks. The data grid builder provides `onCellContextMenu` and `onViewportContextMenu` handlers that give you the mouse event to pass into `menu.open()`.

## Keeping the Menu Open

By default, clicking a `CoarMenuItem` closes the entire context menu. Call `keepMenuOpen()` on the click event to prevent this — useful for toggles or multi-select actions.

```vue
<CoarMenuItem
  label="Toggle dark mode"
  icon="moon"
  @clicked="(e) => { e.keepMenuOpen(); toggleDarkMode(); }"
/>
```

## API

### `useContextMenu()`

Returns a `ContextMenuContext` object:

| Property   | Type                          | Description                                    |
|------------|-------------------------------|------------------------------------------------|
| `isOpen`   | `Readonly<Ref<boolean>>`      | Whether the menu is currently visible          |
| `position` | `Readonly<Ref<{x, y}>>`      | Cursor position where the menu was opened      |
| `open`     | `(event: MouseEvent) => void` | Open at the event's cursor position            |
| `close`    | `() => void`                  | Close the menu                                 |

### `<CoarContextMenu>`

| Prop   | Type                 | Required | Description                              |
|--------|----------------------|----------|------------------------------------------|
| `menu` | `ContextMenuContext` | Yes      | Controller returned by `useContextMenu()` |

**Slot:** `default` — menu items (`CoarMenuItem`, `CoarMenuDivider`, `CoarMenuHeading`, `CoarSubExpand`, etc.)

### Behavior

* **Viewport clamping** — the menu repositions to stay within the window
* **Click outside** — closes the menu
* **Escape** — closes the menu
* **Scroll** — closes the menu
* **Auto-close on item click** — unless `keepMenuOpen()` is called

---

---
url: /components/sidebar.md
---
# Sidebar

A structured navigation sidebar with three distinct sections: a header for branding, a scrollable content area for navigation, and a footer for secondary actions. Use the dedicated sidebar components (`CoarSidebarItem`, `CoarSidebarGroup`, `CoarSidebarHeading`, `CoarSidebarDivider`, `CoarSidebarSpacer`) for full collapsed/expanded support with automatic tooltips.

```ts
import {
  CoarSidebar,
  CoarSidebarItem,
  CoarSidebarGroup,
  CoarSidebarHeading,
  CoarSidebarDivider,
  CoarSidebarSpacer,
} from '@cocoar/vue-ui';
```

## Sidebar Items

Use `CoarSidebarItem` for navigation, `CoarSidebarGroup` for expandable or flyout sections, and `CoarSidebarHeading` for section labels. Items go directly into the sidebar — no `CoarMenu` wrapper needed.

Toggle `collapsed` for icon-only mode with automatic tooltips. Groups support two modes: `expand` (inline panel with plus/minus indicator) and `flyout` (floating panel with chevron indicator). Use the controls to explore all options.

## Side / Orientation

The `side` prop attaches the sidebar to any of the four edges. `left` and `right` give a vertical column (the classic navigation rail); `top` and `bottom` switch the layout to a horizontal toolbar. Tooltip placement, flyout direction, the active-state indicator border, and the collapsed dimension (width vs. height) all adapt automatically.

Use the `side` selector below to flip between all four orientations on the same content.

## Migrating from Menu-based Sidebar

If you are using `CoarMenu` and `CoarMenuItem` inside `CoarSidebar`, we recommend migrating to the new sidebar-specific components. The new components support collapsed mode with automatic tooltips, flyout panels, icon-only mode, and nested groups — none of which work with the menu-based approach.

**Before (menu-based):**

```vue
<CoarSidebar v-model:collapsed="collapsed">
  <CoarMenu>
    <CoarMenuItem icon="home" label="Dashboard" />
    <CoarMenuItem icon="user" label="Profile" />
    <CoarSubExpand icon="users" label="Users">
      <CoarMenuItem icon="user-plus" label="All Users" />
      <CoarMenuItem icon="shield" label="Roles" />
    </CoarSubExpand>
  </CoarMenu>
</CoarSidebar>
```

**After (sidebar components):**

```vue
<CoarSidebar v-model:collapsed="collapsed">
  <CoarSidebarItem icon="home" label="Dashboard" active />
  <CoarSidebarItem icon="user" label="Profile" />
  <CoarSidebarGroup icon="users" label="Users" v-model:open="usersOpen">
    <CoarSidebarItem icon="user-plus" label="All Users" />
    <CoarSidebarItem icon="shield" label="Roles" />
  </CoarSidebarGroup>
</CoarSidebar>
```

**Key differences:**

* No `CoarMenu` wrapper — items go directly into the sidebar
* `CoarSidebarItem` replaces `CoarMenuItem` (same props: `icon`, `label`, `active`, `disabled`)
* `CoarSidebarGroup` replaces `CoarSubExpand` — add `mode="flyout"` for flyout behavior
* Headings use `CoarSidebarHeading` instead of custom markup
* Footer items use `<template #footer>` slot — they stretch to full width automatically

## API

### CoarSidebar

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `side` | `'left' \| 'right' \| 'top' \| 'bottom'` | `'left'` | Which edge the sidebar attaches to. `top`/`bottom` switch the layout to horizontal (items in a row, scrolls horizontally). Flyout submenus and tooltip placements adapt automatically. |
| `position` | `'left' \| 'right'` | — | **Deprecated.** Use `side` instead. Still accepted as an alias for backwards compatibility. |
| `collapsed` | `boolean` | `false` | Narrow/icon-only collapsed state. Supports `v-model:collapsed`. In horizontal sidebars this collapses height instead of width. |
| `size` | `'s' \| 'm' \| 'l'` | `'m'` | Icon size: s (16px), m (20px), l (24px) |
| `variant` | `'primary' \| 'secondary'` | `'primary'` | Background color variant |
| `elevated` | `boolean` | `false` | Show elevation shadow |
| `borderless` | `boolean` | `false` | Hide the border |
| `ariaLabel` | `string` | `'Sidebar'` | Accessible label for the nav landmark |

#### Slots

All slots receive `{ collapsed: boolean }` as scoped slot props.

| Slot | Description |
|------|-------------|
| `#header` | Start of the main axis — top in vertical sidebars, left in horizontal. Use for logo, brand, workspace switcher |
| `default` | Scrollable content area — sidebar items. Scrolls vertically in vertical sidebars, horizontally in horizontal ones |
| `#footer` | End of the main axis — bottom in vertical sidebars, right in horizontal. Use for user profile, logout, secondary actions |

### CoarSidebarItem

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | *(required)* | Item label text |
| `icon` | `string` | — | Icon name (recommended for collapsed mode) |
| `active` | `boolean` | `false` | Highlight as current page |
| `disabled` | `boolean` | `false` | Disabled state |

**Events:** `@click` — standard `MouseEvent`

### CoarSidebarGroup

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | *(required)* | Group label text |
| `icon` | `string` | — | Icon name (recommended for collapsed mode) |
| `disabled` | `boolean` | `false` | Disabled state |
| `mode` | `'expand' \| 'flyout'` | `'expand'` | `expand`: inline animated panel (plus/minus icon). `flyout`: floating panel next to the sidebar (chevron icon). |
| `open` | `boolean` | `false` | Expanded state (expand mode). Supports `v-model:open`. |
| `icon-only` | `boolean` | `false` | Flyout shows icon-only items with tooltips (no labels). Inherited by nested groups. Use `:icon-only="collapsed"` for dynamic behavior. |
| `open-on-hover` | `boolean` | `false` | Open flyout on hover (200ms delay) instead of click. Only applies to `mode="flyout"`. |

### CoarSidebarHeading

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | *(required)* | Section heading text. Hidden when sidebar is collapsed (small spacer remains). |

### CoarSidebarDivider

No props. Renders a horizontal separator line.

### CoarSidebarSpacer

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `height` | `string` | `var(--coar-spacing-m)` | CSS height value (e.g. `'8px'`, `'1rem'`) |
| `grow` | `boolean` | `false` | If true, fills available space (`flex: 1`) |

## CSS Tokens

| Token | Default | Description |
|-------|---------|-------------|
| `--coar-sidebar-width` | `16rem` | Default width (vertical sidebars) |
| `--coar-sidebar-collapsed-width` | *size-aware* — s: `2.25rem`, m: `2.75rem`, l: `3.25rem` | Width in collapsed mode. Auto-scales with `size`; set this token to override. |
| `--coar-sidebar-height` | `auto` | Default height (horizontal sidebars) |
| `--coar-sidebar-collapsed-height` | *size-aware* — same scale as collapsed-width | Height in collapsed mode. Auto-scales with `size`; set this token to override. |
| `--coar-sidebar-item-padding` | `0.5rem 0.75rem` | Item padding |
| `--coar-sidebar-item-gap` | `0.75rem` | Gap between icon and label |
| `--coar-sidebar-item-margin-horizontal` | `0 2px` | Item margin in horizontal sidebars |
| `--coar-sidebar-item-hover` | neutral tertiary | Hover background |
| `--coar-sidebar-item-active-color` | accent primary | Active text color |
| `--coar-sidebar-item-active-bg` | accent tertiary | Active background |
| `--coar-sidebar-group-indent` | `16px` | Child indent for `mode="expand"` (vertical only) |

---

---
url: /components/navbar.md
---
# Navbar

A top-level navigation bar that anchors your application layout. It provides three flexible content slots -- start, center, and end -- so you can place a logo, navigation links, and user actions exactly where they belong. By default it uses a subtle shadow for visual elevation; switch to `bordered` for a flat look with a bottom border instead.

```ts
import { CoarNavbar } from '@cocoar/vue-ui';
```

## Basic Usage (Elevated)

The default navbar casts a light shadow to separate it from the page content below. Use all three slots for a complete navigation layout: brand on the left, links in the center, and call-to-action buttons on the right.

## App Navbar with User Avatar

A common pattern for authenticated applications. The start slot holds the brand mark, the center slot contains primary navigation, and the end slot pairs notification controls with a user avatar.

## Logo Only (Start Slot)

Not every navbar needs all three slots. For landing pages or simple tools, use just the start and end slots for a clean, minimal header.

## Bordered (No Shadow)

Prefer a flat aesthetic? The `bordered` prop swaps the drop shadow for a thin bottom border, giving the navbar a lighter visual weight that works well in dense dashboards.

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `elevated` | `boolean` | `true` | Show subtle box-shadow elevation |
| `bordered` | `boolean` | `false` | Show bottom border instead of shadow |

### Slots

| Slot | Description |
|------|-------------|
| `#start` | Left-aligned content (logo, brand name) |
| `#center` | Centered content (navigation links) |
| `#end` | Right-aligned content (actions, user menu) |

---

---
url: /components/tabs.md
---
# Tabs

Organize related content into separate panels that users switch between without leaving the page. Tabs are ideal for settings screens, detail views, and any layout where showing everything at once would feel overwhelming. The active tab is controlled via `v-model`, so you can read or set it programmatically.

```ts
import { CoarTabGroup, CoarTab } from '@cocoar/vue-ui';
```

## Basic Tabs

Define your tabs inside a `CoarTabGroup` and render the matching panel content with `v-if` on the active tab ID. Users can click tabs or use the keyboard to switch between them.

## Settings Pattern

Tabs shine in settings pages where each category has its own form section. This pattern keeps the page compact and scannable while giving each section room to breathe.

## Disabled Tabs

Disable individual tabs to prevent access to sections that are not yet available, require a higher permission level, or depend on completing a previous step first.

## Actions in the Tab Bar

Use the `#actions` slot to put right-aligned controls on the same row as the tab labels — typical uses include undo/redo buttons, a refresh icon, filter toggles, or an overflow menu. The slot stays out of the way when unused: consumers that never populate it get the exact same layout as before.

## Accessibility

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Left Arrow` / `Right Arrow` | Move between tabs |
| `Home` | First tab |
| `End` | Last tab |
| `Tab` | Move to panel content |

## API

### CoarTabGroup Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `v-model` | `string` | first tab id | ID of the active tab |

### CoarTabGroup Slots

| Slot | Description |
|------|-------------|
| `default` | Contains one or more `CoarTab` children defining tabs and their panels. |
| `actions` | Optional right-aligned controls in the tab-list row. Rendered only when populated; empty-slot consumers see the standard layout. |

### CoarTab Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `id` | `string` | — | Unique tab identifier (**required**) |
| `disabled` | `boolean` | `false` | Disable this tab |
| `loadingStrategy` | `'lazy' \| 'eager'` | `'lazy'` | `lazy`: content only rendered when active; `eager`: always in DOM |

---

---
url: /components/segmented-control.md
---
# Segmented Control

Switch between a small fixed set of mutually-exclusive options like view modes, filters, density, or time ranges. A segmented control reads as a button-bar for view-state — same semantics as a radio group (single selection from N options), different visual register: it belongs in toolbars and headers, not in forms.

```ts
import { CoarSegmentedControl } from '@cocoar/vue-ui';
```

## Basic Usage

Pass an array of `{ value, label }` options and bind the active value via `v-model`. The control is generic over the option's value type, so the model and event payloads stay strongly typed.

## Sizes

Heights and font sizes line up with `CoarButton`'s `xs / s / m / l` so the segmented control sits naturally next to other buttons in a toolbar. Default is `s`.

## With Icons

Each option accepts an optional `icon` (`CoarIcon` name) rendered before the label. Icon-only segments work too — pass `ariaLabel` on the option for screen-reader text when the visible label is empty.

## Disabled

Disable a single option to hide a state that's currently unavailable, or disable the whole control when the surrounding context is read-only.

## Full Width

Set `fullWidth` to make the control fill its container; segments share the available width equally. Useful in narrow side panels and mobile layouts.

## When to Use

| Use a segmented control when… | Use a radio group instead when… |
|---|---|
| The choices are 2–6 view-state options | The choices are part of a form being submitted |
| The control sits in a toolbar / header | The control sits in a labelled form field |
| Choosing should switch the UI immediately | Choosing should be confirmed by a Submit |

## Accessibility

The control is exposed as `role="group"` with the `ariaLabel` you pass; each segment is a `<button type="button">` with `aria-pressed` reflecting the active state. Screen readers announce both the group label and the pressed state of the active segment. Disabled segments use the native `disabled` attribute.

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `v-model` | `T` (required) | — | Active option's `value`. |
| `options` | `CoarSegmentedControlOption<T>[]` | — | List of segments. |
| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'s'` | Sizes match `CoarButton`. |
| `disabled` | `boolean` | `false` | Disable the entire control. |
| `fullWidth` | `boolean` | `false` | Stretch to fill the parent's width. |
| `ariaLabel` | `string` | — | Screen-reader label for the group. |

### Events

| Event | Payload | Description |
|-------|---------|-------------|
| `update:modelValue` | `T` | Standard v-model update. |
| `change` | `(value: T, option: CoarSegmentedControlOption<T>)` | Fired only when the user picks a *different* option. |

### `CoarSegmentedControlOption<T>`

| Field | Type | Description |
|-------|------|-------------|
| `value` | `T` | Bound to `v-model`. |
| `label` | `string` | Visible label. May be empty for icon-only segments. |
| `icon` | `string` | Optional `CoarIcon` name rendered before the label. |
| `disabled` | `boolean` | Disable just this segment. |
| `ariaLabel` | `string` | Override aria-label for the segment (typical for icon-only). |

---

---
url: /components/breadcrumb.md
---
# Breadcrumb

Show users exactly where they are within a page hierarchy and give them a quick path back to any parent level. Breadcrumbs are especially valuable in applications with deep navigation structures, where the sidebar alone does not make the current location obvious.

```ts
import { CoarBreadcrumb, CoarBreadcrumbItem } from '@cocoar/vue-ui';
```

## Basic Usage

Wrap each level in a `CoarBreadcrumbItem`. Parent levels are rendered as links; the last item is marked `active` to indicate the current page. Separators between items are handled automatically.

## Deep Hierarchy

Breadcrumbs scale naturally for deeply nested content. Even a five-level trail remains compact and readable, giving users confidence about their location.

## App Navigation

Here are several breadcrumb paths you might encounter in a real application -- from a simple two-level dashboard path to a four-level project issue drill-down.

## Accessibility

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Tab` | Move between breadcrumb links |
| `Enter` | Activate the focused link |
| `Shift + Tab` | Move focus backward |

## API

### CoarBreadcrumb Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `separator` | `string` | `'/'` | Separator character between items |
| `ariaLabel` | `string` | `'Breadcrumb'` | Accessible label for the nav landmark |

### CoarBreadcrumbItem Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `active` | `boolean` | `false` | Mark as the current/active page (not a link) |

### CoarBreadcrumbItem Slots

| Slot | Description |
|------|-------------|
| `default` | Item content -- typically an anchor tag for links, or plain text for the active item |

---

---
url: /components/pagination.md
---
# Pagination

Split large collections into digestible pages and let users navigate between them. Pagination automatically calculates page count from `totalItems` and `pageSize`, and intelligently truncates the page range with ellipses when there are too many pages to display at once.

```ts
import { CoarPagination } from '@cocoar/vue-ui';
```

## Basic Usage

Bind a reactive page number with `v-model`. This example paginates 100 items at 10 per page, yielding 10 pages.

## Different Page Size

Adjust `totalItems` and `pageSize` to match your data. Here, 500 items at 25 per page produces 20 pages.

## Large Dataset

With 10,000 items, the page count reaches 1,000. The component automatically shows ellipsis markers so the control stays compact no matter how many pages exist.

## With Table

The most common real-world pattern: pair pagination with a data table. A summary line shows the visible row range, and page controls sit alongside it in the table footer.

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `v-model` | `number` | `1` | Current active page (1-indexed) |
| `totalItems` | `number` | — | Total number of items (**required**) |
| `pageSize` | `number` | `10` | Items per page |
| `maxVisiblePages` | `number` | `5` | Maximum visible page buttons |
| `showFirstLast` | `boolean` | `true` | Show first/last page nav buttons |
| `disabled` | `boolean` | `false` | Disable the pagination control |

### Events

| Event | Payload | Description |
|-------|---------|-------------|
| `pageChanged` | `number` | Emitted when the page changes |

## i18n Keys

These keys can be translated via [`@cocoar/vue-localization`](/foundations/localization/translations).

| Key | Default (English) | Used as |
|-----|-------------------|---------|
| `coar.ui.pagination.firstPage` | `'Go to first page'` | First page button `aria-label` |
| `coar.ui.pagination.previousPage` | `'Go to previous page'` | Previous page button `aria-label` |
| `coar.ui.pagination.nextPage` | `'Go to next page'` | Next page button `aria-label` |
| `coar.ui.pagination.lastPage` | `'Go to last page'` | Last page button `aria-label` |
| `coar.ui.pagination.morePage` | `'More pages'` | Ellipsis separator `aria-label` |
| `coar.ui.pagination.goToPage` | `'Go to page {page}'` | Page number button `aria-label` — `{page}` is replaced with the page number |
| `coar.ui.pagination.nav` | `'Pagination'` | Nav element `aria-label` |

---

---
url: /components/dialog.md
---
# Dialog

Modal dialogs demand attention. They block interaction with the rest of the page until the user makes a decision, making them the right choice for destructive actions, important confirmations, and messages that must be acknowledged before proceeding. Use them sparingly -- when the stakes are high enough to justify interrupting the user's flow.

```ts
import { useDialog } from '@cocoar/vue-ui';
```

## Confirm Dialog

Use `dialog.confirm()` when you need an explicit yes-or-no decision before proceeding. The returned promise resolves with `true` (confirmed) or `false` / `undefined` (cancelled / dismissed).

## Alert Dialog

Use `dialog.alert()` for one-way messages that require acknowledgement -- session expirations, permission errors, or completion notices. The user can only dismiss it; there is no secondary action.

## Setup

Register the overlay plugin once in your app entry point:

```ts
// main.ts
import { CoarOverlayPlugin } from '@cocoar/vue-ui';

createApp(App)
  .use(CoarOverlayPlugin)
  .mount('#app');
```

::: warning Dialog vs Popconfirm
Use **Dialog** for modal confirmations that block the entire UI. Use **Popconfirm** for lightweight inline confirmations anchored near the trigger element. Dialogs are appropriate for higher-stakes, less frequent actions.
:::

## API

### `useDialog()` Methods

| Method | Parameters | Returns | Description |
|--------|-----------|---------|-------------|
| `dialog.confirm(options)` | `ConfirmOptions` | `DialogRef<boolean>` | Show a confirm/cancel dialog |
| `dialog.alert(title, message)` | `string, string` | `DialogRef<void>` | Show an acknowledgement dialog |
| `dialog.open(component, config?, props?)` | `Component, DialogConfig?, Record?` | `DialogRef<T>` | Open a custom component inside the dialog |

### `ConfirmOptions`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `title` | `string` | — | Dialog title |
| `message` | `string` | — | Confirmation message body |
| `confirmText` | `string` | `'Confirm'` | Confirm button label |
| `cancelText` | `string` | `'Cancel'` | Cancel button label |
| `confirmVariant` | `'primary' \| 'danger'` | `'primary'` | Confirm button color variant |
| `size` | `'s' \| 'm' \| 'l'` | `'s'` | Dialog width |

### `DialogRef`

| Property | Type | Description |
|----------|------|-------------|
| `result` | `Promise<T \| undefined>` | Resolves when the dialog closes |
| `close(result?)` | `(val?: T) => void` | Programmatically close the dialog |

## i18n Keys

These keys can be translated via [`@cocoar/vue-localization`](/foundations/localization/translations).

| Key | Default (English) | Used as |
|-----|-------------------|---------|
| `coar.ui.dialog.close` | `'Close dialog'` | Close button `aria-label` |
| `coar.ui.dialog.dialog` | `'Dialog'` | Fallback dialog `aria-label` (when no title) |

---

---
url: /components/popover.md
---
# Popover

Popovers display rich, interactive content anchored to a trigger element. Unlike tooltips (which are text-only and non-interactive), popovers can hold forms, menus, formatted text, and action buttons. They stay open until the user clicks away or presses Escape, giving people time to interact with the content inside.

```ts
import { CoarPopover } from '@cocoar/vue-ui';
```

## Basic Popover (Click)

Set `mode="click"` to open the popover on click. This is the best mode for action menus and content that users need to interact with. Click outside the popover or press Escape to dismiss it.

## Hover Mode

The default `mode="hover"` opens the popover when the pointer enters the trigger. Use `mode="both"` to support both hover preview and click-to-pin behavior -- the popover opens on hover and stays pinned after a click.

## User Menu

A classic application pattern: clicking an avatar reveals a small card with the user's identity and quick actions like profile, settings, and sign-out.

## Info Popover

Attach a hover popover to an icon button to provide contextual help without navigating the user away from their current task. This works well for explaining features, showing rate limits, or surfacing inline guidance.

::: info Slot names
Place the trigger in the **default slot** and the content in **`#content`**. The popover auto-positions itself to stay within the viewport -- no placement prop needed.
:::

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `mode` | `'hover' \| 'click' \| 'both'` | `'hover'` | How the popover is triggered |
| `disabled` | `boolean` | `false` | Prevent the popover from opening |
| `interactive` | `boolean` | `true` | Whether the panel receives pointer events |
| `offset` | `number` | `6` | Gap in px between trigger and panel |

### Slots

| Slot | Description |
|------|-------------|
| `default` | The trigger element that opens the popover |
| `#content` | The popover panel content |

---

---
url: /components/popconfirm.md
---
# Popconfirm

A lightweight confirmation bubble that appears right next to the trigger element. Use it for quick "are you sure?" moments -- deleting a row, removing a team member, or publishing a change -- without pulling the user out of context with a full-screen modal dialog.

```ts
import { CoarPopconfirm } from '@cocoar/vue-ui';
```

## Basic Usage

Wrap any button (or other trigger) in `CoarPopconfirm`. When the trigger is clicked, a small confirmation panel appears nearby with confirm and cancel actions.

## Variants

Use `confirmVariant="danger"` for destructive operations to make the risk visually clear. The `"primary"` variant (default) suits non-destructive confirmations like publishing or saving.

## Custom Labels

Replace the default "OK" / "Cancel" labels with language that describes the actual action. Specific labels like "Yes, remove" and "Keep member" help users make confident decisions.

## Placement

Control which side of the trigger the confirmation panel appears on. Pick the placement that best avoids clipping against viewport edges in your layout.

::: info Popconfirm vs Dialog
Use **Popconfirm** for quick inline confirmations that keep the user in context. Use **Dialog** when the confirmation needs a longer explanation, additional form fields, or when the action affects multiple items.
:::

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `message` | `string` | required | Confirmation message body |
| `title` | `string` | `''` | Optional title above the message |
| `confirmText` | `string` | `'OK'` | Confirm button label |
| `cancelText` | `string` | `'Cancel'` | Cancel button label |
| `confirmVariant` | `'primary' \| 'danger'` | `'primary'` | Confirm button color variant |
| `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Preferred placement |
| `disabled` | `boolean` | `false` | Disable the popconfirm trigger |

### Events

| Event | Description |
|-------|-------------|
| `confirmed` | Emitted when the confirm button is clicked |
| `cancelled` | Emitted when the cancel button is clicked or overlay is dismissed |

### Slots

| Slot | Description |
|------|-------------|
| `default` | The trigger element that opens the popconfirm |

---

---
url: /components/toast.md
---
# Toast

Non-blocking notification messages that slide in, deliver a brief update, and dismiss themselves. Toasts are perfect for confirming background actions -- a file uploaded, a record saved, or a network error encountered -- without interrupting the user's current workflow.

```ts
import { useToast } from '@cocoar/vue-ui';
```

## Variants

Four semantic variants communicate the nature of the notification at a glance. Click each button below to see the corresponding toast.

## Without Title

For straightforward messages, skip the title entirely. A single-line toast keeps the notification compact and fast to read.

## Duration Control

By default, toasts dismiss after 5 seconds (error toasts stay until dismissed). Pass a custom `duration` in milliseconds for longer messages, or set `duration: 0` to create a persistent toast that stays visible until the user explicitly dismisses it.

## Setup

Register the overlay plugin once in your app entry point:

```ts
// main.ts
import { CoarOverlayPlugin } from '@cocoar/vue-ui';

createApp(App)
  .use(CoarOverlayPlugin)
  .mount('#app');
```

Then add the toast container to your `App.vue`:

```vue
<template>
  <RouterView />
  <CoarToastContainer />
</template>
```

## API

### `useToast()` Methods

| Method | Parameters | Description |
|--------|-----------|-------------|
| `toast.show(config)` | `ToastConfig` | Show a fully custom toast |
| `toast.success(message, config?)` | `string, Partial<ToastConfig>?` | Show success toast |
| `toast.error(message, config?)` | `string, Partial<ToastConfig>?` | Show error toast (persistent by default) |
| `toast.warning(message, config?)` | `string, Partial<ToastConfig>?` | Show warning toast |
| `toast.info(message, config?)` | `string, Partial<ToastConfig>?` | Show info toast |
| `toast.dismissAll()` | — | Dismiss all visible toasts |

### `ToastConfig`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `message` | `string` | — | Toast message (required for `show()`) |
| `title` | `string` | `undefined` | Optional toast title |
| `duration` | `number` | `5000` (errors: `0`) | Duration in ms (0 = persistent) |
| `position` | `'top-right' \| 'top-left' \| 'top-center' \| 'bottom-right' \| 'bottom-left' \| 'bottom-center'` | `'top-right'` | Screen position |
| `dismissible` | `boolean` | `true` | Show close button |
| `showProgress` | `boolean` | `true` | Show progress bar |
| `action` | `{ label: string; callback: () => void }` | `undefined` | Optional action button |

## i18n Keys

These keys can be translated via [`@cocoar/vue-localization`](/foundations/localization/translations).

| Key | Default (English) | Used as |
|-----|-------------------|---------|
| `coar.ui.toast.dismiss` | `'Dismiss notification'` | Dismiss button `aria-label` |
| `coar.ui.toast.notifications` | `'Notifications'` | Toast container region `aria-label` |

---

---
url: /components/tooltip.md
---
# Tooltip

Tooltips are small, text-only hints that appear on hover or focus. They are the simplest way to add contextual labels to icon buttons, truncated text, or any element that benefits from a brief explanation. Use the `v-tooltip` directive on any element -- no wrapper component needed.

```ts
import { vTooltip } from '@cocoar/vue-ui';
```

## Basic Tooltip

Pass a string directly to `v-tooltip` for the quickest setup. Hover over any button below to see its tooltip.

## Placements

By default, tooltips appear above the trigger. Use the options object form to position them on any side. Pick the placement that avoids clipping in your layout.

## On Icon Buttons

Icon-only buttons look clean, but their meaning can be ambiguous. Adding a tooltip provides both a visual hint for sighted users and an accessible label for screen readers -- making tooltips essential for any icon-only control.

## On Any Element

`v-tooltip` is a directive, so it works on any HTML element -- spans, icons, code snippets, or custom components. No special wrapper needed.

::: tip Tooltip vs Popover
Use **Tooltip** for short, non-interactive text hints on hover or focus. Use **Popover** for rich interactive content that opens on click. Tooltips are text-only and disappear when the pointer leaves; popovers can hold buttons, forms, and full HTML.
:::

## API

### `v-tooltip` Options

The directive accepts either a plain string or an options object:

```vue
<!-- String shorthand -->
<CoarButton v-tooltip="'Save changes'">Save</CoarButton>

<!-- Options object -->
<CoarButton v-tooltip="{ text: 'Delete item', placement: 'top' }">Delete</CoarButton>
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `text` | `string` | -- | Tooltip text (or pass string directly to the directive) |
| `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Preferred tooltip placement |
| `disabled` | `boolean` | `false` | Disable the tooltip |

---

---
url: /components/transitions.md
---
# Transitions

Pre-built Vue `<Transition>` wrappers that use the design system's motion tokens. Drop them in, toggle visibility, done — durations, easing, and `prefers-reduced-motion` are handled automatically.

```ts
import { CoarFade, CoarSlide, CoarScale, CoarCollapse } from '@cocoar/vue-ui';
```

## Fade

Simple opacity transition. Use for overlays, tooltips, and content toggling.

## Slide

Slides content in from a direction with a subtle opacity fade. Use for dropdowns, drawers, and notification panels.

## Scale

Scales content in with a slight bounce and fades out cleanly. Use for dialogs, popovers, and action confirmations.

## Collapse

Animates the actual height of content for smooth expand/collapse. Use for accordions, expandable sections, and progressive disclosure.

## Accessibility

All transition components respect `prefers-reduced-motion: reduce`. When the user has reduced motion enabled, the design system's duration tokens collapse to `0ms`, making all transitions instant.

## API

### Shared Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `duration` | `'fast' \| 'normal' \| 'slow'` | `'normal'` | Maps to `--coar-duration-*` tokens (100ms / 200ms / 300ms) |
| `appear` | `boolean` | `false` | Animate on initial render |

### CoarSlide Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `direction` | `'up' \| 'down' \| 'left' \| 'right'` | `'down'` | Slide direction |

### Slots

All transition components have a single default slot. The child element must support `v-if` or `v-show` for the transition to work.

```vue
<CoarFade>
  <div v-if="visible">I fade in and out</div>
</CoarFade>
```

---

---
url: /components/virtual-list.md
---
# Virtual List

`useVirtualList` is a framework-agnostic composable that returns the slice of rows currently inside the viewport (plus an overscan buffer). Use it to render very large lists without putting thousands of DOM nodes in the tree. It's the primitive behind [`CoarListbox`'s virtual mode](/components/listbox#virtual-scrolling), but is independently exported and usable in any Vue component that scrolls.

```ts
import { useVirtualList } from '@cocoar/vue-ui';
```

## Standalone example

The demo below is a plain `<div>` scroller — **no listbox involved**. 50,000 synthetic log lines are described by data, but only ~20 rows are ever in the DOM:

## When to reach for it

* Pre-loaded catalogs of a few thousand+ items that would otherwise jank the browser
* Chat history, timelines, command logs
* Large custom tables you build yourself (not for `CoarDataGrid`, which handles this internally)
* Any component with a scroll container where DOM-node count is the bottleneck

If your data is backend-paginated and can be filtered server-side, virtual scrolling is rarely necessary — the DOM stays small on its own.

## Usage

```ts
import { useTemplateRef } from 'vue';
import { useVirtualList } from '@cocoar/vue-ui';

const scrollRef = useTemplateRef<HTMLElement>('scrollRef');

const { virtualRows, totalSize, scrollToIndex } = useVirtualList({
  count: () => items.value.length,
  itemSize: 32,
  overscan: 5,
  scrollElement: scrollRef,
});
```

Template skeleton — a spacer establishes the full scroll height and each visible row is absolutely positioned at its offset:

```vue
<div ref="scrollRef" style="overflow: auto; height: 400px;">
  <div :style="{ height: totalSize + 'px', position: 'relative' }">
    <div
      v-for="row in virtualRows"
      :key="row.index"
      :style="{
        position: 'absolute', left: 0, right: 0,
        transform: `translateY(${row.start}px)`,
        height: row.size + 'px',
      }"
    >
      {{ items[row.index] }}
    </div>
  </div>
</div>
```

## Variable item heights

`itemSize` accepts either a fixed number or a per-index callback. Groups, headings, or mixed content get different heights while the cumulative-offset math stays O(log n) per scroll event:

```ts
useVirtualList({
  count: () => entries.value.length,
  itemSize: (index) => entries.value[index].isHeading ? 28 : 44,
  scrollElement: scrollRef,
});
```

## API

### `UseVirtualListOptions`

| Option | Type | Default | Description |
|---|---|---|---|
| `count` | `MaybeRefOrGetter<number>` | — | Total item count. Reactive — changes trigger a recomputation of the offset table. |
| `itemSize` | `MaybeRefOrGetter<number \| (index) => number>` | — | Fixed pixel height, or a per-index function for variable heights. |
| `overscan` | `MaybeRefOrGetter<number>` | `5` | Extra rows rendered above/below the viewport as a scroll buffer. |
| `scrollElement` | `Ref<HTMLElement \| null>` | — | The scrolling container. Attach via `useTemplateRef`. |

### Return value

| Field | Type | Description |
|---|---|---|
| `virtualRows` | `ComputedRef<VirtualRow[]>` | The rows currently in the viewport + overscan window. |
| `totalSize` | `ComputedRef<number>` | Sum of all item heights — bind this to your spacer's `height`. |
| `scrollToIndex` | `(index, align?) => void` | Programmatically scroll an index into view. `align`: `'auto'` (default), `'start'`, `'center'`, `'end'`. |
| `offsetFor` | `(index) => number` | Debug/test helper — returns the cumulative pixel offset for an index. |

### `VirtualRow`

| Field | Type | Description |
|---|---|---|
| `index` | `number` | Position in the underlying list (0-based). |
| `start` | `number` | Pixel offset from the top of the spacer. Use `translateY(start)`. |
| `size` | `number` | Row height in pixels. |

## Behavior notes

* **Fixed viewport:** the composable tracks the container's `clientHeight` on every scroll event and — when available — via a `ResizeObserver`. In environments without `ResizeObserver`, it falls back to the `window.resize` event.
* **SSR-safe:** the `ResizeObserver` and DOM access are all guarded; the composable returns empty rows until the scroll element is mounted.
* **Binary-search offset table:** `count` and `itemSize` are reactive. Changing them rebuilds the cumulative offset array (`O(n)` once); scroll events then binary-search (`O(log n)`) for the visible window.
* **Dynamic measurement** (rendering items and measuring their actual heights) is *not* supported — pick an `itemSize` or function that matches your row heights. For the common "some rows are 32px, some are 48px" case, per-index function is enough.

---

---
url: /components/drag-drop.md
---
# Drag & Drop

`useDragDrop` is a small, framework-agnostic composable wrapping HTML5 drag-and-drop with the same group / accept / canDrop semantics used by [`CoarListbox`](/components/listbox#drag-drop-between-lists) — but usable from any Vue component. It takes care of the fiddly bits (module-level payload registry, group matching, directional whitelists, source-side cleanup on accept) so your component only needs to wire events.

```ts
import { useDragDrop } from '@cocoar/vue-ui';
```

## Standalone example — custom Kanban board

The demo below is built from plain `<div>` columns + cards, using `useDragDrop` directly — **no Listbox involved**. Cards flow **Backlog → In progress → Done**; Backlog accepts no drops (not a target), Done accepts from everywhere, In progress only accepts from Backlog:

Each column is one component that wires the composable's `startDrag` / `endDrag` to its cards and `onDragOver` / `onDragLeave` / `onDrop` to itself:

```vue
<script setup lang="ts">
import { useDragDrop } from '@cocoar/vue-ui'

const dnd = useDragDrop<Card>({
  dragId: () => props.columnId,
  dragGroup: 'kanban',
  dragAccept: () => props.dragAccept,  // whitelist of upstream columns
  onDropAccept: ({ items }) => emit('items-add', { items }),
  onItemsRemove: ({ items }) => emit('items-remove', { items }),
})
</script>

<template>
  <div
    :class="{ 'over': dnd.isDragOver.value }"
    @dragover="dnd.onDragOver"
    @dragleave="dnd.onDragLeave"
    @drop="dnd.onDrop($event)"
  >
    <div
      v-for="card in cards"
      draggable="true"
      @dragstart="dnd.startDrag($event, [card])"
      @dragend="dnd.endDrag($event)"
    >{{ card.title }}</div>
  </div>
</template>
```

## Matching rules

A drop is accepted iff **all** of the following pass:

1. **`dragGroup`** on source and target is equal (or both unset). This is the fast coarse-matching layer.
2. **`dragAccept`** — if set on the target, the source's `dragId` must be in the list.
3. **`canDrop`** — if provided on the target, it must return `true` for the incoming payload.

Self-drops (drag within the same surface) bypass the group check but still honour `dragAccept` and `canDrop`. They also skip `onItemsRemove` — the source of truth already holds the item.

Visual feedback: when any rule fails during `dragover`, the composable sets `dropEffect = 'none'` (cursor shows "not allowed") and leaves `isDragOver` false — wire that ref to a CSS class for accurate hover highlighting.

## API

### `UseDragDropOptions<T>`

| Option | Type | Default | Description |
|---|---|---|---|
| `dragId` | `MaybeRefOrGetter<string \| undefined>` | — | Public identifier for this surface. Pair with another surface's `dragAccept` for directional flow. |
| `dragGroup` | `MaybeRefOrGetter<string \| undefined>` | — | Shared name linking compatible surfaces. Only surfaces sharing a group exchange items. |
| `dragAccept` | `MaybeRefOrGetter<string[] \| undefined>` | — | Whitelist of source `dragId`s this surface accepts. Unset = accept any source in the same `dragGroup`. |
| `canDrop` | `(payload) => boolean` | — | Runtime drop validation. `payload = { items, fromId, fromGroup, fromSelf }`. |
| `onDragStart` | `(items) => void` | — | Called after `startDrag` registers a drag. |
| `onDragEnd` | `({ items, dropped }) => void` | — | Called on `dragend` — `dropped: true` if a target consumed the payload. |
| `onDropAccept` | `(payload & { insertIndex }) => void` | — | Called on **this** surface when it accepts a drop. Update your source of truth here. |
| `onItemsRemove` | `({ items, toGroup }) => void` | — | Called on the **source** surface when another target consumed its payload — fires synchronously inside the target's `drop`. Update your source of truth here. |

### Return value

| Field | Type | Description |
|---|---|---|
| `instanceId` | `string` | Stable per-instance identifier (auto-generated). |
| `isDragOver` | `Ref<boolean>` | `true` while a compatible drag is hovering this surface. Wire to a CSS class. |
| `isDragging` | `Ref<boolean>` | `true` while this surface is the source of an in-flight drag. |
| `startDrag` | `(event, items) => boolean` | Call from `@dragstart` on a draggable element. Returns `false` for empty payloads. |
| `endDrag` | `(event) => void` | Call from `@dragend`. Cleans up the session and fires `onDragEnd`. |
| `onDragOver` | `(event) => void` | Call from the drop container's `@dragover`. |
| `onDragLeave` | `(event) => void` | Call from `@dragleave`. Ignores events whose relatedTarget is still inside the container. |
| `onDrop` | `(event, ctx?) => void` | Call from `@drop`. Optional `ctx.insertIndex` is forwarded to `onDropAccept`. |

## Patterns

**Two-way exchange** — both surfaces draggable + droppable + same `dragGroup`:

```ts
useDragDrop({ dragGroup: 'items', onDropAccept, onItemsRemove })
```

**One-way flow** — give each source a unique `dragId`, whitelist on the target:

```ts
// source (box1)
useDragDrop({ dragId: 'box1', dragGroup: 'flow' })
// target (box2) — only accepts from box1
useDragDrop({ dragGroup: 'flow', dragAccept: ['box1'], onDropAccept })
```

**Capacity limits** — reject in `canDrop`:

```ts
useDragDrop({
  dragGroup: 'roles',
  canDrop: ({ items }) => admins.value.length + items.length <= 5,
  onDropAccept,
})
```

**Integration with existing components** — `CoarListbox` uses this composable internally. If you're building a new component that needs the same drag semantics, reach for `useDragDrop` rather than reimplementing the registry.

## Custom drag ghosts

The browser's default drag image is a semi-transparent snapshot of the dragged element. That looks fine for small items but turns into a giant faded blob for a large card or a nested tree node. Two tiny helpers attached to the same package give you a styled ghost next to the cursor without the boilerplate of cloning, off-screen mounting, and cleanup.

```ts
import {
  setCoarDragImageFromElement,
  setCoarDragImageFromHtml,
} from '@cocoar/vue-ui';

function onDragStart(event: DragEvent) {
  setCoarDragImageFromElement(event, event.currentTarget as HTMLElement);
}
```

The helper clones the source element, sizes the clone to match the source's bounding box, mounts it off-screen (horizontally, because Chromium skips rendering elements that are entirely outside the viewport — and an unrendered ghost captures as an empty bitmap), calls `dataTransfer.setDragImage`, and removes the clone on the next macrotask so the browser has time to rasterise it.

For a free-form ghost that doesn't mirror an existing element, use the HTML variant:

```ts
setCoarDragImageFromHtml(event, `
  <div style="padding: 6px 10px; font-size: 12px;">
    Moving 3 items
  </div>
`);
```

### API

#### `setCoarDragImageFromElement(event, source, options?)`

| Argument | Type | Description |
|---|---|---|
| `event` | `DragEvent` | The `dragstart` event. Called synchronously inside the handler. |
| `source` | `HTMLElement` | Element to clone as the ghost. The live element is not visually disturbed. |
| `options` | `CoarDragImageOptions` | Optional styling overrides. See below. |

#### `setCoarDragImageFromHtml(event, html, options?)`

Same contract, but builds the ghost from a raw HTML string instead of cloning an element. Useful for "drag summary" previews (e.g. "Moving 3 items") that don't correspond to a single DOM node.

#### `CoarDragImageOptions`

| Option | Type | Default | Description |
|---|---|---|---|
| `offsetX` | `number` | `12` | Cursor offset within the ghost, in px. |
| `offsetY` | `number` | `12` | Cursor offset within the ghost, in px. |
| `className` | `string` | — | CSS class applied to the generated wrapper so consumers can theme the ghost. |
| `style` | `Partial<CSSStyleDeclaration>` | — | Inline styles merged onto the wrapper. Prefer `className` when possible. |
| `applyDefaultStyle` | `boolean` | `true` | Apply the default rounded-corner, drop-shadow, 0.9 opacity treatment. Set to `false` when the caller handles all styling via `className`. |

---

---
url: /components/fragment-parser.md
---
# Fragment Parser & Modal Routing

Parse URL fragments (hash portion) into structured routes with parameters. Combined with composables, this enables **deep-linkable modals** — open modals via URL, share links, and use browser back to close them.

::: info Separate Package

```bash
pnpm add @cocoar/vue-fragment-parser
```

:::

```ts
import {
  parseFragment,            // Core parser
  useFragmentNavigation,    // navigateToModal(), closeModal()
  useRoutedFragments,       // Reactive fragment parsing
  useRoutedModals,          // Auto dialog/modal from URL
  type DialogFragment,      // type: 'dialog' route config
  type ModalFragment,       // type: 'modal' route config
} from '@cocoar/vue-fragment-parser';
```

## Basic Usage

Define routes with path patterns and parse the current URL fragment:

```ts
import { parseFragment, type RoutedFragmentBase } from '@cocoar/vue-fragment-parser';

interface AppRoute extends RoutedFragmentBase {
  type: string;
  path: string | string[];
  options?: { requiresAuth?: boolean };
}

const routes: AppRoute[] = [
  { type: 'overview', path: 'overview' },
  { type: 'details', path: 'details/:id' },
  { type: 'edit', path: 'details/:id/edit' },
];

// URL: https://app.com/#details/42?tab=comments
const result = parseFragment('#details/42?tab=comments', routes);
// → [{ route: { type: 'details', ... }, params: { id: '42', tab: 'comments' }, fragment: '...' }]
```

## Path Parameters

Use `:param` syntax for dynamic segments (powered by `path-to-regexp`):

```ts
const routes = [
  { type: 'user', path: 'user/:userId' },
  { type: 'project', path: 'project/:projectId/task/:taskId' },
];

// #user/abc → params: { userId: 'abc' }
// #project/1/task/42 → params: { projectId: '1', taskId: '42' }
```

## Query Parameters

Query parameters are parsed automatically with JSON type coercion:

```ts
// #details/5?edit=true&count=3
// → params: { id: '5', edit: true, count: 3 }

// #overview?tags=["a","b"]
// → params: { tags: ['a', 'b'] }
```

## Multiple Fragments

Chain multiple fragments with `#` for composable routing:

```ts
// #details/5#confirm?force=true
const results = parseFragment('#details/5#confirm?force=true', routes);
// → Two parsed routes: details + confirm
```

## Array Paths

A single route can match multiple paths:

```ts
const routes = [
  { type: 'docs', path: ['overview', 'usage', 'examples'] },
];

// #overview → matches docs route
// #usage → matches docs route
// #examples → matches docs route
```

## Modal Routing

The fragment parser's main use case: **deep-linkable modals**. When a user double-clicks a grid row, the modal opens AND the URL updates. Copy-pasting that URL opens the same modal. Browser back closes it.

```
/todos                → just the list
/todos#todo-42        → list + detail modal for todo-42
/todos#todo-42?tab=2  → list + detail modal, comments tab selected
```

### How It Works

Three composables work together:

```
User clicks row
    ↓
navigateToModal('todo-42')         ← useFragmentNavigation
    ↓
URL changes to /todos#todo-42
    ↓
useRoutedFragments detects change  ← useRoutedFragments
    ↓
Parses fragment against routes
    ↓
useRoutedModals opens dialog       ← useRoutedModals
    ↓
User closes dialog (or browser back)
    ↓
Fragment removed from URL
```

### Step 1: Define Fragment Routes

Register which fragments should open components in your Vue Router config. Two types are supported:

* **`type: 'dialog'`** — Opens inside a `CoarDialog` shell (header, title, close button)
* **`type: 'modal'`** — Opens as a raw overlay (no shell, your component IS the entire modal)

```ts
// routes.ts
import type { RoutedOverlayFragment } from '@cocoar/vue-fragment-parser';

const routes = [
  {
    path: '/todos',
    component: () => import('./TodoList.vue'),
    meta: {
      routedFragments: [
        {
          type: 'dialog',
          path: ':todoId',
          component: () => import('./TodoDetail.vue'),
          dialogOptions: { title: 'Todo Details', size: 'l' },
        },
      ] satisfies RoutedOverlayFragment[],
    },
  },
];
```

### Step 2: Wire Up the List View

```vue
<!-- TodoList.vue -->
<script setup lang="ts">
import { useFragmentNavigation, useRoutedModals } from '@cocoar/vue-fragment-parser';

// Auto-open/close modals based on URL fragments
useRoutedModals();

// Navigate to modal on interaction
const { navigateToModal } = useFragmentNavigation();

builder.onRowDoubleClicked((event) => {
  navigateToModal(event.data.id);
});

// With query params:
// navigateToModal(event.data.id, { tab: 0 })
// → URL: #todo-42?tab=0
</script>
```

### Step 3: Build the Modal Content

The modal component receives fragment params as props, plus a `close` function:

```vue
<!-- TodoDetail.vue -->
<script setup lang="ts">
const props = defineProps<{
  todoId: string;       // from fragment path ':todoId'
  tab?: number;         // from query params '?tab=2'
  close: (result?: unknown) => void;
}>();
</script>

<template>
  <div>
    <h3>Todo: {{ todoId }}</h3>
    <button @click="close()">Done</button>
  </div>
</template>
```

### Deep-Linking

Copy the URL `https://app.com/todos#todo-42?tab=2` and paste it in a new browser tab. The page loads, the fragment is parsed, and the modal opens automatically with `todoId: 'todo-42'` and `tab: 2`.

### Browser Back & History

The modal system integrates with browser history:

* **Modal open** → creates a history entry (`/todos` → `/todos#todo-42`)
* **Modal close** (X button) → creates another entry (`/todos#todo-42` → `/todos`)
* **Browser Back** after close → goes back to `/todos#todo-42` → modal reopens
* **Browser Back** while modal is open → goes back to `/todos` → modal closes

This means users can navigate modal state with the browser's back/forward buttons, just like regular pages.

### Multiple Modals

By default, `navigateToModal` **replaces** the current fragment. Use `append: true` to open multiple modals at once:

```ts
// Opens modal, replaces any existing fragment
navigateToModal('todo-42');
// URL: /todos#todo-42

// Opens second modal alongside the first
navigateToModal('confirm', undefined, { append: true });
// URL: /todos#todo-42#confirm
```

Each fragment is matched independently. Closing one modal removes only its fragment.

## Composable API

### `useFragmentNavigation()`

```ts
const { navigateToModal, closeModal } = useFragmentNavigation();
```

| Method | Parameters | Description |
|--------|-----------|-------------|
| `navigateToModal(path, params?, options?)` | `string, Record<string, ...>?, { append?: boolean }?` | Set fragment in URL, opens modal. `append: true` for multi-modal. |
| `closeModal(path)` | `string` | Remove fragment from URL, closes modal |

### `useRoutedFragments(routes?)`

```ts
const { fragments } = useRoutedFragments();
```

Reactively parses `route.hash` against routes from `route.meta.routedFragments`. Returns `computed<ParsedRoute[]>`.

### `useRoutedModals()`

```ts
useRoutedModals();
```

Fire-and-forget composable. Watches fragments and manages the overlay lifecycle:

* **`type: 'dialog'`** → opens via `useDialog().open()` with `DialogConfig` (shell with header/title)
* **`type: 'modal'`** → opens via `getOverlayService().open()` with `OverlaySpec` (raw overlay, no shell)

Handles:

* Fragment appears → lazy-load component → open dialog/modal
* Fragment removed (close button, browser back) → close
* Closed by user → remove fragment from URL
* Page load with fragment → deep-link: opens immediately

## API

### `parseFragment<T>(fragment, routes)`

| Parameter | Type | Description |
|-----------|------|-------------|
| `fragment` | `string` | URL fragment string (with or without leading `#`) |
| `routes` | `T[]` | Array of route definitions |

**Returns:** `ParsedRoute<T>[]` — array of matched routes

### Types

```ts
interface RoutedFragmentBase<TOptions = unknown> {
  type: string;
  path: string | string[];
  options?: TOptions;
}

interface ParsedRoute<T extends RoutedFragmentBase> {
  params: Record<string, unknown>;  // Path + query parameters
  route: T;                          // Matched route config
  fragment: string;                  // Original fragment string
}
```

---

---
url: /components/markdown.md
---
# Markdown

Render markdown content with Cocoar Design System styling. The system is split into two packages: a framework-agnostic parser and a Vue component.

::: info Separate Packages

```bash
pnpm add @cocoar/vue-markdown @cocoar/vue-markdown-core
```

Then load the shared block stylesheet **once** at app entry, alongside `@cocoar/vue-ui/styles`:

```css
/* app/main.css */
@import "@cocoar/vue-ui/styles";
@import "@cocoar/vue-markdown/styles";
```

The same stylesheet is consumed by `@cocoar/vue-markdown-editor` — viewer and editor render identical output for every node type.
:::

## Quick Start

Parse a markdown string, then render it:

```vue
<template>
  <CoarMarkdown :doc="doc" />
</template>

<script setup lang="ts">
import { parse } from '@cocoar/vue-markdown-core';
import { CoarMarkdown } from '@cocoar/vue-markdown';

const doc = parse(`
# Hello World

This is **bold** and *italic* text with a [link](https://example.com).

- Item one
- Item two
- Item three
`, { gfm: true });
</script>
```

## Parsing (`@cocoar/vue-markdown-core`)

### `parse(markdown, options?)`

Converts a markdown string into a `MarkdownDocument` tree.

```ts
import { parse } from '@cocoar/vue-markdown-core';

const doc = parse('# Title\n\nParagraph text.', { gfm: true });
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `gfm` | `boolean` | `false` | Enable GitHub Flavored Markdown (tables, strikethrough, task lists) |

### `serialize(doc, options?)`

Convert a document tree back to a markdown string:

```ts
import { serialize } from '@cocoar/vue-markdown-core';

const markdown = serialize(doc, { gfm: true });
```

### `transform(doc, ...transforms)`

Apply transformations to the document tree:

```ts
import { parse, transform, type MarkdownTransform } from '@cocoar/vue-markdown-core';

const addPrefix: MarkdownTransform = (doc) => ({
  ...doc,
  nodes: doc.nodes.map(node => {
    if (node.type === 'heading') {
      return { ...node, text: `[Docs] ${node.text}` };
    }
    return node;
  }),
});

const doc = transform(parse(markdown), addPrefix);
```

## Rendering (`@cocoar/vue-markdown`)

### `CoarMarkdown`

| Prop | Type | Description |
|------|------|-------------|
| `doc` | `MarkdownDocument` | Pre-parsed markdown document |
| `renderers` | `MarkdownViewerRenderers` | *(optional)* Per-instance renderer override. See [Custom renderers](#custom-renderers-registry) below. |

### Custom renderers (registry)

Every node type — headings, paragraphs, code blocks, tables, lists, even inline marks like `<em>` — is rendered by a swappable Vue component. The package exports the full default registry so you can override **just one slot** while keeping the rest of the Cocoar look:

```vue
<script setup lang="ts">
import { CoarMarkdown, defaultMarkdownRenderers } from '@cocoar/vue-markdown';
import MyHighlightedCodeBlock from './MyHighlightedCodeBlock.vue';

const renderers = {
  ...defaultMarkdownRenderers,
  codeBlock: MyHighlightedCodeBlock,  // Swap just the code-block slot
};
</script>

<template>
  <CoarMarkdown :doc="doc" :renderers="renderers" />
</template>
```

For app-wide overrides, `provide` the registry once at startup:

```ts
import { MARKDOWN_RENDERERS_KEY, defaultMarkdownRenderers } from '@cocoar/vue-markdown';
app.provide(MARKDOWN_RENDERERS_KEY, {
  ...defaultMarkdownRenderers,
  codeBlock: MyHighlightedCodeBlock,
});
```

Resolution order: per-instance prop → app-level inject → built-in defaults.

#### Renderer contract

Each renderer receives:

```ts
interface MarkdownRendererProps {
  /** The AST node currently being rendered. */
  node: MarkdownNode;
  /** Recursive child renderer — call to render `node.children`. */
  renderChildren: () => VNode[];
  /** Render an arbitrary list of nodes through the registry. Used by `DefaultTable`
   *  to render each cell's inline content while keeping the `<thead>/<tbody>` shape
   *  under the renderer's control. */
  renderNodes: (nodes: readonly MarkdownNode[]) => VNode[];
}
```

A custom renderer is a regular Vue component that emits the right semantic HTML for its node type. Use `renderChildren()` for the typical "wrap children in a tag" case; reach for `renderNodes(...)` only when the rendered structure isn't a flat children list (the GFM table is the canonical example).

#### Why the registry matters

The same registry is consumed by `@cocoar/vue-markdown-editor`. Overriding `codeBlock` in your app's `provide` flips the rendering both in the viewer **and** in the editor's render mode (the cursor-out state of the in-editor code block). Output stays in sync without any duplicated wiring.

### Supported Elements

| Markdown | HTML | Notes |
|----------|------|-------|
| `# Heading` | `<h1>` - `<h6>` | With anchor IDs |
| `**bold**` | `<strong>` | |
| `*italic*` | `<em>` | |
| `` `code` `` | `<code>` | Inline code |
| Code blocks | `<CoarCodeBlock>` | With language highlighting |
| `[text](url)` | `<a>` | External links open in new tab |
| `![alt](src)` | `<img>` | Lazy loaded |
| `> quote` | `<blockquote>` | Styled with left border |
| Lists | `<ul>` / `<ol>` | Including task lists |
| Tables | `<CoarTable>` | GFM tables with alignment |
| `~~strike~~` | `<del>` | GFM strikethrough |
| `---` | `<hr>` | Thematic break |

### Links

Links are handled intelligently:

* **External** (`https://...`): Opens in new tab with `rel="noopener noreferrer"`
* **Hash anchors** (`#section`): Resolved relative to current page
* **Relative paths** (`./page`): Local navigation

## Node Types

```ts
type MarkdownNodeType =
  | 'heading' | 'paragraph' | 'blockquote'
  | 'list' | 'listItem'
  | 'codeBlock' | 'table' | 'tableRow' | 'tableCell'
  | 'thematicBreak' | 'lineBreak'
  | 'text' | 'emphasis' | 'strong' | 'strikethrough'
  | 'inlineCode' | 'link' | 'image';

interface MarkdownNode {
  id: string;
  type: MarkdownNodeType;
  children?: readonly MarkdownNode[];
  text?: string;
  attrs?: Record<string, unknown>;
  position?: MarkdownPosition;
}

interface MarkdownDocument {
  nodes: readonly MarkdownNode[];
}
```

## Theming

The markdown component uses CSS custom properties for theming:

```css
/* Override in your app */
.coar-markdown {
  --coar-markdown-text: var(--coar-text-neutral-primary);
  --coar-markdown-link: var(--coar-text-accent);
  --coar-markdown-border: var(--coar-border-neutral);
}
```

---

---
url: /components/markdown-editor.md
---
# Markdown Editor&#x20;

WYSIWYG Markdown editor for Vue 3 based on [Milkdown](https://milkdown.dev/) (Kit approach), styled with the Cocoar Design System. Markdown-first: lossless round-trip between text and editor state. Shares the same remark stack — and the same render registry — as `@cocoar/vue-markdown-core` and `<CoarMarkdown>`.

::: info Separate Package

```bash
pnpm add @cocoar/vue-markdown-editor @cocoar/vue-markdown @cocoar/vue-ui
```

`@cocoar/vue-markdown`, `@cocoar/vue-ui` and `vue` are peer dependencies. Milkdown is bundled as a regular dependency — no extra setup required. The peer-dep on `@cocoar/vue-markdown` is what makes the **shared rendering registry** work — code blocks, tables, etc. look identical here and in `<CoarMarkdown>`.

Import the stylesheets once at your app's entry — same pattern as `@cocoar/vue-ui`:

```css
/* app/main.css */
@import "@cocoar/vue-ui/styles";
@import "@cocoar/vue-markdown/styles";        /* ← shared block styles */
@import "@cocoar/vue-markdown-editor/styles"; /* ← editor-specific chrome */
```

:::

::: warning Preview release
The package is on the `0.0.x` line. The render layer, `v-model` contract, toolbar API, form-field integration, and code-block view/edit toggle are **stable enough to ship in internal Cocoar apps** — the source format is plain Markdown, so any content written today round-trips through future API changes.

Still missing for a `1.0`: link insertion dialog, image upload, placeholder text, and custom table edge-handles. See [TODO](#todo) below.
:::

## Basic Usage

The editor exposes a plain `v-model` for the markdown string and renders a floating toolbar on text selection.

```vue
<template>
  <CoarMarkdownEditor v-model="value" />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { CoarMarkdownEditor } from '@cocoar/vue-markdown-editor';

const value = ref('# Hello\n\nStart typing **markdown**.');
</script>
```

::: tip Sizing
The editor fills its parent container. Wrap it in a parent with explicit height (`height: 360px`, `flex: 1` inside a column flexbox, etc.).
:::

## Toolbar Modes

`toolbarMode` controls the layout. Three values:

| Value | Description |
|---|---|
| `'floating'` (default) | Appears on text selection, teleported to `<body>`, context-aware (text vs. table) |
| `'fixed'` | `CoarSidebar` collapsed with icon buttons and flyout submenus, persistent. Sits on any of the four edges — see `toolbarPosition` |
| `'both'` | Both active simultaneously |

When `toolbarMode` is `'fixed'` or `'both'`, `toolbarPosition` controls which edge the toolbar attaches to. All four edges are supported — `'left'` and `'right'` give a vertical icon column, `'top'` and `'bottom'` switch to a horizontal toolbar above or below the editor area. Flyout submenus open in the corresponding direction (right for `left`, downward for `top`, etc.).

```vue
<CoarMarkdownEditor
  v-model="value"
  toolbar-mode="fixed"
  toolbar-position="top"
/>
```

## Readonly

```vue
<CoarMarkdownEditor v-model="value" readonly />
```

In `readonly` mode the editor accepts no input, the floating toolbar is suppressed, and the sidebar buttons are inert. The fixed toolbar still renders so the layout stays stable when toggling between view and edit.

## Code blocks — view / edit toggle

Code blocks have a richer UX than the rest of the editor. When the cursor is **outside** a code block it renders as `CoarCodeBlock` with full Prism syntax highlighting — same component, same look as `<CoarMarkdown>` produces in the viewer. When the cursor moves **inside** the block it switches to plain editable mode plus a language selector at the top.

| State | What renders | Why |
|---|---|---|
| Cursor **outside** | `CoarCodeBlock` (Prism-highlighted, copy button, language label) | Read-mode aesthetic — matches the viewer |
| Cursor **inside** | Plain editable text + `CoarSelect` for the language | Editing on top of Prism-highlighted DOM is fragile (cursor jumps, IME issues). Plain text avoids that. |

Switching directions:

* **Render → edit**: hover the code block to reveal a small **Edit** button (top-right), or simply click into the text via PM's natural cursor placement
* **Edit → render**: click anywhere outside the code block. PM's selection moves out → the NodeView swaps back automatically

Supported languages match what `CoarCodeBlock` ships with: `typescript`, `javascript`, `json`, `css`, `scss`, `html`, `bash`, plus `''` (Plain text — no highlighting). The language string is persisted exactly as picked into the markdown fence (` ```json `).

::: tip Custom code-block renderer
The render-mode component is the registry's `codeBlock` slot. Override it in `provide(MARKDOWN_RENDERERS_KEY, { ...defaults, codeBlock: MyCustom })` and the editor's render mode picks up the same custom component without any extra wiring.
:::

## Form Integration

`CoarMarkdownEditor` is a full citizen of the Cocoar form ecosystem. Drop it inside `CoarFormField` and the label, error message, `aria-describedby` wiring, and `disabled` state propagate automatically — the same way `CoarTextInput`, `CoarSelect`, and `CoarScriptEditor` behave.

```vue
<template>
  <CoarFormField label="Body" :error="bodyError" hint="Markdown" required>
    <CoarMarkdownEditor v-model="form.body" />
  </CoarFormField>
</template>

<script setup lang="ts">
import { computed, reactive } from 'vue';
import { CoarFormField } from '@cocoar/vue-ui';
import { CoarMarkdownEditor } from '@cocoar/vue-markdown-editor';

const form = reactive({ body: '' });
const bodyError = computed(() => form.body.trim().length === 0 ? 'Body cannot be empty.' : '');
</script>
```

What gets auto-wired from the surrounding `<CoarFormField>`:

| Form-field state | Effect on the editor |
|---|---|
| `id` | Set as the editor wrapper's `id` (so `<label for="...">` association works) |
| `error` | Sets `aria-invalid="true"` and applies the error outline |
| `disabled` | Combined with the editor's own `readonly` prop — `disabled || readonly` controls editability. `disabled` also dims the editor and blocks pointer events |
| `messageId` | Set as `aria-describedby` so screen readers announce the form-field's error/hint when the editor is focused |

You can also pass these props directly without `CoarFormField` (`error`, `disabled`, `id`) — direct props win over the injected context.

## Text Color

Apply inline color to a selection. Click the **palette** button in the floating toolbar (or the sidebar item in fixed mode) to open the picker — pick a swatch from the 8-color palette or use the native browser color input for a custom hex value. The color persists to markdown as plain inline HTML so the document stays readable in any standard renderer:

```markdown
The quick <span style="color: #dc2626">red</span> fox.
```

The picker is rendered through the same overlay primitive (`menuPreset`) that powers menus, popovers, and sidebar flyouts: anchor-relative positioning, viewport flipping, scroll-reposition, plus outside-click and `Escape` dismissal — no bespoke layout or click-handling logic in the editor.

::: info Why a whitelist?
The viewer (`@cocoar/vue-markdown` and `@cocoar/vue-markdown-core`) and the editor share a single `sanitizeColor` helper that accepts only:

* Hex (`#rgb`, `#rrggbb`, with optional alpha)
* `rgb()` / `rgba()` and the modern space-separated form
* `hsl()` / `hsla()` and the modern space-separated form
* A small set of named CSS colors (`red`, `blue`, …, `transparent`, `currentcolor`)

Anything else — `var(--token)`, `url(...)`, `expression(...)`, multi-declaration styles, foreign attributes — is rejected. A failed sanitization falls through to plain text in the viewer and keeps the surrounding content intact in the editor. There's no way for a hostile markdown payload to leak inline style beyond a single `color` declaration.

The picker palette (`COAR_TEXT_COLOR_PALETTE`) is exported so consumers can mirror it in custom UI.
:::

## Editor ↔ Viewer Parity

`<CoarMarkdownEditor>` and `<CoarMarkdown>` (the viewer) read the **same shared stylesheet** (`@cocoar/vue-markdown/styles`) so a markdown document looks pixel-identical whether you're editing it or rendering it for display. The two render through different DOM shapes — the editor's PM-managed contenteditable emits bare `<li>` / `<td>` / `<blockquote>` nodes inside a `.ProseMirror` wrapper, while the viewer emits class-tagged elements (`.coar-markdown-list-item`, etc.) — and the shared stylesheet covers both via parallel `:where(…)` selectors:

| Concern | Note |
|---|---|
| Vertical rhythm | Block margins apply to direct children of `.coar-markdown` (viewer) **and** `.coar-markdown .ProseMirror` (editor). |
| Typography | Heading sizes, blockquote inset, list indentation, `<strong>` weight (700), inline-code color, link underline — all defined once. |
| Tables | Zebra alternation uses `:nth-child(<n> of :not([data-is-header]))` to handle Milkdown's `<tr data-is-header>`-inside-`<tbody>` shape and the viewer's classic `<thead>` / `<tbody>` split with one rule. |
| Task lists | `<li data-item-type="task" data-checked="true">` in both panes; the visual checkbox is a `::before` pseudo-element (no native `<input>`). Completed items get the muted-color strikethrough. |
| Cell padding | `<p>` user-agent margin reset to `0` inside `<li>` / `<td>` / `<th>` — without the reset PM's auto-wrapped paragraph would add ~1em of vertical whitespace per row. |

If you embed the editor next to a viewer pane (the playground's "viewer pane" toggle does exactly this), the two should render the same source identically. Differences narrow down to design tokens you can override globally:

| Variable | Default | Effect |
|---|---|---|
| `--coar-markdown-heading-block-start` | `var(--coar-spacing-xl, 2rem)` | Extra space above every top-level heading. Lower for tighter docs, raise for more whitespace. |
| `--coar-markdown-space-2` | `var(--coar-spacing-m, 1rem)` | Default block-end margin. Drives paragraph / list / table / blockquote spacing. |
| `--coar-markdown-link` | `var(--coar-text-brand-primary)` | Link color (also applied to inline code). |
| `--coar-markdown-border` | `var(--coar-border-neutral-tertiary)` | Used by tables, blockquote, `<hr>`. |

## Restricting the Toolbar

Pass a `tools` array to limit which buttons the toolbar exposes. When omitted, all tools are shown. Order does not matter — the canonical order is preserved.

```vue
<!-- Minimal subset (matches the default rich-text editor in older Cocoar apps) -->
<CoarMarkdownEditor
  v-model="value"
  :tools="['bold', 'italic', 'bulletList', 'orderedList', 'outdent', 'indent', 'clearFormatting']"
/>

<!-- All tools except tables -->
<script setup lang="ts">
import { COAR_MARKDOWN_EDITOR_ALL_TOOLS } from '@cocoar/vue-markdown-editor';
const tools = COAR_MARKDOWN_EDITOR_ALL_TOOLS.filter(t => t !== 'table' && t !== 'tableOps');
</script>
<CoarMarkdownEditor v-model="value" :tools="tools" />
```

### Tool identifiers

| Tool | Description |
|---|---|
| `bold` `italic` `strikethrough` `inlineCode` | Inline marks |
| `textColor` | Text color picker — see [Text Color](#text-color) |
| `headings` | Heading flyout (H1–H6 + paragraph) |
| `bulletList` `orderedList` `taskList` | List variants |
| `indent` `outdent` | List nesting controls |
| `blockquote` `horizontalRule` | Block elements |
| `codeBlock` `table` | Insert blocks |
| `tableOps` | Insert/Delete row/col, shown contextually when cursor is inside a table |
| `clearFormatting` | Strip all marks + reset block to paragraph |
| `undo` `redo` | History |

::: info Markdown-only formatting
Only formatting that round-trips through Markdown is exposed. There is intentionally **no underline, font-family, font-size, or alignment** — these have no Markdown representation and would silently break round-trip persistence. **Text color** is the one exception: it round-trips as plain inline HTML through a strict whitelist sanitizer (see [Text Color](#text-color)).

When migrating from a richtext editor that exposed those tools, the closest Markdown-native substitutes are:

| Richtext tool | Markdown equivalent |
|---|---|
| Font size | `headings` — H1–H6 provide the typographic hierarchy |
| Bold / italic | `bold` / `italic` (no change) |
| Bulleted / numbered list | `bulletList` / `orderedList` |
| Indent / outdent (in lists) | `indent` / `outdent` |
| Clear / eraser | `clearFormatting` |
| Underline, color, alignment, font-family | *no equivalent — drop or accept embedded HTML* |
:::

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `modelValue` | `string` | `''` | Markdown content (use with `v-model`) |
| `readonly` | `boolean` | `false` | Disable editing (keeps the layout, suppresses the toolbar) |
| `disabled` | `boolean` | `false` | Disabled state — non-interactive, dimmed. Auto-picked up from `CoarFormField` |
| `error` | `boolean` | `false` | Error state — adds outline + `aria-invalid`. Auto-picked up from `CoarFormField.error` |
| `id` | `string` | *(auto)* | HTML id. Auto-generated if omitted; `CoarFormField`'s id takes precedence |
| `name` | `string` | *undefined* | Reflected as `data-name` for form-submission tooling |
| `required` | `boolean` | `false` | Sets `aria-required="true"` |
| `toolbarMode` | `'floating' \| 'fixed' \| 'both'` | `'floating'` | Toolbar layout |
| `toolbarPosition` | `'left' \| 'right' \| 'top' \| 'bottom'` | `'left'` | Toolbar edge when `toolbarMode` is `'fixed'` or `'both'`. `top`/`bottom` render a horizontal toolbar; flyouts open along the perpendicular axis. |
| `tools` | `CoarMarkdownEditorTool[]` | *all* | Whitelist of toolbar tools. See [Restricting the Toolbar](#restricting-the-toolbar) |

## Events

| Event | Payload | Description |
|---|---|---|
| `update:modelValue` | `string` | Fired on every internal markdown change. The editor de-duplicates — if a parent echoes the value back unchanged, no second update fires. |

## Floating-Toolbar Contexts

The floating toolbar swaps its contents based on what's selected:

| Selection | Toolbar |
|---|---|
| Text outside a table | Bold, Italic, Strikethrough, Inline Code, Headings flyout, Blockquote |
| Text inside a table cell | Row insert above/below, Column insert left/right, Delete cell, plus Bold/Italic/Code |

Detection runs on the ProseMirror selection state via `editorViewCtx`. CellSelections are ProseMirror-internal and don't fire `selectionchange` — the column- and row-handle toolbars referenced in the architecture below are not wired up yet (see [TODO](#todo)).

## Architecture Notes

### Why Milkdown (not TipTap, not Crepe)

| | Milkdown Kit | TipTap | Milkdown Crepe |
|---|---|---|---|
| Data format | **Markdown-first** (lossless round-trip) | JSON-first (lossy markdown export) | Markdown-first |
| Shared stack | Same as `@cocoar/vue-markdown-core`: unified@^11, remark-parse@^11, remark-gfm@^4 | No overlap | Same |
| Bundle | ~137 KB gzip (Kit) | Similar | ~2 MB (CodeMirror, KaTeX, etc.) |
| UI control | Full — headless, own components | Full — headless | Limited — predefined Notion-like UI |
| License | MIT | MIT (core), paid (collab) | MIT |

The Kit approach gives full control over UI while sharing the remark pipeline with the existing `@cocoar/vue-markdown-core` parser and `<CoarMarkdown>` viewer.

### Why no `tableBlock` plugin

`@milkdown/components/table-block` provides edge-handle buttons, button-group popups, and drag-to-reorder, but:

* Clicking in a cell auto-selects all content (breaks normal editing)
* Button-group popup overlaps with the floating toolbar
* CellSelection is internal to ProseMirror — `window.getSelection()` returns `type: "None"`, so `selectionchange` doesn't fire and detection is unreliable
* Requires ~200 lines of CSS to style properly

Table operations are instead exposed via the floating toolbar (when the cursor is inside a cell) and the sidebar toolbar (always available in fixed mode). Custom edge-handles will be built when a stable design is settled.

## TODO

* \[ ] Custom table edge-handles (column/row selection + dedicated toolbars)
* \[ ] Link insert/edit dialog
* \[ ] Image upload support
* \[ ] Placeholder text
* \[ ] Task list checkbox rendering and toggling
* \[ ] Use `computeOverlayCoordinates` for floating toolbar positioning instead of viewport clamping
* \[ ] Slash commands for block insertions
* \[ ] Block drag handle
* \[ ] Code block syntax highlighting (Prism or Shiki)

---

---
url: /components/script-editor.md
---
# Script Editor

A Monaco-based code editor for Vue 3 with Cocoar Design System theming. Supports **TypeScript, JavaScript, and JSON**, with first-class support for user-supplied type definitions (IntelliSense for your domain types).

::: info Separate Package

```bash
pnpm add @cocoar/vue-script-editor monaco-editor
```

`monaco-editor` is a peer dependency — consumers install and configure it themselves. This keeps the library bundle small and lets each app decide which Monaco languages and features to ship.
:::

## Worker Setup

Monaco offloads language services to Web Workers. Register them once **before any editor mounts**. Pick the pattern that matches your app's shape.

### SPA (client-only, Vite)

The common case. Register at application entry (`src/main.ts` or equivalent):

```ts
import EditorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker';
import TsWorker from 'monaco-editor/esm/vs/language/typescript/ts.worker?worker';
import JsonWorker from 'monaco-editor/esm/vs/language/json/json.worker?worker';

self.MonacoEnvironment = {
  getWorker(_id, label) {
    if (label === 'typescript' || label === 'javascript') return new TsWorker();
    if (label === 'json') return new JsonWorker();
    return new EditorWorker();
  },
};
```

Omit the JSON branch if your app never uses `language="json"`.

### SSR / static-generation (VitePress, Nuxt, Astro)

Monaco touches `window` and the DOM, so it cannot run during server-side rendering. Defer both worker registration and the editor import to `onMounted`, and wrap the template in `<ClientOnly>`:

```vue
<template>
  <ClientOnly>
    <component :is="Editor" v-if="Editor" v-model="code" />
  </ClientOnly>
</template>

<script setup lang="ts">
import { onMounted, ref, shallowRef, type Component } from 'vue';

const Editor = shallowRef<Component | null>(null);
const code = ref('// ...');

onMounted(async () => {
  const [mod, editorWorker, tsWorker, jsonWorker] = await Promise.all([
    import('@cocoar/vue-script-editor'),
    import('monaco-editor/esm/vs/editor/editor.worker?worker'),
    import('monaco-editor/esm/vs/language/typescript/ts.worker?worker'),
    import('monaco-editor/esm/vs/language/json/json.worker?worker'),
  ]);
  self.MonacoEnvironment = {
    getWorker(_id, label) {
      if (label === 'typescript' || label === 'javascript') return new tsWorker.default();
      if (label === 'json') return new jsonWorker.default();
      return new editorWorker.default();
    },
  };
  Editor.value = mod.CoarScriptEditor;
});
</script>
```

::: info Where does `<ClientOnly>` come from?
VitePress and Nuxt register `<ClientOnly>` globally. In a plain Vite SPA you don't need it — the SPA pattern above is simpler. In Astro use `client:only="vue"` on the component instead.
:::

Other bundlers (Webpack, Rollup, esbuild, or a CDN setup) use the same `self.MonacoEnvironment.getWorker` contract with different worker-import syntax — see [Monaco's official docs](https://github.com/microsoft/monaco-editor/tree/main/docs).

## Basic Usage

The editor exposes a plain `v-model` for the source text. Use `language` to choose between `'typescript'` (default), `'javascript'`, and `'json'`.

```vue
<template>
  <CoarScriptEditor v-model="code" language="typescript" style="height: 320px" />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { CoarScriptEditor } from '@cocoar/vue-script-editor';

const code = ref(`function greet(name: string) {\n  return \`Hello, \${name}\`;\n}\n`);
</script>
```

::: tip Sizing
The editor fills its parent container. Either pass a `height` prop (`"160px"`, `240`, `"40vh"`) or wrap in a parent with explicit height. The editor's own default `min-height: 200px` only applies when no parent height is set.
:::

## Form Integration

`CoarScriptEditor` is a full citizen of the Cocoar form ecosystem. Drop it inside `CoarFormField` and label, error message, `aria-describedby` wiring, and disabled state propagate automatically — the same way `CoarTextInput` and `CoarSelect` behave. Use `variant="inline"` for a compact form-field look (no line numbers, no gutter, tight padding) and `script-mode` to suppress the "top-level return/await" errors Monaco normally emits for full `.ts` programs.

`preamble` gives you per-editor type context without polluting the global TS namespace: the declaration lines render invisibly above the user script (hidden + locked), and `modelValue` only round-trips the user portion.

```vue
<template>
  <CoarFormField label="Handler script" :error="scriptError" required>
    <CoarScriptEditor
      v-model="form.script"
      variant="inline"
      language="typescript"
      height="180px"
      placeholder="// return query.filter(...)"
      script-mode
      preamble="declare const query: TodoQuery;"
      :extra-libs="[{ filePath: 'file:///types/todo-query.d.ts', content: todoQueryTypes }]"
    />
  </CoarFormField>
</template>
```

### `preamble` — per-editor type context

`preamble` is a hidden, auto-locked prefix prepended to the editor content. It's rendered invisibly, can't be edited or cursored into, and never appears in the emitted `modelValue`. The TypeScript service sees it as normal source, so IntelliSense resolves symbols declared inside it.

Typical use-case: your runtime executes the user's script as a function body with a specific set of bindings (`query`, `ctx`, `request`, …). Declare them in the preamble so the editor IntelliSense matches the runtime shape exactly:

```vue
<CoarScriptEditor
  v-model="form.script"
  preamble="declare const query: TodoQuery;\ndeclare const ctx: WorkflowCtx;"
/>
```

**When to use `preamble` vs `extraLibs`:**

| Signal                                            | Use `preamble`                           | Use `extraLibs`                    |
| ------------------------------------------------- | ---------------------------------------- | ---------------------------------- |
| Scope should be limited to this editor instance   | ✅                                        | ❌ (globally ambient)               |
| Different editors need different variable names   | ✅                                        | ❌                                  |
| App-wide shared domain types, interfaces          | ❌                                        | ✅                                  |
| You want the declaration to match a runtime shape | ✅ (declaration is literal code)          | 〰️ (works if wrapped in `declare global`) |

The two are complementary — most real forms use `extraLibs` for interfaces (`TodoQuery`, `Todo`, …) and `preamble` for the bindings that actually exist at runtime (`declare const query: TodoQuery`).

### `script-mode` — suppress script-body diagnostics

Enables suppression of the diagnostic codes TypeScript emits for "script body" constructs that are invalid in a full program but expected in an executable snippet:

| Code   | Suppressed meaning                                                            |
| ------ | ----------------------------------------------------------------------------- |
| `1108` | `return` statement outside a function                                         |
| `1208` | Cannot use `export` in a non-module (`export {}` forces module scope)          |
| `1375` | `await` allowed only in async functions                                       |
| `2304` | Cannot find name … (when the user relies on pre-injected globals)              |
| `2695` | Left-hand side of assignment is invalid                                       |
| `7027` | Unreachable code detected                                                     |

::: warning Global side-effect
`script-mode` calls `monaco.languages.typescript.typescriptDefaults.setDiagnosticsOptions` which is **shared across every TS/JS editor on the page**. The codes are additive — Cocoar merges them into the existing ignore list and never clears them, so toggling `script-mode` off does not restore the diagnostics. If your app mixes "full program" editors with "script body" editors, use the escape-hatch (`monaco.languages.typescript.typescriptDefaults.setDiagnosticsOptions`) from the consumer side for finer control.
:::

### Compact `variant="inline"`

Flipping `variant` to `'inline'` restyles Monaco for form-field use — no line numbers, no glyph margin, folding off, context menu off, tight 8px padding, word wrap on, and a hover/focus ring that matches `CoarTextInput`.

```vue
<CoarScriptEditor v-model="code" variant="inline" height="160px" />
```

Use `'editor'` (the default) whenever the editor is the page focus — IDE-like experience, line numbers, full gutter.

## Custom Type Definitions (`extraLibs`)

Inject `.d.ts` contents into the editor's TypeScript service to get autocomplete, hover types, and inline diagnostics for your domain objects — without polluting the global TS server.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { CoarScriptEditor, type CoarScriptEditorExtraLib } from '@cocoar/vue-script-editor';

const extraLibs: CoarScriptEditorExtraLib[] = [
  {
    content: `declare interface AppContext {
      user: { id: string; name: string };
      tenant: { id: string; name: string };
    }

    declare function getContext(): AppContext;`,
    filePath: 'file:///types/app-context.d.ts',
  },
];

const code = ref(`const ctx = getContext();\nconsole.log(ctx.user.name);\n`);
</script>

<template>
  <CoarScriptEditor v-model="code" language="typescript" :extra-libs="extraLibs" />
</template>
```

Each entry maps to `monaco.languages.typescript.typescriptDefaults.addExtraLib(...)` (or `javascriptDefaults` in JS mode). Use a stable, unique `filePath` per lib — Monaco keys its entries on the path.

## Runtime lib configuration

Monaco ships with a default lib set of `es5 + dom + webworker.importscripts + scripthost` — surfacing thousands of browser APIs (`document.*`, `fetch`, `localStorage`, `WScript`, …) in IntelliSense. For script editors backed by a non-browser runtime (e.g. Jint/Edge.js in a .NET host), autocompleting those APIs would lure users into writing code that crashes at execution time.

`CoarScriptEditor` therefore forces Monaco to `lib: ['es2024']` the first time it's mounted, dropping the browser-specific libs and keeping only the standard ECMAScript surface. It also applies to both TS and JS defaults and sets `target: ES2024`, `allowNonTsExtensions: true`, `noResolve: true`.

Host-specific globals (e.g. your runtime's `fetch`, `require`, `exit`) should be layered on top via `extraLibs` — opt-in and explicit, so what Monaco shows matches what Jint can run.

If you need a different lib set for non-Jint scenarios, call `monaco.languages.typescript.typescriptDefaults.setCompilerOptions(...)` yourself **after** the first `CoarScriptEditor` has mounted — `setCompilerOptions` is a module-global last-writer-wins, so your override takes effect immediately for every editor on the page.

::: warning `filePath` must start with `file:///`
Monaco's TypeScript service silently ignores declarations registered under any other URI scheme, so a value like `'types/foo.d.ts'` will compile without error but produce no IntelliSense. In development mode the component emits a `console.warn` when it detects this, but there's no runtime error — it's easy to miss in production. Always prefix with `file:///`.
:::

::: warning Untrusted content
`extraLibs.content` is parsed by Monaco's TypeScript service as a `.d.ts` file — it is not `eval`'d, so arbitrary code in `content` cannot execute in the browser. Declaration files *can* however expose surprising types / module augmentations. If the content comes from untrusted sources (e.g. another tenant's template), treat it as you would any other user-generated data: validate server-side and consider sandboxing the editor in an iframe with a restrictive CSP.
:::

## JSON mode

Set `language="json"` to edit JSON with Monaco's native JSON services — syntax validation, bracket matching, format-on-save, and optional schema-based IntelliSense all work out of the box.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { CoarScriptEditor } from '@cocoar/vue-script-editor';

const config = ref(`{
  "name": "example",
  "version": "1.0.0"
}`);
</script>

<template>
  <CoarScriptEditor v-model="config" language="json" />
</template>
```

::: tip JSON schemas
`extraLibs` is TypeScript-specific and is ignored in JSON mode. For schema-driven validation and autocompletion, call Monaco's JSON defaults directly — typically once at app entry:

```ts
import * as monaco from 'monaco-editor';

monaco.languages.json.jsonDefaults.setDiagnosticsOptions({
  validate: true,
  schemas: [
    {
      uri: 'https://my-app/schemas/config.json',
      fileMatch: ['*.json'],
      schema: { type: 'object', required: ['name'], properties: { name: { type: 'string' } } },
    },
  ],
});
```

If you need per-editor schema attachment, use the `getEditor()` escape hatch to access the model's URI and register matching schemas.
:::

## Read-only & Minimap

Both boolean flags default to `false`. Toggle `readonly` for viewer-style contexts and `minimap` when long files benefit from the overview gutter.

## Constrained Mode (Protected Lines)

Any line of the source that contains `// @locked` is protected: the user cannot edit it, merge it with a neighbour, or delete it. Everything else — other lines, file-top imports, helpers between functions — is freely editable.

The TypeScript language service sees the whole file as one document, so IntelliSense, Auto-Import, and domain types resolve exactly as in a normal `.ts` file. Markers are plain line comments, so the stored value is also a valid `.ts` file in any toolchain.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { CoarScriptEditor } from '@cocoar/vue-script-editor';

const code = ref(`declare interface Order {
  id: string;
  total: number;
}

function describeOrder(order: Order): string { // @locked
  return \`Order \${order.id}\`;
} // @locked
`);
</script>

<template>
  <CoarScriptEditor v-model="code" language="typescript" />
</template>
```

### Why line-based `@locked` (and not open/close tags)

Three real-world benefits:

* **Auto-Import works.** When the user types an unresolved type, TypeScript's quickfix inserts the `import` at the top of the file — a non-locked line, so the edit passes. Locked lines below simply shift down with the rest of the text; Monaco's native text handling does the bookkeeping for us.
* **No pairing errors.** Each `// @locked` marker is self-contained; you can't accidentally leave one open or nest them wrong. Copy-pasting a function across templates "just works".
* **Helpers fit naturally.** The user can declare local types, utility functions, or blank lines between the locked signatures without asking permission.

### The model value is the persistence format

`v-model` always contains the full source *including* the `// @locked` comments. Save and reload the exact same string — nothing to serialize:

```ts
// Save
localStorage.setItem('snippet', code.value);

// Load (later)
code.value = localStorage.getItem('snippet') ?? defaultTemplate;
```

::: tip Free mode
Without any `// @locked` markers the editor behaves like a regular code editor — no guards, no decorations. Adding a marker to any line turns enforcement on for just that line.
:::

### Reacting to rejected edits

Bind `@reject` to surface user feedback when an edit was rolled back:

```vue
<script setup lang="ts">
import type { CoarScriptEditorRejectEvent } from '@cocoar/vue-script-editor';

function onReject(event: CoarScriptEditorRejectEvent) {
  // Show a toast, trigger a shake animation, flash the affected line, etc.
  const line = event.range?.startLineNumber;
  toast.warn(`This line is protected.${line != null ? ` (line ${line})` : ''}`);
}
</script>

<template>
  <CoarScriptEditor v-model="code" @reject="onReject" />
</template>
```

### Authoring mode (`authoring` prop)

Template authors need to edit the protected parts too. Pass `:authoring="true"` to suspend enforcement: locked lines become editable, markers render at full size in a warm accent colour, and the author can add new markers or remove existing ones. Toggle the prop back to `false` and enforcement resumes with whatever markers are currently in the text.

```vue
<script setup lang="ts">
const editing = ref(false);
</script>

<template>
  <button @click="editing = !editing">
    {{ editing ? 'Exit authoring mode' : 'Enter authoring mode' }}
  </button>
  <CoarScriptEditor v-model="code" :authoring="editing" />
</template>
```

The demo above exposes the same toggle inline so you can flip between the modes.

### How it works

* **Marker detection**: `/\/\/\s*@locked\b/` — a line is locked if it contains `// @locked` anywhere. Match is case-sensitive; `@lockedx` does not count.
* **Protected range**: every locked line is protected inclusively, including its trailing newline. Backspace at the start of a line below a locked one, Delete at the end of a line above — both blocked.
* **Overlap check**: if any change in the batch intersects any protected range, the entire multi-cursor batch is rolled back via `editor.trigger('undo')`. An internal stack boundary keeps the rejected edit from coalescing with surrounding legal edits.
* **Cursor guard**: cursors that land inside a locked line snap to the nearer free boundary. Silenced when `authoring` is on.
* **Diagnostics filter**: error-severity markers emitted on locked lines are suppressed — an in-progress body that makes TypeScript mark the signature as broken won't surface that to the user, because they can't fix it anyway. Warnings and info remain; the filter also stands down in `authoring` mode so authors see everything.
* **Auto-features policy**: Monaco's `formatOnType`, `formatOnPaste`, and `linkedEditing` are turned off in constrained mode so cross-boundary reformats don't generate confusing rejections. Auto-Import (the lightbulb quickfix) is deliberately left on — its edits go to the file top, which is virtually always outside any lock.
* **Rejections**: `@reject` emits an object `{ reason, range? }` so you can surface a toast, shake animation, or highlight the affected line range. See the Events section below for the full payload.

::: warning Editor-option override
The auto-feature overrides above run on mount when constrained mode activates. If you call `editorRef.value?.getEditor().updateOptions({ formatOnType: true })` from consumer code, the override will re-apply next time constrained mode is set up (e.g. when `modelValue` gains or loses `// @locked` markers). If you need to re-enable these features for a constrained-mode editor, file an issue describing your use case — we may add an opt-out prop.
:::

### Styling

Two CSS variable groups, set per editor root and overridden automatically by the `coar-script-editor--authoring` class:

```css
.coar-script-editor {
  --coar-script-editor-marker-scale: 0.6;        /* relative to editor font */
  --coar-script-editor-marker-opacity: 0.45;
  --coar-script-editor-marker-color: var(--coar-text-neutral-tertiary);
  --coar-script-editor-locked-line-bg: /* subtle tint */;
}
.coar-script-editor--authoring {
  --coar-script-editor-marker-scale: 1;
  --coar-script-editor-marker-opacity: 0.85;
  --coar-script-editor-marker-color: var(--coar-text-warning);
  --coar-script-editor-locked-line-bg: /* warm tint */;
}
```

Override per-editor via inline style or globally via your theme stylesheet.

### Pure helpers

Available without mounting an editor — use them for validation, on the server, or in tests:

```ts
import {
  hasLockedMarkers,
  scanLockedLines,
  computeProtectedRanges,
  getEditableSegments,
  getSlots,
  getSlot,
  editIsProtected,
  snapOffsetAwayFromLocked,
  countLockedLines,
  isEverySegmentNonEmpty,
  validateSource,
  SLOT_MARKER_PATTERN,
} from '@cocoar/vue-script-editor';

// Structural queries
if (hasLockedMarkers(source)) { /* ... constrained ... */ }
const n = countLockedLines(source);
const lines = scanLockedLines(source);          // per locked line
const ranges = computeProtectedRanges(lines);   // merged blocks for overlap/snap

// Segmentation
const segments = getEditableSegments(source);   // stretches between locks

// Named slots (per-region access by name; see the Named slots section)
const allSlots = getSlots(source);              // { slotName: bodyContent }
const fn2Body = getSlot(source, 'fn2');         // string | undefined

// Submit-gating
if (isEverySegmentNonEmpty(source)) {
  submit(source);
}

// Soft validation (non-throwing, surfaces informational warnings)
const v: SourceValidation = validateSource(source);
// v.ok — no warnings surfaced
// v.lockedLineCount — number of // @locked lines
// v.segmentCount — number of editable stretches between locks
// v.warnings — e.g. "source starts with a locked line" (imports can't be added above)
```

The full type shapes:

```ts
interface SourceValidation {
  ok: boolean;
  lockedLineCount: number;
  segmentCount: number;
  warnings: string[];
}

interface LockedLine {
  lineIndex: number;        // 0-based
  lineStart: number;        // char offset of first line char
  lineEnd: number;          // offset of trailing `\n` (or source.length for last line)
  protectedStart: number;   // inclusive start of the protected range
  protectedEnd: number;     // inclusive end (covers the `\n`)
  snapBefore: number | null; // cursor-snap target before, null for first line
  snapAfter: number | null;  // cursor-snap target after, null for last line
  slotName?: string;        // name parsed from @slot:NAME on this locked line
}

interface ProtectedRange {
  start: number;
  end: number;
  snapBefore: number | null;
  snapAfter: number | null;
}
```

### Named slots (`@slot:NAME`)

Templates with multiple fillable regions — e.g. an event-handler script with three function bodies the user may or may not fill in — need a way to identify *which* body belongs to *which* function in the persisted source. Line-based locking alone tells you "this stretch is editable" but not "this is the body of `onLoad`".

The `@slot:NAME` attribute solves it. Placed on a `// @locked` line, it **names the editable segment that follows** (up to the next locked line or EOF):

```ts
function fn1(input) { // @locked @slot:fn1
} // @locked

function fn2(input) { // @locked @slot:fn2
} // @locked

function fn3(input) { // @locked @slot:fn3
  return input * 2;
} // @locked
```

Because the marker sits on a **locked line**, the user cannot delete or move it — the slot anchor survives whatever edits the user makes to the bodies. Auto-Import inserts at the file top shift all slot markers down with the rest of the text; the scanner re-derives positions on each call.

#### Reading slot content

Two helpers, both pure functions over the source string:

```ts
import { getSlots, getSlot } from '@cocoar/vue-script-editor';

// All slots as a dictionary, slot name → body content
const slots = getSlots(code.value);
// { fn1: '', fn2: '', fn3: '  return input * 2;' }

// A single slot, or `undefined` if the template does not declare it
const fn2Body = getSlot(code.value, 'fn2');
// '' — declared but not filled in

const missing = getSlot(code.value, 'fn4');
// undefined — template does not have this slot
```

* **Empty string** (`''`) = slot exists but body is whitespace-only (user skipped it). Check with `content.trim().length === 0`.
* **`undefined`** = slot not declared in the template. Lets callers distinguish "not part of the template" from "part of the template but empty".
* **First-wins on duplicates** — if two locked lines declare the same slot name, the first one's segment is returned. `validateSource()` warns on duplicates during template authoring.
* **Content trim rule**: leading and trailing blank lines are stripped; indentation of the remaining content is preserved, so multi-line bodies keep their shape.

#### Submit-gating by slot

```ts
const slots = getSlots(code.value);
const filled = Object.entries(slots)
  .filter(([, body]) => body.trim().length > 0)
  .map(([name]) => name);

if (filled.length === 0) {
  // Block save — user hasn't filled in anything.
}
```

#### Symmetric parsing on the server

The slot format is regex-matchable, so consumers running the saved script server-side (e.g. a C# Jint host) can extract the same info without shipping JS. The regex is exported as `SLOT_MARKER_PATTERN`:

```ts
import { SLOT_MARKER_PATTERN } from '@cocoar/vue-script-editor';
// '\/\/\s*@locked\b[^\n]*?@slot:([A-Za-z_][A-Za-z0-9_-]*)'
```

Drop the helper below into your backend project as-is. It matches the JS implementation one-to-one: same regexes, same first-wins rule on duplicates, same CRLF normalization, same blank-line trimming:

```csharp
using System.Text.RegularExpressions;

public static class ScriptSlots
{
    private static readonly Regex LockedMarker =
        new(@"//\s*@locked\b", RegexOptions.Compiled);

    private static readonly Regex SlotMarker =
        new(@"//\s*@locked\b[^\n]*?@slot:([A-Za-z_][A-Za-z0-9_-]*)", RegexOptions.Compiled);

    /// <summary>
    /// All named slots in the source keyed by slot name.
    /// Empty string = slot exists but body is whitespace-only.
    /// First-wins on duplicates.
    /// </summary>
    public static Dictionary<string, string> GetSlots(string source)
    {
        // Normalize CRLF so Windows-saved sources parse identically.
        var lines = source.Replace("\r\n", "\n").Split('\n');
        var result = new Dictionary<string, string>(StringComparer.Ordinal);

        for (int i = 0; i < lines.Length; i++)
        {
            var match = SlotMarker.Match(lines[i]);
            if (!match.Success) continue;

            var name = match.Groups[1].Value;
            if (result.ContainsKey(name)) continue; // first-wins

            // Find the next locked line (or EOF).
            int end = i + 1;
            while (end < lines.Length && !LockedMarker.IsMatch(lines[end])) end++;

            var bodyLines = lines.Skip(i + 1).Take(end - i - 1);
            result[name] = TrimBlankLines(string.Join("\n", bodyLines));
        }

        return result;
    }

    /// <summary>
    /// Content of a single slot. Returns null when no locked line declares that name.
    /// Returns "" when the slot exists but its body is empty — callers distinguish
    /// "not declared" from "declared but empty".
    /// </summary>
    public static string? GetSlot(string source, string name)
        => GetSlots(source).TryGetValue(name, out var v) ? v : null;

    private static string TrimBlankLines(string raw)
    {
        var lines = raw.Split('\n');
        int start = 0, end = lines.Length;
        while (start < end && string.IsNullOrWhiteSpace(lines[start])) start++;
        while (end > start && string.IsNullOrWhiteSpace(lines[end - 1])) end--;
        return string.Join("\n", lines.Skip(start).Take(end - start));
    }
}
```

With this helper, the Jint host can decide per-function whether to invoke it:

```csharp
var source = await dbContext.Scripts
    .Where(s => s.Id == id)
    .Select(s => s.SourceCode)
    .FirstAsync();

var slots = ScriptSlots.GetSlots(source);
var engine = new Engine().Execute(source);

foreach (var (name, body) in slots)
{
    if (!string.IsNullOrWhiteSpace(body))
        engine.Invoke(name, input);
}
```

Or pull a single handler directly:

```csharp
var onSave = ScriptSlots.GetSlot(source, "onSave");
if (!string.IsNullOrWhiteSpace(onSave))
    engine.Invoke("onSave", input);
```

The C# port mirrors the JS behaviour exactly, so you can reuse the 13 slot-related test cases from `LockedLineScanner.test.ts` as a parity check — same input strings must produce the same outputs.

#### Slot name rules

* Must match `[A-Za-z_][A-Za-z0-9_-]*` — starts with a letter or underscore, then letters / digits / underscores / hyphens.
* Names that don't match (e.g. `@slot:1bad`) are ignored silently — the locked line still locks, but no slot is registered.
* Must sit on a `// @locked` line. A lone `// @slot:X` on a free line is not recognised, because the user could delete it.

### Limitations (v1)

* **Languages**: TypeScript, JavaScript, JSON. Other Monaco-supported languages (CSS, HTML, Markdown, SQL, etc.) work too if you register their workers, but the component is only tested against these three.
* **Per-line granularity.** Locking a specific *character range* inside a line is not supported; the whole line is locked.
* **Monaco auto-edits that cross a boundary are blocked.** Format Document over a locked line, Rename Symbol touching both a locked and a free stretch — the whole operation is rolled back. Usually what you want; flip `authoring` on if not.
* **Authoring toggle + stale markers**: when `authoring` flips from `false` to `true`, previously-suppressed error markers on locked lines reappear only after the next TypeScript analysis pass (i.e. the next edit). This is a minor UX quirk of Monaco's marker model and does not affect correctness.

## API

### Props

| Prop           | Type                                    | Default        | Description                                                                              |
| -------------- | --------------------------------------- | -------------- | ---------------------------------------------------------------------------------------- |
| `modelValue`   | `string`                                | `''`           | Editor source. Any line containing `// @locked` is protected.                            |
| `authoring`    | `boolean`                               | `false`        | Authoring mode — suspends enforcement so template authors can modify locked lines or markers. |
| `language`     | `'typescript' \| 'javascript' \| 'json'` | `'typescript'` | Language mode. Changing it switches the model live.                                      |
| `readonly`     | `boolean`                               | `false`        | Viewer mode — user cannot edit but selection / copy / navigation still work.              |
| `disabled`     | `boolean`                               | `false`        | Non-interactive form state. Dimmed, pointer-events suppressed, picked up from `CoarFormField`. |
| `error`        | `boolean`                               | `false`        | Error state — red border. Auto-picked up from `CoarFormField.error`.                      |
| `placeholder`  | `string`                                | `''`           | Placeholder shown when the editor is empty and not focused.                               |
| `required`     | `boolean`                               | `false`        | Sets `aria-required="true"`. Does not enforce submission.                                |
| `autofocus`    | `boolean`                               | `false`        | Focus the editor after mount.                                                            |
| `id`           | `string`                                | `''`           | HTML id. Auto-generated if omitted; `CoarFormField.id` takes precedence.                  |
| `name`         | `string`                                | `''`           | Informational. Emitted as `data-name` (the editor is not a native form control).          |
| `height`       | `string \| number`                      | `undefined`    | Explicit height — CSS string (`"160px"`, `"40%"`) or pixels as number.                    |
| `variant`      | `'editor' \| 'inline'`                  | `'editor'`     | UI preset. `'editor'` = full IDE chrome. `'inline'` = compact form-field look.             |
| `lineNumbers`  | `boolean`                               | `undefined`    | Explicit line-numbers toggle. Overrides the variant default. Off-state keeps a small left margin so text doesn't hit the border. |
| `scriptMode`   | `boolean`                               | `false`        | Suppresses TS/JS diagnostics for "script body" code. Global side-effect — see Form Integration. |
| `preamble`     | `string`                                | `''`           | Hidden + locked prefix providing per-editor type context. Does not round-trip through `modelValue`. |
| `minimap`      | `boolean`                               | `false`        | Show the Monaco minimap gutter.                                                          |
| `theme`        | `'auto' \| 'light' \| 'dark'`           | `'auto'`       | `auto` tracks `.dark-mode` class on `<html>`/`<body>`, `data-theme="dark"`, then OS `prefers-color-scheme` — reactively. See Theming below. |
| `extraLibs`    | `CoarScriptEditorExtraLib[]`            | `[]`           | TypeScript declarations available for IntelliSense.                                      |

### Events

| Event               | Payload                              | Description                                                                          |
| ------------------- | ------------------------------------ | ------------------------------------------------------------------------------------ |
| `update:modelValue` | `string`                             | Full editor text. Markers stay in the value so it round-trips. Preamble is stripped before emit. |
| `reject`            | `CoarScriptEditorRejectEvent`        | Emitted when an edit was rolled back. See the payload shape below.                    |
| `focused`           | `void`                               | Fired when the editor widget gains focus (including suggestion popup).                |
| `blurred`           | `void`                               | Fired when the editor widget loses focus — use this to trigger form-touched state.    |

```ts
interface CoarScriptEditorRejectEvent {
  reason: CoarScriptEditorRejectReason;
  /** 1-based line range of the rejected edit (from Monaco). */
  range?: { startLineNumber: number; endLineNumber: number };
}

// Currently a single value; the type is an open union so consumers pattern-match forward-compatibly.
type CoarScriptEditorRejectReason = 'edit-overlaps-locked-line';
```

### Types

```ts
interface CoarScriptEditorExtraLib {
  content: string;   // .d.ts source
  filePath: string;  // e.g. 'file:///types/app-context.d.ts'
}

type CoarScriptEditorLanguage = 'typescript' | 'javascript' | 'json';
type CoarScriptEditorTheme = 'auto' | 'light' | 'dark';
```

### Exposed Methods

```ts
const editorRef = ref<InstanceType<typeof CoarScriptEditor> | null>(null);

// Standard helper
editorRef.value?.focus();

// Escape-hatch access to the raw Monaco editor instance and its text model
editorRef.value?.getEditor();
editorRef.value?.getModel();
```

Use `getEditor()` / `getModel()` for APIs not covered by the declarative props — markers, custom commands, folding ranges, formatting actions, etc.

## Theming

Two Monaco themes ship with the package — `coar-light` and `coar-dark`. They're registered via `monaco.editor.defineTheme` the first time any editor mounts.

### How `theme="auto"` decides

Monaco's theme is not CSS-driven — it's switched via an imperative `monaco.editor.setTheme()` call. `auto` mode watches the page for common dark-mode signals and calls `setTheme` whenever any of them changes. The resolution order is:

1. `.dark-mode` class on `<html>` or `<body>` → dark (Cocoar convention)
2. `.dark` class on `<html>` or `<body>` → dark
3. `data-theme="dark"` / `data-theme="light"` attribute on `<html>` or `<body>`
4. OS-level `prefers-color-scheme`

All four sources are watched live via `MutationObserver` + `matchMedia` listeners, so toggling your app's theme switcher flips the editor in the same frame.

::: tip Custom theme switchers
If your app uses a different convention (e.g. a Pinia store driving a root attribute), skip `auto` and bind the prop directly:

```vue
<CoarScriptEditor v-model="code" :theme="isDark ? 'dark' : 'light'" />
```

Monaco's `setTheme` is called whenever the prop changes, so this is the cheapest integration.
:::

The editor container surfaces these CSS custom properties:

```css
.coar-script-editor {
  --coar-border-neutral-tertiary: /* editor border */;
  --coar-background-neutral-primary: /* editor surface */;
  --coar-radius-xs: /* rounded corners */;
}
```

To register your own Monaco theme, call `monaco.editor.defineTheme('my-theme', {...})` anywhere in your app and pass it via the underlying editor instance (`editorRef.value?.getEditor().updateOptions({ theme: 'my-theme' })`).

### Font

The editor renders code in **Cascadia Code** (Microsoft's ligature-enabled coding font) with `Consolas`, `Monaco`, `Courier New` as fallback. Ligatures are enabled by default, so `!=`, `=>`, `===`, and `&&` render as combined glyphs. This matches `CoarCodeBlock` — both components share the same font stack.

Cascadia Code is bundled via `@cocoar/vue-ui/fonts` (weights 400 / 600 / 700). If your app imports that stylesheet — the standard Cocoar setup — the font loads automatically:

```ts
import '@cocoar/vue-ui/fonts'
import '@cocoar/vue-ui/styles'
```

If you don't import `@cocoar/vue-ui/fonts` (e.g. an app that only uses the script editor), Monaco falls back to Consolas/Monaco/Courier New. The editor keeps working; you just don't get the Cascadia Code glyphs or ligatures.

To override the font — e.g. to a custom corporate monospace — use the `getEditor()` escape hatch:

```ts
editorRef.value?.getEditor()?.updateOptions({
  fontFamily: "'JetBrains Mono', monospace",
  fontLigatures: true,
});
```

---

---
url: /components/data-grid.md
---
# Data Grid

A powerful data grid built on AG Grid with Cocoar theming. Configure columns, sorting, selection, and cell renderers through a fluent builder API — no raw AG Grid config needed.

::: info Separate Package
The Data Grid depends on AG Grid. Install it separately:

```bash
pnpm add @cocoar/vue-data-grid ag-grid-community ag-grid-vue3
```

:::

```ts
import { CoarDataGrid, CoarGridBuilder } from '@cocoar/vue-data-grid';
```

## Basic Usage

Define columns with `.field()`, `.header()`, and `.flex()` / `.width()`. Pass row data with `.rowData()`.

## Appearance

Add a border or elevation shadow to the grid. Toggle the checkboxes to see the effect.

## Column Types

Built-in renderers for dates, numbers, currency, tags, and icons — no custom cell components needed. Date, number, and currency columns are locale-aware and update reactively when the locale changes. Try the locale switcher in the nav bar.

| Method | Description |
|--------|-------------|
| `.field(name)` | Plain text column |
| `.date(field, config?)` | Locale-aware date display |
| `.number(field, config?)` | Locale-aware number display |
| `.currency(field, config?)` | Locale-aware currency display |
| `.tag(field, config)` | Renders a `CoarTag` with variant mapping or custom colors |
| `.icon(field, config?)` | Renders a `CoarIcon` |
| `.wrap(inner)` | Wraps any column builder with left/right decoration slots |

## Wrapper Column

Decorate any column with left and/or right slots — perfect for status indicators, action icons, or inline badges. The inner column keeps all its behavior (sort, filter, edit, `valueFormatter`, custom `cellRenderer`, …); only rendering gets an extra frame around it.

Each slot accepts one of three shapes:

```ts
// 1) Icon shorthand
.left({
  icon: (row) => row.starred ? 'star' : 'star-outline',
  color: (row) => row.starred ? '#f5a623' : '#ccc',
  tooltip: (row) => row.starred ? 'Unstar' : 'Star',
  onClick: (row, event) => toggleStar(row),
  show: (row) => row.visible,            // optional v-if gate
})

// 2) Any Vue component
// The component automatically receives `row: TData` as a prop —
// use `params(row)` to add or override props.
.right({
  component: CoarBadge,
  params: (row) => ({ content: String(row.unread) }),
  show: (row) => row.unread > 0,
})

// 3) Plain text
.right({ text: (row) => row.suffix })
```

### Multiple items per slot

Pass an array to stack several items in the same slot — each with its own `show()` gate, `onClick`, and tooltip. Items are rendered in order with a small gap.

```ts
.right([
  { icon: 'circle-alert',   color: '#dc2626', show: (r) => r.isCritical },
  { icon: 'message-circle', color: '#3b82f6', show: (r) => r.awaitingFeedback },
  { component: PriorityIndicator },  // receives `row` automatically
])
```

### Row-aware components

Every component slot automatically receives `row: TData` as a prop. This lets a single component decide what to render — icon, tag, or nothing — based on the full row:

```ts
const PriorityIndicator = defineComponent({
  props: { row: { type: Object as () => Message, required: true } },
  setup(props) {
    return () => {
      if (props.row.priority === 'high') return h(CoarTag, { variant: 'error' }, () => 'HIGH');
      if (props.row.priority === 'low')  return h(CoarIcon, { name: 'arrow-down' });
      return null;
    };
  },
});
```

Slot `onClick` handlers automatically call `event.stopPropagation()` so they don't trigger row-click or cell-click events on the grid.

## Row Selection

Toggle between single-click and multi-select with checkboxes.

## Reactive Data

Bind a `ref` with `.rowDataRef()` and the grid updates automatically when your data changes.

## Search (Quick Filter)

Enable the built-in search bar with `show-search`. It wires the search input to the builder's quick filter automatically.

### Custom Layout

Use `CoarDataGridSearch` and `CoarDataGrid` separately for full layout control. Connect them via `builder.quickFilterText(ref)`.

### Per-Column Configuration

Control how each column participates in quick filtering:

```ts
builder.columns([
  // Default: searches by String(value)
  (col) => col.field('name').header('Name'),

  // Custom text extraction (e.g., for arrays or objects)
  (col) => col.field('tags').quickFilter((tags) => tags.map(t => t.label).join(' ')),

  // Exclude from search
  (col) => col.field('id').quickFilter(false),
]);
```

### Custom Filter Function

Override the default per-column matching with a fully custom filter:

```ts
builder.quickFilterFn((searchValue, data) => {
  // searchValue is already lowercased and trimmed
  return data.name.toLowerCase().includes(searchValue)
    || data.email.toLowerCase().includes(searchValue);
});
```

### Search Highlighting

Enable text highlighting in grid cells using the CSS Custom Highlight API. Matching text is underlined without modifying the DOM.

```ts
builder
  .quickFilterText(searchRef)
  .searchHighlight()
```

The highlight style can be customized via CSS:

```css
::highlight(coar-search) {
  text-decoration: underline;
  text-decoration-color: #0066cc;
}
```

## I18n Headers

Column headers support runtime language switching via `@cocoar/vue-localization`. Pass a fallback text and an optional translation key:

```ts
builder.columns([
  // Static header
  (col) => col.field('name').header('Name'),

  // With i18n — falls back to 'Name' if no translation found
  (col) => col.field('name').header('Name', 'todo.grid.header.title'),
])
```

If `@cocoar/vue-localization` is not installed, the fallback text is always shown. Headers update automatically when the language changes at runtime.

## Auto Size

Control how columns are sized initially:

```ts
// Columns fill the grid width (most common)
builder.autoSize('fitGridWidth')

// Columns fit their content
builder.autoSize('fitCellContents')
```

## Tree Drag & Drop

Move rows between parents via drag & drop. Use `.rowDrag()` on the tree column, `.rowDragHighlight()` for visual feedback, and `.onRowDragEnd()` to handle the reparenting.

```ts
builder
  .treeData({ children: (r) => r.children ?? [], rowId: (r) => r.id })
  .openRows(openRows)
  .rowDragHighlight()
  .onRowDragEnd((event) => {
    const dragged = event.node.data;
    const target = event.overNode?.data;
    if (!dragged || !target) return;
    // API call or store mutation to reparent
    api.moveInto(dragged.id, target.id);
  });
```

## Tree Data

Display hierarchical data with expand/collapse. Use `treeData()` with nested children arrays and `openRows()` to control expansion. The `tree()` column type renders indentation, chevron toggle, and child count.

Search automatically expands matching branches — a parent stays visible when any descendant matches.

```ts
builder
  .treeData({
    children: (row) => row.children ?? [],
    rowId: (row) => row.id,
  })
  .openRows(openRowsRef)
  .columns([
    (col) => col.tree('name').header('Name').flex(1),  // tree column
    (col) => col.field('size').header('Size').width(100),
  ])
```

## Row Drag & Drop

Reorder rows via drag & drop. Use `.rowDrag()` on a column to show the drag handle, and `.rowDragManaged()` on the builder. Dragging is automatically disabled when a column sort is active.

```ts
builder
  .columns([
    (col) => col.field('name').rowDrag().flex(1),
  ])
  .rowDragManaged()
  .onRowDragEnd(() => {
    const newOrder = builder.getDisplayedRowData();
    store.updateOrder(newOrder);  // persist new order
  });
```

## Sorting

Make columns sortable and set a default sort order.

```ts
const builder = CoarGridBuilder.create<Row>()
  .columns([
    (col) => col.field('name').header('Name').flex(1).sortable(),
    (col) => col.number('salary').header('Salary').width(120).sortable(),
  ])
  .rowData(data)
  .defaultSort('name', 'asc');
```

## Column Persistence

Persist column widths, order, visibility, and sort in IndexedDB with `.persistColumnState(key)`.

**Width buckets:** The grid container width is rounded to buckets (default: 100px). Each bucket gets its own saved column layout, so different container sizes — switching monitors, collapsing a sidebar — each keep their own column widths. When no exact bucket exists, the nearest saved state is applied.

**Live sync:** Multiple grids with the same key synchronize column changes instantly. Resize, reorder, or hide a column in one grid and all others update immediately. Useful for comparison views with different filters on the same data structure.

Try it below — resize a column in Team A and watch Team B follow.

```ts
const builder = CoarGridBuilder.create<User>()
  .persistColumnState('my-users-grid')
  .columns([...])

// Optional: custom bucket size and debounce
.persistColumnState('my-grid', { bucketSize: 200, debounceMs: 1000 })

// Reset current bucket
builder.resetPersistedState()

// Reset all buckets
builder.resetPersistedStates()
```

### Cleanup

Persisted entries are timestamped on every read and write. Call `cleanupColumnStates()` once at application startup to remove stale entries and prevent unbounded growth:

```ts
// main.ts
import { cleanupColumnStates } from '@cocoar/vue-data-grid';

cleanupColumnStates(180); // Remove entries older than 6 months
```

## API

### CoarDataGrid Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `builder` | `CoarGridBuilder<T>` | — | Grid configuration builder (required) |
| `theme` | `Theme` | `cocoarTheme` | AG Grid theme override |
| `showSearch` | `boolean` | `false` | Show the search bar in the toolbar |
| `searchPlaceholder` | `string` | `'Search...'` | Placeholder for the search input |
| `searchSize` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Search input size |
| `search` | `string` | `''` | Search text (`v-model:search`) |
| `bordered` | `boolean` | `false` | Show a border around the grid |
| `elevated` | `boolean` | `false` | Add elevation shadow |

### CoarDataGrid Slots

| Slot | Description |
|------|-------------|
| `toolbar-left` | Content on the left side of the toolbar (e.g., title, icon) |
| `toolbar-right` | Content on the right side of the toolbar (e.g., buttons, actions) |

The toolbar appears automatically when `showSearch` is enabled or any `toolbar-*` slot is used. The search input fills available space (`flex: 1`). When search is disabled, a spacer pushes `toolbar-right` to the far right.

```vue
<!-- Search + actions -->
<CoarDataGrid :builder="builder" show-search bordered>
  <template #toolbar-left>
    <span style="font-weight: 600;">Users</span>
  </template>
  <template #toolbar-right>
    <CoarButton size="s">Add User</CoarButton>
  </template>
</CoarDataGrid>

<!-- Only toolbar actions, no search -->
<CoarDataGrid :builder="builder">
  <template #toolbar-right>
    <CoarButton size="s">Export</CoarButton>
  </template>
</CoarDataGrid>
```

### CoarGridBuilder Methods

| Method | Parameters | Description |
|--------|-----------|-------------|
| `.columns(defs)` | `ColumnDefFn<T>[]` | Define column configuration |
| `.rowData(data)` | `T[]` | Set static row data |
| `.rowDataRef(ref)` | `Ref<T[]>` | Bind reactive row data |
| `.quickFilterText(ref)` | `Ref<string>` | Bind search text for quick filtering |
| `.quickFilterFn(fn)` | `(search, data) => boolean` | Custom filter function override |
| `.searchHighlight()` | — | Highlight matching text via CSS Custom Highlight API |
| `.rowDragManaged()` | — | Enable managed drag & drop reordering |
| `.onRowDragEnd(fn)` | `(event) => void` | Handle drag end, persist new order |
| `.rowDragHighlight(opts?)` | `{ canDrop? }` | Visual drop target feedback with validation |
| `.getDisplayedRowData()` | — | Get row data in current display order |
| `.getTreeMeta(rowId)` | `string` | Get tree node depth, children info |
| `.treeData(config)` | `TreeDataConfig<T>` | Enable tree mode with nested children |
| `.openRows(ref)` | `Ref<string[]>` | Reactive ref of expanded row IDs |
| `.autoSize(strategy)` | `'fitGridWidth' \| 'fitCellContents'` | Column auto-sizing strategy |
| `.rowSelection(mode, opts?)` | `'single' \| 'multiple'` | Enable row selection |
| `.defaultSort(field, dir)` | `string, 'asc' \| 'desc'` | Set default sort column |
| `.persistColumnState(key, opts?)` | `string, ColumnPersistenceOptions?` | Persist column state in IndexedDB with width-based buckets |
| `.resetPersistedState(bucket?)` | `number?` | Reset persisted state for a specific bucket (defaults to current) |
| `.resetPersistedStates()` | — | Reset all persisted column states (all buckets) |
| `.rowClassRules(rules)` | `RowClassRules<T>` | Conditional row CSS classes |

### Standalone Functions

| Function | Parameters | Description |
|----------|-----------|-------------|
| `cleanupColumnStates(maxAgeDays)` | `number` | Remove persisted column states older than `maxAgeDays`. Call at app startup. |

### CoarGridColumnBuilder Methods

| Method | Parameters | Description |
|--------|-----------|-------------|
| `.field(name)` | `keyof T` | Set column data field |
| `.header(text, i18nKey?)` | `string, string?` | Set header text with optional i18n key |
| `.flex(value)` | `number` | Flexible column width |
| `.width(px)` | `number` | Fixed column width |
| `.fixedWidth(px)` | `number` | Non-resizable fixed width |
| `.sortable()` | — | Enable column sorting |
| `.quickFilter(fn)` | `boolean \| (value, data) => string` | Configure quick filter for column |
| `.date(field, config?)` | `keyof T, DateCellRendererConfig?` | Locale-aware date cell renderer |
| `.number(field, config?)` | `keyof T, NumberCellRendererConfig?` | Locale-aware number cell renderer |
| `.currency(field, config?)` | `keyof T, CurrencyCellRendererConfig?` | Locale-aware currency cell renderer |
| `.tag(field, config)` | `keyof T, TagConfig` | Tag cell renderer |
| `.icon(field, config?)` | `keyof T, IconConfig?` | Icon cell renderer |
| `.tree(field, config?)` | `keyof T, TreeCellRendererConfig?` | Tree column with expand/collapse |

---

---
url: /components/data-grid/editing.md
---
# Editing

In-cell editing is exposed through three builder methods that map directly onto AG Grid's editor lifecycle:

| Method | Level | Purpose |
|--------|-------|---------|
| `column.editable(value)` | column | Enable editing — `boolean` or `(row) => boolean` predicate |
| `column.cellEditorConfig(component, config)` | column | Plug in a custom Vue editor component (mirrors `cellRendererConfig`) |
| `gridBuilder.onCellValueChanged(handler)` | grid | React to a committed cell edit |

`editable()` and `cellEditorConfig()` are **orthogonal** — set both, otherwise the editor never opens. If you only set `editable(true)`, the cell uses AG Grid's built-in text editor.

## Default Editor

`.editable(true)` enables the default text editor. Editing starts on **double-click** (or pressing Enter / F2 with a cell focused). Enter commits, Escape cancels.

A row predicate gates editing per-row — locked items in the demo below skip the editor entirely:

```ts
(col) => col.field('name').editable(row => !row.locked)
```

`onCellValueChanged` fires once per committed edit and surfaces both the previous and new value. The demo updates a status line below the grid:

```ts
CoarGridBuilder.create<Person>()
  .columns([
    (col) => col.field('name').editable(row => !row.locked),
    (col) => col.number('amount').editable(row => !row.locked),
  ])
  .rowDataRef(data)
  .onCellValueChanged((event) => {
    saveField(event.data, event.colDef.field, event.newValue);
  });
```

## Custom Cell Editor

`cellEditorConfig(component, config)` accepts any Vue component and wraps your `config` object under `params.config` — the exact same convention as `cellRendererConfig`.

The component must follow AG Grid's [editor contract](https://www.ag-grid.com/vue-data-grid/component-cell-editor/): receive a single `params` prop and expose a `getValue()` method via `defineExpose`. Cocoar does not ship editor wrappers — building them is consumer territory, since the appropriate input control (text, select, autocomplete, date picker, custom widget) is application-specific.

The minimal `SelectCellEditor.vue` used above:

```vue
<template>
  <select ref="selectRef" v-model="value" style="width:100%;height:100%;">
    <option v-for="opt in options" :key="opt" :value="opt">{{ opt }}</option>
  </select>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue';
import type { ICellEditorParams } from 'ag-grid-community';

const props = defineProps<{
  params: ICellEditorParams<unknown, string> & { config: { options: string[] } };
}>();

const selectRef = ref<HTMLSelectElement | null>(null);
const value = ref(props.params.value ?? '');
const options = props.params.config.options;

onMounted(() => selectRef.value?.focus());

defineExpose({ getValue: () => value.value });
</script>
```

Wire it into a column:

```ts
(col) =>
  col.field('role')
    .editable(true)
    .cellEditorConfig(SelectCellEditor, {
      options: ['Engineer', 'Designer', 'Manager'],
    })
```

## Tips

**Single-click edit.** AG Grid's default is double-click. To enter edit on a single click, pass through the native option:

```ts
gridBuilder.option('singleClickEdit', true);
```

**Stop editing on focus loss.** Useful for forms where clicking outside should commit:

```ts
gridBuilder.stopEditingWhenCellsLoseFocus();
```

**Full-row editing.** Edit every cell in a row at once:

```ts
gridBuilder.fullRowEdit();
```

## API

### Column-level

| Method | Parameters | Description |
|--------|-----------|-------------|
| `.editable(value)` | `boolean \| (row: T) => boolean` | Enable editing statically or via row predicate. The predicate receives row data; rows without data (group rows etc.) return `false`. |
| `.cellEditorConfig(component, config)` | `Component, object` | Set custom cell editor. `config` is wrapped under `cellEditorParams.config`. |

### Grid-level

| Method | Parameters | Description |
|--------|-----------|-------------|
| `.onCellValueChanged(handler)` | `(event: CellValueChangedEvent<T>) => void` | Fires once per committed cell edit. `event.oldValue`, `event.newValue`, `event.data`, `event.colDef.field`. |
| `.fullRowEdit(value?)` | `boolean` | Enable full-row editing mode. |
| `.stopEditingWhenCellsLoseFocus(value?)` | `boolean` | Commit the edit when focus leaves the cell. |

---

---
url: /components/data-grid/text.md
---
# Text Column

`col.text(field, configurator?)` declares a text column whose editor is `<CoarTextInput>` — same visual language as forms, fitted into the cell.

```ts
import { CoarGridBuilder } from '@cocoar/vue-data-grid';

CoarGridBuilder.create<Person>().columns([
  (col) => col.text('name').editable(true),
  (col) => col.text('email', t => t.placeholder('user@example.com').maxLength(120)).editable(true),
])
```

Read-only display uses AG Grid's default text rendering — same as plain `.field()`. The shortcut adds:

* A configurable `CoarTextCellEditor` that opens on double-click / Enter / F2
* `sortable: true` by default

## Edit-mode flow

| Action | Result |
|--------|--------|
| Double-click cell (or Enter / F2) | Opens `CoarTextCellEditor` with focus on the input, existing value selected |
| Type a printable key on a focused cell | Opens editor seeded with that key (replace mode) |
| Tab | Commits + moves focus to the next editable cell, opening its editor automatically |
| Enter | Commits + stays |
| Escape | Cancels |

Toggles fire `cellValueChanged` like any other commit, so a single grid-level handler covers all column types.

## Example

```ts
CoarGridBuilder.create<Person>().columns([
  (col) => col.text('name', t => t.placeholder('Name').maxLength(80)).editable(true),
  (col) => col.text('email', t => t.placeholder('user@example.com').maxLength(120)).editable(true),
  (col) => col.field('role'),                                  // not editable
])
.stopEditingWhenCellsLoseFocus()
.onCellValueChanged(event => save(event.data, event.colDef.field, event.newValue));
```

## Layered overrides

```ts
// Replace the editor (drops the configurator)
col.text('name').editable(true).cellEditorConfig(MyCustomEditor, { ... })

// Keep the bundled editor, override editable
col.text('name').editable(row => !row.locked)
```

## API

### `col.text(field, configurator?)`

| Configurator method | Type | Description |
|--------|------|-------------|
| `.placeholder(value)` | `string` | Placeholder shown when input is empty |
| `.maxLength(value)` | `number` | Max input length |
| `.size(value)` | `'xs' \| 's' \| 'm' \| 'l'` | Input size (default: `'s'`) |
| `.prefix(value)` | `string` | Text shown before the input value |
| `.suffix(value)` | `string` | Text shown after the input value |

Editor commits via `getValue()` per AG Grid's contract — Tab / Enter / Escape are handled by AG Grid's native edit-mode logic. Combine with `gridBuilder.stopEditingWhenCellsLoseFocus()` so clicking outside also commits.

---

---
url: /components/data-grid/number.md
---
# Number Column

`col.number(field, …)` is locale-aware in both display and editing. Two forms — pick by need:

| Form | Effect |
|------|--------|
| `col.number('amount')` or `col.number('amount', { decimals: 2 })` | **Renderer only** — locale-formatted number, no editor (legacy / display-only) |
| `col.number('amount', n => n.decimals(2).min(0).max(100))` | **Renderer + editor** — same formatting plus `CoarNumberCellEditor` for in-cell editing |

The callback form bundles `CoarNumberCellEditor` automatically. Adding `.editable(true)` on the outer chain enables it.

## Example

```ts
CoarGridBuilder.create<Item>().columns([
  (col) => col.field('product').flex(1),
  (col) =>
    col
      .number('qty', n => n.min(0).max(9999).step(1).stepperButtons('both'))
      .editable(true),
  (col) =>
    col
      .number('price', n => n.decimals(2).min(0).step(0.01))
      .editable(true),
])
.stopEditingWhenCellsLoseFocus()
.onCellValueChanged(event => save(event.data, event.colDef.field, event.newValue));
```

The renderer uses `useL10n().fmtNumber()` so the display reactively follows the active locale (try the locale switcher in the docs nav). The editor uses Maskito for locale-aware parsing — `1.234,56` in `de-AT` and `1,234.56` in `en-US` both yield the same numeric value.

## Edit-mode flow

| Action | Result |
|--------|--------|
| Double-click cell (or Enter / F2) | Opens `CoarNumberCellEditor` with focus, existing value selected |
| Type a digit / `.` / `,` / `-` on a focused cell | Opens editor seeded with that key |
| Tab | Commits + moves to the next editable cell |
| Enter | Commits + stays |
| Escape | Cancels |

## Layered overrides

```ts
// Override editor (e.g. add custom validation)
col.number('qty', n => n.min(0)).editable(true).cellEditorConfig(MyOwnEditor, { ... })

// Override editable per-row
col.number('qty', n => n.min(0)).editable(row => !row.archived)
```

## API

### `col.number(field, configOrCallback?)`

**Config-object form** (legacy — renderer only):

| Property | Type | Description |
|----------|------|-------------|
| `decimals` | `number` | Number of decimal places |

**Callback form** (renderer + editor — `NumberColumnConfigurator`):

| Method | Type | Renderer / Editor | Description |
|--------|------|-------------------|-------------|
| `.decimals(value)` | `number` | both | Decimal places |
| `.min(value)` | `number` | editor | Minimum allowed value |
| `.max(value)` | `number` | editor | Maximum allowed value |
| `.step(value)` | `number` | editor | Step increment for arrows / stepper |
| `.stepperButtons(value)` | `'none' \| 'increment' \| 'decrement' \| 'both'` | editor | Stepper button mode |
| `.placeholder(value)` | `string` | editor | Placeholder text |
| `.size(value)` | `'xs' \| 's' \| 'm' \| 'l'` | editor | Input size (default: `'s'`) |

Editor commits via `getValue()` returning a `number | null`. Combine with `gridBuilder.stopEditingWhenCellsLoseFocus()` so clicking outside also commits.

---

---
url: /components/data-grid/select.md
---
# Select Column

`col.select(field, configurator)` declares a select column whose renderer shows the **label** of the matched option and whose editor is `<CoarSelect>` — same visual language as forms, with the dropdown teleported to `<body>` so it can overflow the cell freely.

```ts
import { CoarGridBuilder } from '@cocoar/vue-data-grid';

const ROLES = [
  { value: 'eng', label: 'Engineer' },
  { value: 'des', label: 'Designer' },
  { value: 'mgr', label: 'Manager' },
];

CoarGridBuilder.create<Person>().columns([
  (col) => col.field('name').flex(1),
  (col) => col.select('role', s => s.options(ROLES)).editable(true),
])
```

The configurator's `options` is required — there's no useful "select column without options".

## Edit-mode flow

| Action | Result |
|--------|--------|
| Double-click cell (or Enter / F2) | Opens `CoarSelectCellEditor` and **auto-opens the dropdown** via `afterGuiAttached` |
| Click an option (or Enter on highlighted) | Auto-commits + exits edit mode in one step |
| Up / Down | Highlight previous / next option |
| Type a character (when `searchable: true`) | Filters the option list |
| Escape | Closes dropdown; pressing again cancels edit |

The auto-commit is intentional — for a select, picking an option **is** the edit. Tab-through-edit-mode still works on the surrounding cells; the select cell just commits faster than free-form text would.

## Example

```ts
CoarGridBuilder.create<Person>().columns([
  (col) => col.field('name').flex(1),

  // simple
  (col) => col.select('role', s => s.options(ROLES)).editable(true),

  // clearable + per-row gating (archived rows are read-only)
  (col) =>
    col.select('status', s => s.options(STATUSES).clearable())
       .editable(row => row.status !== 'archived'),

  // searchable for long lists
  (col) =>
    col.select('country', s => s.options(COUNTRIES).searchable())
       .editable(true),
])
.stopEditingWhenCellsLoseFocus();
```

## Row-aware options

Pass a function instead of a static array to compute options per row:

```ts
col.select('parent', s =>
  s.options(row => allowedParents(row.type))
).editable(true)
```

Both renderer (label lookup) and editor (dropdown options) call the function with the current row, so display and edit stay consistent.

## Layered overrides

```ts
// Replace the editor entirely (drops the configurator)
col.select('role', s => s.options(ROLES))
   .editable(true)
   .cellEditorConfig(MyCustomSelect, { … })

// Keep the bundled renderer + editor, override editable
col.select('role', s => s.options(ROLES)).editable(false)
```

## API

### `col.select(field, configurator)`

| Configurator method | Type | Description |
|--------|------|-------------|
| `.options(value)` | `CoarSelectOption<T>[] \| (row) => CoarSelectOption<T>[]` | **Required.** Static array or per-row function. |
| `.clearable(value?)` | `boolean = true` | Show a clear button in the editor |
| `.searchable(value?)` | `boolean = true` | Enable search/filter in the dropdown |
| `.placeholder(value)` | `string` | Placeholder shown when no value is selected |
| `.searchPlaceholder(value)` | `string` | Search-input placeholder (used with `.searchable()`) |
| `.size(value)` | `'xs' \| 's' \| 'm' \| 'l'` | Trigger size (default: `'s'`) |

`CoarSelectOption<T>` is `{ value: T, label: string, disabled?: boolean, group?: string, icon?: string }`.

Editor commits via `getValue()` returning the option `value`. The dropdown panel is teleported to `<body>` (Coar overlay-host) so it can extend past the cell / grid boundaries without clipping.

---

---
url: /components/data-grid/multi-select.md
---
# Multi-Select & Tag-Select Columns&#x20;

Two column shortcuts for multi-value cells. Both store the cell value as `T[]` and share the same renderer — they differ only in the editor surface and which configurator options are available.

| | Editor | When to use |
|--|--|--|
| **`col.multiSelect()`** | `<CoarMultiSelect>` — standard trigger, dropdown shows all options with checkboxes | Curated option lists where the user picks N of M known values. Supports search, "Select all". |
| **`col.tagSelect()`** | `<CoarTagSelect>` — trigger renders selected values as removable chips inline; dropdown shows only not-yet-selected options | When the visual identity of selected values matters at-a-glance, or when you want `.allowCreate()` to let users add free-form values. |

```ts
import { CoarGridBuilder } from '@cocoar/vue-data-grid';

CoarGridBuilder.create<Person>().columns([
  (col) => col.field('name').flex(1),

  (col) => col.multiSelect('tags', s => s.options(TAGS).searchable().showSelectAll())
              .editable(true),

  (col) => col.tagSelect('skills', s => s.options(SKILLS).allowCreate().display('chips'))
              .editable(true),
])
```

## Edit-mode flow

| Action | Result |
|--------|--------|
| Double-click cell (or Enter / F2) | Opens the editor and **auto-opens the dropdown** via `afterGuiAttached` |
| Toggle a checkbox (multiSelect) / pick an option (tagSelect) | Updates the editor's working array. Dropdown stays open. |
| Click outside the dropdown / Tab / Enter | Commits — AG Grid pulls the final array via `getValue()` |
| Escape | Cancels (no commit) |

Unlike `col.select()` (which auto-commits on every pick because the single-value edit is *one* click), multi-value editors deliberately keep the dropdown open so the user can complete the selection. Focus-preservation prevents AG Grid's `stopEditingWhenCellsLoseFocus` from committing the array prematurely when the user clicks options in the body-teleported dropdown.

## Rendering

Both columns default to a comma-separated label list. Switch to chips via the configurator:

```ts
col.multiSelect('tags', s => s.options(TAGS).display('chips'))
col.tagSelect('skills', s => s.options(SKILLS).display('chips'))
```

The shared renderer (`CoarMultiSelectCellRenderer`) looks up labels from `options` — values that aren't in the option list (only possible via `col.tagSelect().allowCreate()`) fall back to `String(value)`.

## Example

## Row-aware options

Pass a function for per-row option lists — both renderer (label lookup) and editor (dropdown) call it with the current row:

```ts
col.multiSelect('perms', s => s.options(row => permsFor(row.role)))
   .editable(true)
```

## API

### `col.multiSelect(field, configurator)`

Cell value type: `T[]`.

| Configurator method | Type | Description |
|---|---|---|
| `.options(value)` | `CoarSelectOption<T>[] \| (row) => CoarSelectOption<T>[]` | **Required.** Static array or per-row function. |
| `.clearable(value?)` | `boolean = true` | Show a clear button in the editor |
| `.searchable(value?)` | `boolean = true` | Enable search/filter in the dropdown |
| `.showSelectAll(value?)` | `boolean = true` | Show a "Select all" row at the top of the dropdown |
| `.placeholder(value)` | `string` | Placeholder shown when no values are selected |
| `.searchPlaceholder(value)` | `string` | Search-input placeholder (used with `.searchable()`) |
| `.size(value)` | `'xs' \| 's' \| 'm' \| 'l'` | Trigger size (default: `'s'`) |
| `.display(value)` | `'text' \| 'chips'` | Renderer display mode (default: `'text'`) |

### `col.tagSelect(field, configurator)`

Cell value type: `T[]`. The cell renderer is shared with `col.multiSelect()`; only the editor differs.

| Configurator method | Type | Description |
|---|---|---|
| `.options(value)` | `CoarSelectOption<T>[] \| (row) => CoarSelectOption<T>[]` | **Required.** Static array or per-row function. |
| `.placeholder(value)` | `string` | Placeholder shown when no values are selected |
| `.searchPlaceholder(value)` | `string` | Search-input placeholder |
| `.size(value)` | `'xs' \| 's' \| 'm' \| 'l'` | Trigger size (default: `'s'`) |
| `.allowCreate(value?)` | `boolean = true` | Let the user type free-form values not in `options` |
| `.display(value)` | `'text' \| 'chips'` | Renderer display mode (default: `'text'`) |

`CoarSelectOption<T>` is `{ value: T, label: string, disabled?: boolean, group?: string, icon?: string }`.

## Layered overrides

Same escape-hatches as the other column shortcuts — chain `.cellEditorConfig(...)` or `.cellRendererConfig(...)` after the factory call to swap in custom components while keeping the rest of the column setup.

```ts
col.multiSelect('tags', s => s.options(TAGS))
   .editable(true)
   .cellEditorConfig(MyCustomMultiEditor, { /* ... */ })
```

---

---
url: /components/data-grid/date-columns.md
---
# Date Columns&#x20;

Three Temporal-typed column shortcuts for date / date-time / zoned-date-time cells. All three follow the same pattern: a renderer that formats locale-aware via `toLocaleString`, an editor that wraps the matching `<CoarPlainDatePicker>` / `<CoarPlainDateTimePicker>` / `<CoarZonedDateTimePicker>` component.

| | Cell value | Renderer format | Editor |
|--|--|--|--|
| **`col.plainDate()`** | `Temporal.PlainDate \| null` | `15. Mai 2026` (date-style: medium) | `CoarPlainDatePicker` |
| **`col.plainDateTime()`** | `Temporal.PlainDateTime \| null` | `15. Mai 2026, 14:30` (date-style: medium + time-style: short) | `CoarPlainDateTimePicker` |
| **`col.zonedDateTime()`** | `Temporal.ZonedDateTime \| null` | `15. Mai 2026, 14:30 GMT+2` (+ short zone-name suffix) | `CoarZonedDateTimePicker` |

```ts
import { CoarGridBuilder } from '@cocoar/vue-data-grid';
import { Temporal } from '@js-temporal/polyfill';

CoarGridBuilder.create<Task>().columns([
  (col) => col.plainDate('startsOn', d => d.highlightWeekends())
              .editable(true),

  (col) => col.plainDateTime('reminderAt')
              .editable(true),

  (col) => col.zonedDateTime('eventAt', d => d.timeZone('Europe/Vienna'))
              .editable(true),
])
```

::: info Temporal-only contract
All three column shortcuts require the cell value to be the matching `Temporal` type (or `null`). ISO strings, native `Date`, floating `Temporal.PlainDateTime` in a `zonedDateTime` column — all rejected: the renderer shows empty, the editor falls back to `null`. Convert at the data layer (typically in the row mapper that turns API responses into grid rows). This matches `@cocoar/vue-calendar`'s Temporal-only contract — when a row's date round-trips between the grid and the calendar, both sides agree on the type.

The legacy `col.date(field, config?)` shortcut (display-only, accepts `Date | string`) is unchanged for back-compat with existing consumer columns.
:::

## Edit-mode flow

| Action | Result |
|--------|--------|
| Double-click cell (or Enter / F2) | Opens the editor and focuses the picker's trigger. The picker handles its own open / navigate / select keystrokes. |
| Click outside / Tab / Enter (after selection) | AG Grid commits via `getValue()` — `Temporal.PlainDate` / `PlainDateTime` / `ZonedDateTime` (or `null` if cleared). |
| Escape | Cancels (no commit). |

Focus-preservation (capture-phase `mousedown` listener that `preventDefault`s on `.coar-overlay-host` targets) prevents AG Grid from committing prematurely while the user navigates the body-teleported picker panel.

## `col.plainDate(field, configurator?)`

| Configurator method | Type | Description |
|---|---|---|
| `.size(value)` | `'xs' \| 's' \| 'm' \| 'l'` | Trigger size (default: `'s'`) |
| `.clearable(value?)` | `boolean = true` | Show a clear button inside the picker (default: `true`) |
| `.min(value)` | `Temporal.PlainDate \| null` | Minimum selectable date |
| `.max(value)` | `Temporal.PlainDate \| null` | Maximum selectable date |
| `.showWeekNumbers(value?)` | `boolean = true` | Show ISO week numbers in the calendar panel |
| `.highlightWeekends(value?)` | `boolean = true` | Visually highlight Saturday + Sunday |
| `.markers(value)` | `CoarDateMarker[] \| (row) => CoarDateMarker[]` | Date markers (dot / ring / underline) |
| `.locale(value)` | `string` | Locale override (defaults to consumer-app locale via `useL10n()`) |

## `col.plainDateTime(field, configurator?)`

Same configurator surface as `col.plainDate()`, but `min` / `max` accept `Temporal.PlainDateTime`.

Use this when the time-of-day matters but the event has no fixed zone (calendar-local reminders, scheduled-locally tasks). For cross-zone events, use `col.zonedDateTime()`.

## `col.zonedDateTime(field, configurator?)`

| Configurator method | Type | Description |
|---|---|---|
| `.size(value)` | `'xs' \| 's' \| 'm' \| 'l'` | Trigger size (default: `'s'`) |
| `.clearable(value?)` | `boolean = true` | Show a clear button inside the picker (default: `true`) |
| `.min(value)` | `Temporal.ZonedDateTime \| null` | Minimum selectable instant |
| `.max(value)` | `Temporal.ZonedDateTime \| null` | Maximum selectable instant |
| `.showWeekNumbers(value?)` | `boolean = true` | Show ISO week numbers |
| `.highlightWeekends(value?)` | `boolean = true` | Highlight Saturday + Sunday |
| `.markers(value)` | `CoarDateMarker[] \| (row) => CoarDateMarker[]` | Date markers |
| `.locale(value)` | `string` | Locale override |
| `.timeZone(value)` | `string` | **Default IANA zone** for newly-created values (cell was empty before the edit). Existing values keep their own zone. |
| `.timezoneFilter(value)` | `string[]` | Wildcard filter patterns for the zone selector (e.g. `['Europe/*', 'America/*']`) |
| `.displayTimeZone(value)` | `string` | **Renderer-only.** Project every row's instant into this zone for display (e.g. `'Europe/Vienna'` to render every event in Vienna time for cross-zone coordination views). When omitted, each row renders in its own value's zone. |

The renderer formats each cell in its own zone — a row whose value lives in `America/New_York` displays the New York wallclock + a `GMT-5` (or `GMT-4` in summer) suffix, regardless of the user's browser zone. Cross-zone columns stay unambiguous at a glance.

## Row-aware markers

`markers` accepts a function for per-row decorations — useful when the calendar should highlight different dates depending on the row:

```ts
col.plainDate('startsOn', d =>
  d.markers(row => [
    { date: row.deadline, variant: 'underline', color: 'var(--coar-color-warning-bold)' },
  ])
).editable(true)
```

## Layered overrides

Same escape-hatches as the other column shortcuts:

```ts
col.plainDate('startsOn', d => d.size('s'))
   .editable(true)
   .cellEditorConfig(MyCustomDateEditor, { /* ... */ })
```

---

---
url: /components/data-grid/checkbox.md
---
# Checkbox Column

`col.checkbox(field, configurator?)` renders a `<CoarCheckbox>` in each cell — same visual language as forms, just sized to fit the row. The renderer is **always read-only**; interactivity comes from edit-mode, exactly like text/number/select columns.

```ts
import { CoarGridBuilder } from '@cocoar/vue-data-grid';

CoarGridBuilder.create<Task>().columns([
  (col) => col.checkbox('done').editable(true),
  (col) => col.field('title').flex(1),
])
```

## Edit-mode flow

Without `.editable()` the checkbox is a read-only indicator. Adding `.editable(true)` (or a row-predicate) opts the column into AG Grid's standard edit-mode flow:

| Action | Result |
|--------|--------|
| Double-click cell (or Enter / F2) | Opens `CoarCheckboxCellEditor` — interactive `<CoarCheckbox>` with focus on the input |
| Space | Toggles the checkbox |
| Tab | Commits + moves focus to the next editable cell, **opening its editor automatically** |
| Enter | Commits + stays |
| Escape | Cancels |

The Tab-through-edit-mode pattern is AG Grid's native data-entry workflow — keyboard users can fly through editable cells without ever touching the mouse. Pair with `gridBuilder.stopEditingWhenCellsLoseFocus()` so clicking outside also commits.

Toggles fire `cellValueChanged` like any other editor commit, so a single `gridBuilder.onCellValueChanged()` handler covers all column types — checkbox, text, number, custom editors.

## Editable + per-row gating

Pass a row-predicate to `.editable()` to disable the editor for individual rows. Locked rows render a read-only checkbox and can't be entered.

```ts
CoarGridBuilder.create<Task>().columns([
  (col) => col.checkbox('done').editable(row => !row.locked),
  (col) => col.field('task').flex(1),
  (col) => col.checkbox('locked'),                              // read-only indicator
])
.stopEditingWhenCellsLoseFocus()
.onCellValueChanged((event) => {
  if (event.colDef.field === 'done') save(event.data);
});
```

## States — read-only, editable, indeterminate

Three independent states, all using the same `col.checkbox()` shortcut:

* **Read-only:** omit `.editable()` — checkbox is rendered, edit-mode never opens.
* **Editable:** add `.editable(true)` or `.editable(row => …)`.
* **Indeterminate (tri-state):** pass `c.indeterminate(row => …)` in the configurator. Useful for "partial" or "in-progress" states where the row's value isn't a clean true/false. The indeterminate state is shown in both renderer and editor.

```ts
col.checkbox('rolloutComplete', c => c
  .indeterminate(row => row.partial && !row.rolloutComplete)
).editable(true)
```

## Layered overrides

The shortcut bundles renderer + editor with the configurator's options. Subsequent calls on the chain override (last-write-wins):

```ts
// Replace the renderer entirely (drops the configurator)
col.checkbox('done').cellRenderer(MyOwnCheckbox)

// Replace just the editor (e.g. a select-style "yes/no/maybe" widget)
col.checkbox('done').editable(true).cellEditorConfig(MyTriStateEditor, { ... })

// Keep the bundled renderer + editor, override editable
col.checkbox('done').editable(false)
```

## API

### `col.checkbox(field, configurator?)`

| Configurator method | Type | Description |
|--------|------|-------------|
| `.label(value)` | `string \| (row) => string` | Optional label rendered next to the checkbox (in both renderer and editor) |
| `.indeterminate(predicate)` | `(row) => boolean` | Tri-state indicator per row |
| `.size(value)` | `'xs' \| 's' \| 'm' \| 'l'` | Checkbox size (default: `'s'`) |

The configurator config is passed identically to both `CoarCheckboxCellRenderer` and `CoarCheckboxCellEditor`, so display and edit look the same — only behavior changes.

Interactive state comes from the outer chain:

| Outer chain | Result |
|-------------|--------|
| no `.editable()` | Read-only — edit-mode never opens |
| `.editable(true)` | Edit-mode opens on double-click / Enter / F2 |
| `.editable(false)` | Read-only |
| `.editable(row => …)` | Per-row predicate — edit-mode opens only when `true` |

Commit behavior: the editor exposes `getValue()` per AG Grid's contract. Tab/Enter/Escape are handled by AG Grid's native edit-mode logic. Combine with `gridBuilder.stopEditingWhenCellsLoseFocus()` so clicking outside the editor also commits.

---

---
url: /components/calendar.md
---
# Calendar&#x20;

A Vue 3 calendar built around four views — **Day**, **Week**, **Month**, **Agenda** — and a top-level [`<CoarCalendar>`](/components/calendar/coar-calendar) shell that wires them together with prev / today / next navigation and a 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
  CoarDayView,    useDayView,
  CoarWeekView,   useWeekView,
  CoarMonthView,  useMonthView,
  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';
```

## Two ways to use the calendar

### As a single shell

[`<CoarCalendar>`](/components/calendar/coar-calendar) is the all-in-one component: header with prev / today / next, a segmented-control view switcher, 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 all four views, 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 |
|---|---|---|---|
| Day | [`<CoarDayView>`](/components/calendar/day-view) | `useDayView()` | `CalendarBuilder` |
| Week | [`<CoarWeekView>`](/components/calendar/week-view) | `useWeekView()` | `CalendarBuilder` |
| Month | [`<CoarMonthView>`](/components/calendar/month-view) | `useMonthView()` | `CalendarBuilder` |
| Agenda | [`<CoarAgendaView>`](/components/calendar/agenda-view) | `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`. `expandSeries(...)` ships as a typed throwing stub today — the engine wires up post-launch, but the contract is stable now so consumers can build against it. |

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.

## 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 on every builder — the shell composer, every sub-view standalone, and the sub-builders inside the shell.

## 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 | Default | Purpose |
|---|---|---|
| `--coar-calendar-bg` | `#fff` | Background of every cell, header, and band. |
| `--coar-calendar-bg-today` | `rgba(37, 99, 235, 0.04)` | Today highlight on month cells + day-column tint. |
| `--coar-calendar-bg-weekend` | `#f6f7f9` | Weekend tint (Sat/Sun) on month cells + day-columns. |
| `--coar-calendar-bg-other-month` | `#fafafb` | Leading / trailing days outside the active month. |
| `--coar-calendar-border` | `#d1d5db` | Cell borders, header underlines, axis dividers. |
| `--coar-calendar-grid-line` | `#e3e5e9` | The slot-line gradient inside time-grid columns. |
| `--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. |

### 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`, `--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` |

### Example: dark theme

```css
.dark .coar-calendar,
.dark .coar-month-view,
.dark .coar-day-view,
.dark .coar-week-view,
.dark .coar-agenda-view {
  --coar-calendar-bg: #1a1c1f;
  --coar-calendar-bg-today: rgba(96, 165, 250, 0.08);
  --coar-calendar-bg-weekend: #14161a;
  --coar-calendar-bg-other-month: #111316;
  --coar-calendar-border: #2a2e34;
  --coar-calendar-grid-line: #25282d;
}
```

The DS-level tokens (`--coar-color-accent`, `--coar-text-base`, etc.) typically already flip in your design-system's dark theme — only the calendar-specific tokens need explicit overrides above.

::: 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)](/components/calendar/coar-calendar)** — the top-level shell + the full builder API reference.
* **[Day View](/components/calendar/day-view)** — single-day time-grid surface.
* **[Week View](/components/calendar/week-view)** — 7-day time-grid + all-day band.
* **[Month View](/components/calendar/month-view)** — 6×7 grid with multi-day bars + per-cell pills.
* **[Agenda View](/components/calendar/agenda-view)** — virtualized chronological list grouped by day.

---

---
url: /components/calendar/coar-calendar.md
---
# `<CoarCalendar>` — Composer&#x20;

`<CoarCalendar>` is the top-level shell that wires all four views (Day / Week / Month / Agenda) together with prev / today / next navigation and a view switcher. It's driven by the **builder** returned from `useCalendar()` — a single chainable surface that owns events, configuration, handlers, renderers, and an imperative `api` object.

The builder is **flat**: every setter lives directly on it, including view-specific ones (`timeRange`, `slotDuration` for Day / Week; `maxEventsPerCell` for Month; `agendaLengthDays` / `showEmptyDays` for Agenda). View-specific settings are no-ops outside their target view, so a single chained `.timeRange(...).maxEventsPerCell(...)` is fine — each one only takes effect when the matching view is active.

When you embed `<CoarDayView>` / `<CoarWeekView>` / `<CoarMonthView>` / `<CoarAgendaView>` standalone (without the shell), they consume the same builder type — `useDayView()` etc. are just shorthands that pre-set the matching `view` value.

## Basic usage

```ts
import { ref } from 'vue';
import { Temporal } from '@js-temporal/polyfill';
import {
  CoarCalendar,
  useCalendar,
  type CalendarEvent,
  type CalendarView,
} from '@cocoar/vue-calendar';

const events = ref<CalendarEvent[]>([
  {
    id: 'standup',
    // Daily standup at 09:00 IN VIENNA — store the human's intent
    // (local time + IANA zone), not a UTC instant. See
    // "Display vs source zone" below.
    start: Temporal.ZonedDateTime.from('2026-04-15T09:00:00[Europe/Vienna]'),
    end:   Temporal.ZonedDateTime.from('2026-04-15T09:30:00[Europe/Vienna]'),
    meta: { title: 'Daily standup', color: '#10b981' },
  },
  {
    id: 'devconf',
    start: Temporal.PlainDate.from('2026-04-13'),
    end:   Temporal.PlainDate.from('2026-04-16'),
    meta: { title: 'DevConf — Vienna', color: '#7c3aed' },
  },
]);
const view = ref<CalendarView>('week');
const date = ref('2026-04-15');

const { builder, api } = useCalendar();
builder
  .events(events)
  .view(view)              // caller-owned view ref (optional)
  .date(date)              // caller-owned date ref (optional)
  .timezone('Europe/Vienna') // DISPLAY zone — set this to a real IANA
                             // zone (or `detectBrowserTimezone()`).
                             // Don't use 'UTC' unless your users
                             // actually live in UTC.
  .onEventClick(({ event }) => console.log(event.id));
```

::: warning Don't use `'UTC'` as your display zone
UTC is a derived value (article 4: "store intent, derive math"). If your users live in Vienna, set `.timezone('Europe/Vienna')`. If you serve users worldwide, set `.timezone(detectBrowserTimezone())`. Setting the display zone to UTC makes 09:00 wall-time render at 11:00 in summer / 10:00 in winter — invisible bugs that surface when you ship.
:::

```html
<CoarCalendar :builder="builder" />
```

::: tip Why a builder?
Mirrors the `CoarGridBuilder` pattern from `<CoarDataGrid>`. One chainable surface keeps the consumer code linear, makes optional features (renderers, loaders, handlers) easy to register in any order, and gives us a single `api` object for imperative control.
:::

## Time range / Working hours

Constrain the visible hour range in `day` / `week` views via `timeRange([startHour, endHour])` (24-hour). Default is `[0, 24]` (full day). Events outside the range are still rendered into the all-day band when applicable.

## Locale & first day of week

Pass any BCP-47 locale via `locale(...)`. The first day of week is auto-detected from the locale (`en-US` → Sunday, `de-AT` / `fr-FR` → Monday, `ja-JP` → Sunday) and used by the `month` and `week` view windows. Override with `firstDayOfWeek(0..6)` (0 = Sunday … 6 = Saturday) when needed. Range labels and weekday names use the same locale.

## Display vs source zone

The calendar separates the **display zone** (where events are rendered on the grid) from each event's **source zone** (the zone the consumer captured when creating the event). This is the most common source of bugs when porting calendar code from string-based APIs, so it's worth being explicit:

* **`builder.timezone(tz)` is the DISPLAY zone.** Every column / row / hour-axis label resolves in this zone. Switching it (`builder.timezone('Asia/Tokyo')`) re-renders existing events at their Tokyo wall-clock time without mutating the events.

* **`event.start.timeZoneId` is the SOURCE zone** — what the human meant when they put the event on the calendar. A meeting in Vienna is `ZonedDateTime.from('2026-06-15T10:00:00[Europe/Vienna]')`, regardless of whose calendar it eventually lands on.

* **Cross-zone events are allowed.** `start.timeZoneId !== end.timeZoneId` is fine (e.g. a flight from Tokyo to Vienna is `start: …[Asia/Tokyo]`, `end: …[Europe/Vienna]`). The calendar renders both endpoints in the display zone using their underlying instant; the source zones are preserved on the event for round-tripping.

* **All-day events are intentionally zone-less.** A `PlainDate` carries no zone — that's the correct shape for a holiday, vacation, or anniversary. They appear on the calendar day with that name in every display zone, never shifting.

```ts
// Same builder, two display zones — the underlying event is identical.
builder.events([
  {
    id: 'sync',
    // SOURCE zone is Vienna — that's where the meeting was scheduled.
    start: Temporal.ZonedDateTime.from('2026-06-15T10:00:00[Europe/Vienna]'),
    end:   Temporal.ZonedDateTime.from('2026-06-15T11:00:00[Europe/Vienna]'),
  },
]);

builder.timezone('Europe/Vienna');  // renders 10:00–11:00 on Mon Jun 15
builder.timezone('Asia/Tokyo');     // same event renders 17:00–18:00 on Mon Jun 15
builder.timezone('America/Los_Angeles'); // same event renders 01:00–02:00 on Mon Jun 15
```

::: tip Where to set the display zone
Most apps want a single display zone matching the viewer's local zone (`Intl.DateTimeFormat().resolvedOptions().timeZone`). If you ship a "show in my zone" toggle, the only thing that needs to change is `builder.timezone(...)` — the events themselves stay put.
:::

## DST handling and the drop payload

Article 5 of the *Time in Software, Done Right* series demands that DST gaps and overlaps be handled **explicitly**. The library plumbs four policies through `.dstPolicy(...)`:

| Policy | Gap (e.g. 02:30 Vienna on spring-forward) | Overlap (e.g. 02:30 Vienna on fall-back) |
|---|---|---|
| `'compatible'` (default) | Shifts forward to the first valid minute | Picks the **earlier** instant |
| `'reject'` | Drop is vetoed — `canDrop=false`, snap-back fires | Same: vetoed |
| `'earlier'` | Same as compatible | Picks the earlier instant |
| `'later'` | Same as compatible | Picks the later instant |

Whatever policy fires, the resolved drop is reported to your `onEventDrop` handler with a `target.disambiguation` field — `'gap'`, `'overlap'`, or `null` for clean drops. **Consumer apps that want to surface DST resolutions should read this field** and show a toast / dialog accordingly:

```ts
builder.onEventDrop(({ event, next, target }) => {
  if (target.disambiguation === 'gap') {
    showToast(`DST gap — your meeting was shifted to ${next.start}`);
  } else if (target.disambiguation === 'overlap') {
    showToast(`DST fall-back — using the ${dstPolicy === 'later' ? 'second' : 'first'} 02:30`);
  }
  // ...persist next.start / next.end on your event store
});
```

Article 5 quote: *"You need to decide, and your code needs to handle it explicitly."* The lib gives you the explicit handle; ignoring it silently corrupts user expectations.

::: tip Cross-zone events keep their zones
`next.start.timeZoneId` and `next.end.timeZoneId` may differ — a Tokyo→Vienna flight stays Tokyo→Vienna across drag-and-drop. Persist both values verbatim; don't "normalise" to one zone.
:::

::: tip Undo / audit log: persist `original.displayZone` and `target.displayZone`
The drop payload carries the **user's viewing context** in two places:

* `original.displayZone` — the zone the calendar was rendering in when the drag started.
* `target.displayZone` — the zone the drop snapped in (usually the same; differs only if the user toggled `.timezone()` mid-drag).

Storing both alongside `next.start` / `next.end` lets you (a) replay the user's intent on undo without inheriting whatever zone they've toggled to since, and (b) write an audit log honest about "user moved this meeting AT 14:00 IN EUROPE/VIENNA". Article 3: deadlines are hard precisely because the wall-clock + the zone are inseparable. See `CalendarBasic.vue` demo for the canonical pattern.
:::

## Custom event rendering

Two ways to customise event rendering — pick whichever fits the consumer code better. **Slot wins over builder renderer** when both are present.

### Template slot

The `#event` slot replaces the default event card. The slot receives `{ event, view, layout?, item? }` so you can render differently per view. The same slot is forwarded to all four sub-views (and used as a fallback for month pills / bars when no specific `#pill` / `#multiDayBar` slot is supplied).

### Builder renderer

`builder.eventRenderer(...)` accepts three forms — register once, applies everywhere a slot isn't already supplied:

```ts
// (A) one component for all events
builder.eventRenderer(MyEventCard);

// (B) function returning a component — choose by event meta
builder.eventRenderer((ctx) =>
  ctx.event.meta?.kind === 'meeting' ? MeetingCard : DefaultCard,
);

// (C) function returning a VNode — fully custom h() output
builder.eventRenderer((ctx) =>
  h('div', { class: 'pill' }, ctx.event.id),
);
```

### Branching per layout variant

The same event can render in four very different visual shapes depending on the view it lands in:

| `ctx.layout.kind` | Where it appears | Visual |
|---|---|---|
| `'positioned'` | Day / Week time-grid | Card pinned to an hour, color-bar on the leading edge |
| `'allDayBar'` | Day / Week all-day band | Bar that spans multiple day-columns at the top of the time-grid |
| `'monthPill'` | Month cell (single-day event) | Rounded pill stacked inside the cell |
| `'monthBar'` | Month row (multi-day event) | Bar that spans across day-cells in a row |

`builder.eventRenderer((ctx) => …)` is invoked for **every** variant. Inspect `ctx.layout?.kind` and branch:

```ts
builder.eventRenderer((ctx) => {
  switch (ctx.layout?.kind) {
    case 'monthPill':
      return h('div', { class: 'fancy-pill' }, [
        h('span', '🎉'),
        h('span', ctx.event.meta.title),
      ]);
    case 'monthBar':
      return h('div', { class: 'fancy-bar' }, ctx.event.meta.title);
    case 'allDayBar':
      return h('div', { class: 'fancy-allday' }, ctx.event.meta.title);
    case 'positioned':
      return h('div', { class: 'fancy-card' }, [
        h('span', { class: 'time' }, ctx.event.start.toString()),
        h('span', ctx.event.meta.title),
      ]);
    default:
      // Agenda rows etc. — fall through to the lib's default by
      // returning `undefined`.
      return undefined;
  }
});
```

Returning `undefined` from any branch lets the lib fall back to its built-in default for that variant.

::: tip Template slot trumps the renderer
A `<template #event>` slot on `<CoarCalendar>` always wins over `builder.eventRenderer(...)`. Use the slot for the common case; reach for the renderer when you need a function (e.g. dispatch on `meta.kind` to pick a Vue component dynamically).
:::

`dayHeaderRenderer` is the only other renderer setter — it controls the per-day column header in week / month views and has its own dedicated `ctx` shape (`{ date, isToday, isWeekend }`), so it's a separate setter rather than a branch on `ctx.layout.kind`.

## Loading events on-demand

Backends with thousands of events benefit from loader mode — give the builder an async function and the calendar requests events for the visible window only, with caching + debouncing built in:

```ts
builder.eventsLoader(async (window) => {
  const res = await fetch(`/api/events?from=${window.start}&to=${window.end}`);
  return res.json();
});
```

The calendar:

* Watches the visible window and calls the loader whenever it changes.
* Debounces rapid view-nav (50 ms) — clicking next / prev / today in quick succession fires a single fetch for the window the user lands on.
* Caches results per `${view}|${timezone}|${start}|${end}` key. Going back to a previously-loaded window is instant. The display timezone is part of the key so a `.timezone()` toggle re-fetches (events near local midnight differ across zones).
* Tracks in-flight count via `api.loading` (a readonly `Ref<boolean>`).
* Exposes `api.refresh()` to invalidate the entire cache, and `api.refreshRange(start, end)` to invalidate only the window(s) that intersect a date range.

`events()` and `eventsLoader()` are mutually exclusive — calling one drops the other.

## Recurring events

`@cocoar/vue-calendar` expands recurring series at the visible-window boundary — the engine never sees occurrences outside the current view, so a series with `RRULE:FREQ=DAILY` from year 2000 doesn't pay 25 years of expansion cost when you mount the calendar today. Two source modes mirror non-recurring events:

```ts
import { Temporal } from '@js-temporal/polyfill';
import type { RecurringSeries } from '@cocoar/vue-calendar';

const series = ref<RecurringSeries[]>([
  {
    id: 'standup',
    rrule: 'FREQ=WEEKLY;BYDAY=MO,WE,FR',
    dtstart: Temporal.ZonedDateTime.from('2026-06-01T09:00:00[Europe/Vienna]'),
    duration: { minutes: 30 },
    meta: { title: 'Standup', color: '#4f46e5' },
  },
  {
    id: 'public-holiday',
    rrule: 'FREQ=YEARLY;BYMONTH=8;BYMONTHDAY=15',
    // All-day series — `dtstart` is a `PlainDate`, not a `ZonedDateTime`.
    dtstart: Temporal.PlainDate.from('2026-08-15'),
    meta: { title: 'Mariä Himmelfahrt' },
  },
]);

builder.series(series); // reactive; mutating the ref re-expands
```

For backend-managed series, use the loader form — the calendar fetches once per visible window, results cached the same way as `eventsLoader`:

```ts
builder.seriesLoader(async (window) => {
  const res = await fetch(`/api/series?from=${window.start}&to=${window.end}`);
  return res.json();
});
```

`series()` and `seriesLoader()` are mutually exclusive but both compose with `events()` / `eventsLoader()` — `getVisibleEvents()` returns the merged set.

### What ships in the wire

`RecurringSeries` is the public type (in `@cocoar/vue-calendar`):

```ts
interface RecurringSeries<TMeta = Record<string, unknown>> {
  id: string;                // stable series identifier
  rrule: string;             // RFC 5545 RRULE, e.g. 'FREQ=WEEKLY;BYDAY=MO'
  dtstart:
    | Temporal.ZonedDateTime // timed series — local + IANA zone
    | Temporal.PlainDate;    // all-day series
  duration?: { minutes?: number; hours?: number; days?: number };
  rdate?: ReadonlyArray<Temporal.ZonedDateTime | Temporal.PlainDate>;
  exdate?: ReadonlyArray<Temporal.ZonedDateTime | Temporal.PlainDate>;
  meta?: TMeta;
}
```

The Temporal-typed `dtstart` is a non-negotiable: ISO strings, native `Date`, and floating `Temporal.PlainDateTime` are rejected at the boundary. Article 4 — store intent (local time + IANA zone), derive instants. The same rule applies to `rdate` and `exdate`: every entry's `timeZoneId` is preserved to the output, so a series in Tokyo with an RDATE in Vienna keeps both zones.

Each expanded `CalendarEvent` carries provenance under `meta.__recurrence`:

```ts
import { getRecurrenceMeta } from '@cocoar/vue-calendar/recurrence';

builder.onEventClick(({ event }) => {
  const meta = getRecurrenceMeta(event);
  if (meta) {
    console.log(meta.seriesId);     // 'standup'
    console.log(meta.recurrenceId); // ZonedDateTime — the original wall-time slot
    console.log(meta.source);       // 'rrule' | 'rdate'
  }
});
```

`event.id` is a unique synthetic value of shape `${seriesId}__${recurrenceId}` — the layout pipeline dedupes by id, so series identity lives in the provenance accessor, not on the event id directly. `recurrenceId` matches RFC 5545 RECURRENCE-ID semantics (the original slot), enabling future single-instance edits without data-shape changes.

### Standalone expansion

`expandSeries(...)` is exported from a subpath so apps that don't use the builder still avoid pulling the engine into their main bundle:

```ts
import { expandSeries } from '@cocoar/vue-calendar/recurrence';
import { Temporal } from '@js-temporal/polyfill';

const occurrences = await expandSeries(
  series,
  {
    start: Temporal.ZonedDateTime.from('2026-06-01T00:00:00[Europe/Vienna]'),
    end:   Temporal.ZonedDateTime.from('2026-07-01T00:00:00[Europe/Vienna]'),
  },
  'compatible',          // DstPolicy — same union as builder.dstPolicy(...)
  /* engine? optional */ // defaults to lazy-loaded rrule-temporal adapter
);
```

### Custom engines

The calendar ships one bundled engine — a `rrule-temporal` adapter at the `@cocoar/vue-calendar/recurrence-rrule-temporal` subpath, lazy-loaded on first call. Apps with extreme volume or specialized needs (server-side pre-expansion, alternative parsers) implement the `RecurrenceEngine` interface in their own code:

```ts
import type { RecurrenceEngine } from '@cocoar/vue-calendar/recurrence';

const myEngine: RecurrenceEngine = {
  async expand(request) {
    // request.window.{startMs, endMs}
    // request.series — the typed wire shape (no string roundtrips)
    // …
    return { results, errors };
  },
};

builder.recurrenceEngine(myEngine);
// or, SSR-friendly factory form:
builder.recurrenceEngine(() => new MyEngine());
```

Engine-swap invariance is enforced by the library: every occurrence is re-resolved from intended wallclock + source zone + `DstPolicy` after the engine returns, so observable output depends only on the contract inputs, never on which engine ran underneath.

## Popovers and tooltips

The library deliberately doesn't ship a built-in popover — every app wants different content (title-only tooltip vs full action menu vs edit-in-place panel). What it does ship are two handlers that surface the timing + anchor element so consumer code can wire `useOverlay()` (from `@cocoar/vue-ui`) into events:

```ts
import { useOverlay, popoverPreset, type OverlayRef } from '@cocoar/vue-ui';

const overlay = useOverlay();
const activeOverlay = ref<OverlayRef | null>(null);

builder
  .onEventHover(({ event, native }) => {
    activeOverlay.value?.close();          // close previous first
    activeOverlay.value = overlay.open({
      spec: {
        ...popoverPreset,
        anchor: { kind: 'element', element: native.currentTarget as Element },
      },
      content: { kind: 'component', component: MyEventPopover },
      inputs: { event },
    });
  })
  .onEventHoverLeave(() => {
    activeOverlay.value?.close();
    activeOverlay.value = null;
  });
```

`native.currentTarget` is the event-element DOM node — pass it straight to the overlay's anchor spec. The same pattern works for click-driven popovers (use `onEventClick`) and double-click triggers (`onEventDoubleClick`). No hover delay is applied; wrap the open in `setTimeout(..., 200)` if you want one. For touch / pen pointers, `pointerenter` fires on press — handler doubles as a long-press surface on tablets when paired with a delay.

Handlers fire across all five views (day / week / workWeek / month / agenda / timeline) at the same DOM elements that handle click. The library never opens an overlay itself — the entire interaction lifecycle (open / close / outside-click / escape / scroll-strategy) lives in consumer code via the overlay spec.

## Imperative API

The builder exposes an `api` object — same shape regardless of whether the calendar component has mounted yet. Stash it from `useCalendar()` and call methods directly:

```ts
const { builder, api } = useCalendar();

api.next();                     // ±1 view-page
api.prev();
api.goToToday();
api.goTo('2026-12-25');
api.setView('month');
api.scrollToTime(8);            // day / week only
api.scrollToDate('2026-04-15'); // agenda only
api.getVisibleRange();          // ViewWindow | null
api.getVisibleEvents();         // events touching the current window
api.refresh();                  // re-run the loader for the current window
api.refreshRange(start, end);   // invalidate intersecting cache entries

watch(api.loading, (b) => console.log('loading?', b));
watch(api.visibleRange, (w) => console.log('window changed', w));
```

## API reference

### `useCalendar<TMeta>()`

```ts
function useCalendar<TMeta>(): {
  builder: CalendarBuilder<TMeta>;
  api: CalendarApi<TMeta>;
};
```

Returns a fresh builder + its imperative api. Call once per `<CoarCalendar>` instance, typically at the top of `<script setup>`.

### `CalendarBuilder<TMeta>` setters

The builder is **flat** — every setter lives directly on it. There are no sub-builders or factory callbacks.

| Setter | Argument | Notes |
|--------|----------|-------|
| `events(source)` | `MaybeRefOrGetter<readonly CalendarEvent<TMeta>[]>` | Consumer-managed event array. |
| `eventsLoader(loader)` | `(window: ViewWindow) => CalendarEvent[] \| Promise<CalendarEvent[]>` | Calendar-managed async loader (cached, debounced). Mutually exclusive with `events`. |
| `series(source)` | `MaybeRefOrGetter<readonly RecurringSeries<TMeta>[]>` | Recurring series — expanded per visible window. Reactive. Composes with `events` / `eventsLoader`. |
| `seriesLoader(loader)` | `(window: ViewWindow) => RecurringSeries[] \| Promise<RecurringSeries[]>` | Calendar-managed series loader (cached). Mutually exclusive with `series`. |
| `recurrenceEngine(engineOrFactory)` | `RecurrenceEngine \| (() => RecurrenceEngine)` | Override the bundled rrule-temporal engine. Factory form is the SSR escape. |
| `view(model)` | `Ref<CalendarView>` | Bind a caller-owned view ref. |
| `date(model)` | `Ref<Temporal.PlainDate>` | Bind a caller-owned date ref. |
| `timezone(tz)` | `MaybeRefOrGetter<string>` | IANA display timezone. |
| `locale(loc)` | `MaybeRefOrGetter<string \| undefined>` | BCP-47 locale. |
| `firstDayOfWeek(d)` | `MaybeRefOrGetter<0..6 \| undefined>` | Override the locale-detected default. |
| `workDays(d)` | `MaybeRefOrGetter<readonly DayOfWeek[]>` | Days to render in the `'workWeek'` view (0 = Sun … 6 = Sat). Default `[1,2,3,4,5]` (Mon–Fri). |
| `timeRange(r)` | `MaybeRefOrGetter<{ startMinutes: number; endMinutes: number }>` | Day / week visible hour range, in minutes from midnight. |
| `slotDuration(d)` | `MaybeRefOrGetter<number>` | Time-grid slot subdivision (minutes). Default `30`. |
| `pixelsPerHour(p)` | `MaybeRefOrGetter<number>` | Time-grid row height. Default `60`. |
| `density(d)` | `MaybeRefOrGetter<'comfortable' \| 'compact'>` | Row / padding tightness. |
| `maxEventsPerCell(n)` | `MaybeRefOrGetter<number>` | Month-cell pill hint. Default `3`. |
| `agendaLengthDays(n)` | `MaybeRefOrGetter<number>` | Days the agenda window covers. Default `30`. |
| `showEmptyDays(b)` | `MaybeRefOrGetter<boolean>` | Render headers for empty days (agenda). |
| `availableViews(v)` | `MaybeRefOrGetter<readonly CalendarView[]>` | Filter the view-switcher. |
| `dstPolicy(p)` | `MaybeRefOrGetter<'compatible' \| 'reject' \| 'earlier' \| 'later'>` | DST gap/overlap resolution (Article 5). Default `'compatible'`. See "DST handling" above. |
| `dateStyle(s)` | `MaybeRefOrGetter<'full' \| 'long' \| 'medium' \| 'short' \| undefined>` | Verbosity of date labels (Article 9 — independent of locale). |
| `timeStyle(s)` | `MaybeRefOrGetter<'full' \| 'long' \| 'medium' \| 'short' \| undefined>` | Verbosity of time labels (Article 9). |
| `hour12(h)` | `MaybeRefOrGetter<boolean \| undefined>` | Force 12-/24-hour clock independent of locale. `undefined` lets the locale decide. |
| `canDrop(fn)` | `(event, target) => boolean` | Drop-target validator. Read refs inside the function for reactive policies. |
| `eventRenderer(r)` | `EventRenderer<TMeta>` | Universal event renderer. Branch on `ctx.layout?.kind` (`'positioned'` / `'allDayBar'` / `'monthPill'` / `'monthBar'`) to render per layout variant. See "Custom event rendering" above. |
| `dayHeaderRenderer(r)` | `DayHeaderRenderer` | Day column header. |
| `onEventClick(fn)` | `(payload: { event, native: PointerEvent }) => void` | |
| `onEventDoubleClick(fn)` | `(payload: { event, native: MouseEvent }) => void` | |
| `onEventHover(fn)` | `(payload: { event, native: PointerEvent }) => void` | Pair with `useOverlay()` for popovers / tooltips. `native.currentTarget` is the anchor element. No hover delay applied — wrap with `setTimeout(..., 200)` if needed. |
| `onEventHoverLeave(fn)` | `(payload: { event, native: PointerEvent }) => void` | Companion close-trigger for the popover the hover handler opened. |
| `onEventDoubleClick(fn)` | `(payload) => void` | Common: open an edit dialog. |
| `onEventDrop(fn)` | `(payload) => void` | Drag-and-drop / keyboard / touch all flow through this. |
| `onDateClick(fn)` | `(payload) => void` | Empty cell / day-header clicked. |
| `onTimeClick(fn)` | `(payload) => void` | Empty time slot (week / day). |
| `onMoreClick(fn)` | `(payload) => void` | Per-cell context menu trigger (month). |
| `onRangeChange(fn)` | `(window) => void` | Visible window changed. |

### `CalendarApi<TMeta>`

```ts
interface CalendarApi<TMeta> {
  goTo(date: Temporal.PlainDate): void;
  goToToday(): void;
  next(): void;
  prev(): void;
  setView(view: CalendarView): void;
  getVisibleRange(): ViewWindow | null;
  getVisibleEvents(): CalendarEvent<TMeta>[];
  scrollToTime(time: Temporal.PlainTime): void;
  scrollToDate(date: Temporal.PlainDate): void;
  refresh(): void;
  refreshRange(window: ViewWindow): void;
  readonly loading: Readonly<Ref<boolean>>;
  readonly visibleRange: Readonly<Ref<ViewWindow | null>>;
  readonly gridReady: Readonly<Ref<boolean>>;
}
```

### `<CoarCalendar>` slots

Variant-specific slots (`pill`, `multiDayBar`, `allDayEvent`) still exist on the **component** even though there are no matching builder setters — the slots take precedence over `eventRenderer` when both are supplied, so reach for a slot when you want a one-line template-side override and the renderer when you want a function with discriminated branching.

| Slot | Scope | Purpose |
|------|-------|---------|
| `header` | `{ view, cursor, range, controls }` | Replace the entire header. |
| `headerStart` | `{ controls }` | Prepend before nav buttons. |
| `headerEnd` | `{ controls }` | Append after the view switcher. |
| `viewSwitcher` | `{ view, available, setView }` | Replace just the view switcher. |
| `event` | `{ event, view, layout?, item? }` | Per-event renderer (Day / Week / Agenda; falls back for month pills / bars). |
| `allDayEvent` | `{ event, layout }` | All-day band renderer (week / day). |
| `pill` | `{ event, pill }` | Month single-day pill. |
| `multiDayBar` | `{ event, bar }` | Month multi-day bar. |
| `dayHeader` | `{ date, isToday, isWeekend }` | Per-day column header (week / day). |

### `<CoarCalendar>` props

| Prop | Type | Description |
|------|------|-------------|
| `builder` | `CalendarBuilder` | **Required.** From `useCalendar()`. |

That's it — everything else lives on the builder.

---

---
url: /components/calendar/day-view.md
---
# `<CoarDayView>` — Day View&#x20;

Single-day time-grid surface — one hour-axis on the left, one day column on the right. Multi-day all-day events that touch the visible day appear in the all-day band that pins under the day header. Use it standalone via [`useDayView()`](#usedayview) when you need just the day view without the [`<CoarCalendar>`](/components/calendar/coar-calendar) 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](/components/calendar/week-view) — they differ only in the days array the wrapper computes (Day uses `[date]`, Week uses `weekDates(date, fdow)`).

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

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

## Builder setters

Full reference: see [the composer's API reference](/components/calendar/coar-calendar#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. |
| `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. |

---

---
url: /components/calendar/week-view.md
---
# `<CoarWeekView>` — Week View&#x20;

7-day time-grid view — one hour-axis on the left, seven day columns on the right, all-day band pinned under the day-of-week header. The week's first day is locale-aware (`en-US` / `ja-JP` start on Sunday, `de-AT` / `fr-FR` start on Monday) but can be overridden via `firstDayOfWeek()`.

```html
<CoarWeekView :builder="builder" />
```

## Standalone usage

```ts
import { ref } from 'vue';
import { Temporal } from '@js-temporal/polyfill';
import {
  CoarWeekView,
  useWeekView,
  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:30:00[UTC]'),
  },
]);
const date = ref('2026-04-15');

const { builder, api } = useWeekView();
builder
  .events(events)
  .date(date)
  .timezone('UTC')
  .timeRange([7, 20])
  .slotDuration(30)
  .firstDayOfWeek(1);   // Monday — overrides locale default
```

```html
<CoarWeekView :builder="builder" />
```

The Week view shares its builder type, `CalendarBuilder`, with the [Day view](/components/calendar/day-view) — they differ only in the days array the wrapper computes (Week uses `weekDates(date, fdow)` to expand the cursor to the 7-day window).

## Custom day header

The `#dayHeader` slot replaces the default per-column header. Receives `{ date, isToday, isWeekend }` so you can render whatever fits your design — the example below stacks day-of-week + day-of-month with a today indicator and weekend muting.

## Inside `<CoarCalendar>`

`<CoarCalendar>` and `<CoarWeekView>` consume the SAME `CalendarBuilder` instance — there's no sub-builder forking. Set time-grid config 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 week or day, the same builder feeds the embedded `<CoarTimeGrid>`. View-specific settings simply have no effect outside their view (e.g. `maxEventsPerCell` is a no-op in week view).

## `useWeekView<TMeta>()`

```ts
function useWeekView<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>` — `useWeekView()` is a thin shorthand that pre-sets `view: 'week'`. The `next()` / `prev()` step is one **week** here, not one day.

## Builder setters

Full reference: see [the composer's API reference](/components/calendar/coar-calendar#api-reference). Highlights that matter for the week view:

| Setter | Argument | Default | Notes |
|---|---|---|---|
| `firstDayOfWeek(d)` | `0..6 \| undefined` | locale-aware | `0` = Sunday … `6` = Saturday. |
| `dayHeaderRenderer(r)` | `DayHeaderRenderer` | — | Per-day column header — typically the most-customised piece on a week view. |
| `timeRange(r)` | `MaybeRefOrGetter<{ startMinutes, endMinutes }>` | `{0, 1440}` | Visible hour range, in minutes from midnight. |
| `slotDuration(d)` | `MaybeRefOrGetter<number>` | `30` | Slot subdivision (minutes). Also the snap step when dragging. |
| `pixelsPerHour(p)` | `MaybeRefOrGetter<number>` | `60` | Vertical density. |
| `eventRenderer(r)` | `EventRenderer<TMeta>` | — | Universal renderer. For all-day-band bars, branch on `ctx.layout?.kind === 'allDayBar'`; for time-grid event cards, `ctx.layout?.kind === 'positioned'`. |

## Multi-day events & the all-day band

Multi-day events that touch any visible day are split into one bar per row, each clipped to the row. Single-day all-day events appear in the same band. Cluster-aware lane sizing means a busy day doesn't unfairly narrow events on quieter days in the same week.

## Imperative API

```ts
interface CalendarApi<TMeta> {
  goTo(iso: string): void;
  goToToday(): void;
  next(): void;                  // ±1 week
  prev(): void;
  getVisibleRange(): ViewWindow | null;
  getVisibleEvents(): CalendarEvent<TMeta>[];
  scrollToTime(hour: number): void;
  refresh(): void;
  refreshRange(start: string, end: string): void;
  readonly loading: Readonly<Ref<boolean>>;
  readonly visibleRange: Readonly<Ref<ViewWindow | null>>;
  readonly gridReady: Readonly<Ref<boolean>>;
}
```

## `<CoarWeekView>` props + slots

| Prop | Type | Description |
|---|---|---|
| `builder` | `CalendarBuilder` | **Required.** From `useWeekView()` (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. |

---

---
url: /components/calendar/work-week-view.md
---
# `<CoarWorkWeekView>` — Work Week View&#x20;

The week view with weekend columns filtered out. Configurable working-day set via `builder.workDays(...)` — defaults to Mon–Fri but adapts to 6-day operations (Mon–Sat), 4-day weeks (Mon–Thu), Sun–Thu Middle-East work weeks, or any other DayOfWeek subset.

Mechanically the work-week view is a thin filter over [`<CoarWeekView>`](/components/calendar/week-view): same time-grid, same DnD pipeline, same slot rendering, same all-day band. The visible-range `ViewWindow` even stays the full Mon–Sun span — only the columns rendered differ. Loaders see weekend events the same way they do for the full week.

```html
<CoarWorkWeekView :builder="builder" />
```

## Standalone usage

```ts
import { ref } from 'vue';
import { Temporal } from '@js-temporal/polyfill';
import {
  CoarWorkWeekView,
  useWorkWeekView,
  type CalendarEvent,
} from '@cocoar/vue-calendar';

const events = ref<CalendarEvent[]>([
  {
    id: 'standup',
    start: Temporal.ZonedDateTime.from('2026-04-15T09:00:00[Europe/Vienna]'),
    end:   Temporal.ZonedDateTime.from('2026-04-15T09:30:00[Europe/Vienna]'),
  },
]);
const date = ref('2026-04-15');

const { builder } = useWorkWeekView();
builder
  .events(events)
  .date(date)
  .timezone('Europe/Vienna')
  .firstDayOfWeek(1)            // Monday — overrides locale default
  .workDays([1, 2, 3, 4, 5]);   // Mon–Fri (default — shown for clarity)
```

```html
<CoarWorkWeekView :builder="builder" />
```

## Working-day conventions

`workDays(d)` accepts any subset of `0..6` (`0` = Sunday, `6` = Saturday). The order in the array doesn't matter — internally it's used as a Set. The rendered columns appear in calendar order, anchored to `firstDayOfWeek`.

```ts
builder.workDays([1, 2, 3, 4, 5]);        // Mon–Fri (default)
builder.workDays([1, 2, 3, 4, 5, 6]);     // Mon–Sat (retail / hospitality)
builder.workDays([1, 2, 3, 4]);           // Mon–Thu (4-day week experiments)
builder.workDays([0, 1, 2, 3, 4]);        // Sun–Thu (Middle East, parts of South Asia)
```

::: tip Reactive `workDays`
`workDays(d)` accepts `MaybeRefOrGetter`, so a `ref<DayOfWeek[]>` flips the rendered columns live. Useful for "show Saturday too" toggles in operations dashboards without a full reload.
:::

## Window vs render set

`builder.api.getVisibleRange()` for the work-week view returns the **full Mon–Sun span**, not the filtered weekday subset. Two reasons:

* **`eventsLoader(window)` and `seriesLoader(window)`** should fetch weekend events too. Consumers may want to keep them in the database, filter them in the data layer, or rely purely on the view to suppress weekend columns; the loader doesn't need to know the column set.
* **`api.getVisibleEvents()`** returns events that touch any day in the full span, including weekends. A Saturday client demo still shows up in the event list (e.g. for "what did we work on this week?" summaries), just not as a rendered pill in the grid.

If your use case needs the rendered-columns date set, call `workWeekDates(cursor, firstDayOfWeek, workDays)` from `@cocoar/vue-calendar` directly.

## Navigation

`prev()` / `next()` step by 7 days, same as the [Week view](/components/calendar/week-view) — *not* by the count of working days. Stepping by 5 days would leave the cursor on a weekend on alternate clicks, breaking the "this week / next week" mental model. The workday filter is a render concern, not a navigation one.

## Inside `<CoarCalendar>`

When `<CoarCalendar>` is active and the user clicks the "Work week" view-switcher button, the shell mounts `<CoarWorkWeekView>` and the same builder feeds it — view-specific settings (`timeRange`, `slotDuration`, `pixelsPerHour`) apply identically to Week and WorkWeek.

```ts
const { builder } = useCalendar();
builder
  .timeRange({ startMinutes: 8 * 60, endMinutes: 18 * 60 })
  .workDays([1, 2, 3, 4, 5]);
```

The shell's default `availableViews` includes `'workWeek'`, so the view-switcher gets a "Work week" button automatically. Hide it by setting your own list:

```ts
builder.availableViews(['month', 'week', 'day', 'agenda']);
```

## `useWorkWeekView<TMeta>()`

```ts
function useWorkWeekView<TMeta>(): {
  builder: CalendarBuilder<TMeta>;
  api: CalendarApi<TMeta>;
};
```

Returns a fresh standalone builder + its imperative api. Pre-sets `view: 'workWeek'` and `availableViews: ['workWeek']` so the standalone view doesn't render an inactive view-switcher.

## Builder setters

Full reference: see [the composer's API reference](/components/calendar/coar-calendar#api-reference). Highlights specific to the work-week view:

| Setter | Argument | Default | Notes |
|---|---|---|---|
| `workDays(d)` | `MaybeRefOrGetter<readonly DayOfWeek[]>` | `[1, 2, 3, 4, 5]` | `0` = Sunday … `6` = Saturday. Empty array renders zero columns. |
| `firstDayOfWeek(d)` | `0..6 \| undefined` | locale-aware | Affects the underlying week's anchor; the workDays filter is applied on top. |
| `timeRange(r)` | `MaybeRefOrGetter<{ startMinutes, endMinutes }>` | `{0, 1440}` | Visible hour range, in minutes from midnight. |
| `slotDuration(d)` | `MaybeRefOrGetter<number>` | `30` | Slot subdivision (minutes). Also the snap step when dragging. |
| `pixelsPerHour(p)` | `MaybeRefOrGetter<number>` | `60` | Vertical density. |
| `dayHeaderRenderer(r)` | `DayHeaderRenderer` | — | Per-day column header — same slot as Week. |
| `eventRenderer(r)` | `EventRenderer<TMeta>` | — | Universal renderer. Same `ctx.layout?.kind` discriminator as Week (`'positioned'` for time-grid events, `'allDayBar'` for the all-day band). |

## `workWeekDates(date, firstDayOfWeek, workDays)`

Pure helper exported from `@cocoar/vue-calendar`. Returns the subset of `weekDates(date, firstDayOfWeek)` whose day-of-week is in `workDays`, in calendar order.

```ts
import { workWeekDates, Temporal } from '@cocoar/vue-calendar';

const dates = workWeekDates(
  Temporal.PlainDate.from('2026-06-10'),
  1,                                          // Monday-first
  [1, 2, 3, 4, 5],                            // Mon–Fri
);
// → [2026-06-08, 2026-06-09, 2026-06-10, 2026-06-11, 2026-06-12]
```

## Imperative API

Same surface as the Week view — see [`<CoarWeekView>` Imperative API](/components/calendar/week-view#imperative-api). `next()` / `prev()` step by 7 days; `getVisibleRange()` returns the full Mon–Sun window.

## `<CoarWorkWeekView>` props + slots

| Prop | Type | Description |
|---|---|---|
| `builder` | `CalendarBuilder` | **Required.** From `useWorkWeekView()` (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`. |
| `dayHeader` | `{ date, isToday, isWeekend }` | Per-day column header. `isWeekend` is true for Sat/Sun columns *even if hidden by `workDays`* — useful for custom renderers that compute their own styling. |

---

---
url: /components/calendar/month-view.md
---
# `<CoarMonthView>` — Month View&#x20;

6×7 grid showing the full calendar month plus leading / trailing days for context. Multi-day events render as continuous **bars** across the rows they touch; single-day events render as **pills** inside cells. Cells with overflow scroll internally; per-cell expansion via the kebab menu replaces the older "+ N more" popover.

```html
<CoarMonthView :builder="builder" />
```

## Standalone usage

```ts
import { ref } from 'vue';
import { Temporal } from '@js-temporal/polyfill';
import {
  CoarMonthView,
  useMonthView,
  type CalendarEvent,
} from '@cocoar/vue-calendar';

const events = ref<CalendarEvent[]>([
  {
    id: 'devconf',
    start: Temporal.PlainDate.from('2026-04-13'),
    end:   Temporal.PlainDate.from('2026-04-16'),
  },
  {
    id: 'standup',
    start: Temporal.ZonedDateTime.from('2026-04-15T09:00:00[UTC]'),
    end:   Temporal.ZonedDateTime.from('2026-04-15T09:30:00[UTC]'),
  },
]);
const date = ref('2026-04-15');

const { builder, api } = useMonthView();
builder
  .events(events)
  .date(date)
  .timezone('UTC')
  .maxEventsPerCell(5)
  .eventRenderer((ctx) => {
    if (ctx.layout?.kind === 'monthPill') return h(MyPill, { event: ctx.event, pill: ctx.layout.layout });
    if (ctx.layout?.kind === 'monthBar')  return h(MyBar,  { event: ctx.event, bar:  ctx.layout.layout });
    return undefined; // fall through to lib default for other variants
  });
```

```html
<CoarMonthView :builder="builder" />
```

## Custom pills and bars

The month view exposes two slots — `#pill` for single-day events and `#multiDayBar` for multi-day events. Both receive `{ event, pill }` / `{ event, bar }` so you can branch on the layout payload (lane, col-span, clipping flags) when needed.

## Inside `<CoarCalendar>`

`<CoarCalendar>` and `<CoarMonthView>` consume the SAME `CalendarBuilder` instance — there's no sub-builder forking. Set month-specific config (e.g. `maxEventsPerCell`) directly on the composer's builder:

```ts
const { builder } = useCalendar();
builder.maxEventsPerCell(5);
```

When the active view is month, the same builder feeds the embedded `<CoarMonthView>`. When it's week or day, the same builder feeds `<CoarTimeGrid>`. View-specific settings simply have no effect outside their view.

## `useMonthView<TMeta>()`

```ts
function useMonthView<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>` — `useMonthView()` is just a thin shorthand that pre-sets `view: 'month'`.

## Builder setters

Full reference: see [the composer's API reference](/components/calendar/coar-calendar#api-reference). Highlights that matter for the month view:

| Setter | Argument | Default | Notes |
|---|---|---|---|
| `firstDayOfWeek(d)` | `0..6 \| undefined` | locale-aware | `0` = Sunday, `1` = Monday, … |
| `maxEventsPerCell(n)` | `MaybeRefOrGetter<number>` | `3` | Pill cap hint. The library never truncates — pills always reach the DOM — but the collapsed-cell height reserves space for ~`n` pills before the cell starts to scroll. |
| `eventRenderer(r)` | `EventRenderer<TMeta>` | — | Universal renderer. Branch on `ctx.layout?.kind === 'monthPill' \| 'monthBar'` for variant-specific rendering — see the example above. |
| `dayHeaderRenderer(r)` | `DayHeaderRenderer` | — | Weekday-strip header (Mon / Tue / ...). |

## Per-cell expansion

Each cell has a kebab trigger (top-right of the day-number row, hover-reveal on desktop, always visible on touch). Clicking it opens a context menu with **Show more events** / **Show fewer events**, which expands or collapses the entire **row** (single-row mode — opening one collapses any other previously-expanded row). Right-click / long-press on the cell body opens the same menu at the pointer.

The collapsed cell uses a height that fits ~`maxEventsPerCell` pills + the multi-day-bar lane area; expanded rows grow to a fixed maximum so all overflowing pills are reachable via scroll.

## Drag and drop

* **Pills** — drag a single-day pill to another cell to shift its date. The library reflows the source cell as if the event were already gone, and renders a dashed-outline ghost pill at the target.
* **Bars** — drag a multi-day bar's body to shift the whole bar; drag the **left** or **right** edge handle to resize one side. Resize handles only appear on non-clipped edges (no point resizing from off-month).
* **Keyboard** — Tab to focus an event, Arrow keys to move ±1 day (Up / Down jump a full week-row). Shift + Arrow on an all-day event grows / shrinks the end side.
* **`canDrop`** — the universal drop validator on the builder; returning `false` paints a red dashed "invalid" ghost and silently swallows the drop on release.

## Imperative API

```ts
interface CalendarApi<TMeta> {
  goTo(iso: string): void;
  goToToday(): void;
  next(): void;                  // ±1 month
  prev(): void;
  getVisibleRange(): ViewWindow | null;
  getVisibleEvents(): CalendarEvent<TMeta>[];
  refresh(): void;
  refreshRange(start: string, end: string): void;
  readonly loading: Readonly<Ref<boolean>>;
  readonly visibleRange: Readonly<Ref<ViewWindow | null>>;
  readonly gridReady: Readonly<Ref<boolean>>;
}
```

`scrollToTime` / `scrollToDate` are not on the month API — neither has a vertical-scroll surface in this view.

## `<CoarMonthView>` props + slots

| Prop | Type | Description |
|---|---|---|
| `builder` | `CalendarBuilder` | **Required.** From `useMonthView()` (or share the one from `useCalendar()`). |

| Slot | Scope | Purpose |
|---|---|---|
| `pill` | `{ event, pill }` | Single-day pill renderer. `pill` is the `MonthCellPill` (event + visual order in the cell). |
| `multiDayBar` | `{ event, bar }` | Multi-day bar renderer. `bar` is the `MonthMultiDayBar` (lane / startCol / endCol / clipping flags). |

---

---
url: /components/calendar/agenda-view.md
---
# `<CoarAgendaView>` — Agenda View&#x20;

Virtualized chronological list grouped by day. Multi-day events appear on every day they touch (with a `(cont.)` tag from day 2 onwards). The current-day header floats at the top of the surface and is pushed up by the next inline header — same UX as native CSS sticky, but works correctly on top of an absolutely-positioned virtualized surface.

```html
<CoarAgendaView :builder="builder" />
```

## Standalone usage

```ts
import { ref } from 'vue';
import { Temporal } from '@js-temporal/polyfill';
import {
  CoarAgendaView,
  useAgendaView,
  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:30:00[UTC]'),
  },
  {
    id: 'devconf',
    start: Temporal.PlainDate.from('2026-04-13'),
    end:   Temporal.PlainDate.from('2026-04-16'),
  },
]);
const date = ref('2026-04-15');

const { builder, api } = useAgendaView();
builder
  .events(events)
  .date(date)
  .timezone('UTC')
  .agendaLengthDays(60)
  .showEmptyDays(true);
```

```html
<CoarAgendaView :builder="builder" />
```

The visible window is derived from `date()` (the cursor — the **first** day) plus `agendaLengthDays()` (how many days forward to render). Use `api.scrollToDate(...)` to jump to any day inside that window.

## Imperative scroll-to-date + empty days

The `api` object returned by `useAgendaView()` exposes `scrollToDate(iso)` for jumping to any day inside the window. Toggle `showEmptyDays(true)` to render headers for days with no events — useful when you want a continuous date strip.

## Inside `<CoarCalendar>`

`<CoarCalendar>` and `<CoarAgendaView>` consume the SAME `CalendarBuilder` instance — there's no sub-builder forking. Set agenda-specific config directly on the composer's builder:

```ts
const { builder } = useCalendar();
builder
  .agendaLengthDays(60)
  .showEmptyDays(true);
```

When the active view is agenda, the same builder feeds the embedded `<CoarAgendaView>`. View-specific settings simply have no effect outside their view.

## `useAgendaView<TMeta>()`

```ts
function useAgendaView<TMeta>(): {
  builder: CalendarBuilder<TMeta>;
  api: CalendarApi<TMeta>;
};
```

Returns a fresh standalone builder + its imperative api.

## Builder setters

### Universal (every builder)

Same universal surface as the [composer](/components/calendar/coar-calendar#api-reference). Highlights for the agenda view:

| Setter | Notes |
|---|---|
| `eventRenderer(r)` | Replaces the default time + title row content. |
| `onDateClick(fn)` | Fires on day-group header click. |
| `onEventClick(fn)` / `onEventDoubleClick(fn)` | Per-row interaction. |

### Agenda specific

| Setter | Argument | Default | Notes |
|---|---|---|---|
| `agendaLengthDays(n)` | `MaybeRefOrGetter<number>` | `30` | How many days the visible window covers, starting from `date()`. |
| `showEmptyDays(b)` | `MaybeRefOrGetter<boolean>` | `false` | When `true`, empty days render a header in italic-grey. When `false`, only days with events appear. |

## Multi-day events & continuation tags

A multi-day event appears on every day it touches. The first day shows the event normally; subsequent days show it dimmed with a localised `(cont.)` tag appended to the title. Both rows are interactive — clicking either dispatches `onEventClick` with the same event.

## Floating sticky header

Because the virtualized surface absolutely-positions every item, native `position: sticky` can't pin them. The agenda renders a separate **floating** day-header overlay above the surface that:

* shows the most recent header at-or-before `scrollTop`,
* gets pushed up by the next inline header crossing into its region (continuous swap, no snap),
* is reserved as a sibling of the surface so it doesn't scroll with the rows.

There's nothing to configure — it's automatic.

## Imperative API

```ts
interface CalendarApi<TMeta> {
  goTo(iso: string): void;
  goToToday(): void;
  next(): void;                  // ±agendaLengthDays
  prev(): void;
  getVisibleRange(): ViewWindow | null;
  getVisibleEvents(): CalendarEvent<TMeta>[];
  scrollToDate(iso: string): void;   // Agenda only
  refresh(): void;
  refreshRange(start: string, end: string): void;
  readonly loading: Readonly<Ref<boolean>>;
  readonly visibleRange: Readonly<Ref<ViewWindow | null>>;
  readonly gridReady: Readonly<Ref<boolean>>;
}
```

## `<CoarAgendaView>` props + slots

| Prop | Type | Description |
|---|---|---|
| `builder` | `CalendarBuilder` | **Required.** From `useAgendaView()` (or share the one from `useCalendar()`). |
| `estimatedItemSize` | `number` | Height estimate for the variable-size virtualization. Default `64`. |
| `overscan` | `number` | Items beyond the viewport rendered each direction. Default `5`. |

| Slot | Scope | Purpose |
|---|---|---|
| `event` | `{ event, item }` | Per-row renderer. `item` is the full `AgendaEventItem` (event + `isContinuation` flag). |
| `dayGroupHeader` | `{ date, item, isToday }` | Per-day header renderer (same component renders the inline + floating overlay). |

---

---
url: /components/calendar/timeline-view.md
---
# `<CoarTimelineView>` — Timeline View&#x20;

Gantt-lite layout: **one row per logical event**, horizontal time-axis. The left pane lists event titles; the right pane renders bars positioned by `[start, end)` against the visible window. Same `CalendarEvent` data as Day / Week / Month / Agenda — just rendered as a project-plan timeline instead of a calendar grid.

**Recurring series collapse to one row.** All occurrences of a recurring series (those with `meta.__recurrence.seriesId`) share a single row with one bar per occurrence — a weekly stand-up with 26 instances in the visible window renders as ONE row labelled "Standup ×26", not 26 separate rows. Standalone events (no recurrence metadata) keep one row per event. The grouping is automatic; consumer code doesn't need to do anything.

```html
<CoarTimelineView :builder="builder" />
```

::: tip Gantt-lite vs. full Gantt
This view covers the **timeline-of-events** half of project planning: bars on a time-axis, sorted, with window-clamping and continues-indicators. It does **not** yet include the rest of a full Gantt: task hierarchy (parent / sub-task collapse), dependencies (arrows between bars), critical-path computation, milestones, or resource lanes. Those land in a separate `@cocoar/vue-gantt` package later, building on this view's primitives.
:::

## Live example

The demo above mixes four one-off project-milestone events (design / build / QA / launch / retro) with one recurring "Daily standup" series. The recurring occurrences collapse into a single row labelled "Daily standup ×N" with one coloured bar per occurrence; the one-off milestones each get their own row. Drag empty space to pan; the view-switcher button bar at the top lets you flip between Timeline and the other views to see the same data rendered differently.

## Standalone usage

```ts
import { ref } from 'vue';
import { Temporal } from '@js-temporal/polyfill';
import {
  CoarTimelineView,
  useTimelineView,
  type CalendarEvent,
} from '@cocoar/vue-calendar';

const events = ref<CalendarEvent[]>([
  {
    id: 'design',
    start: Temporal.PlainDate.from('2026-06-01'),
    end:   Temporal.PlainDate.from('2026-06-08'),
    meta: { title: 'Design phase', color: '#4f46e5' },
  },
  {
    id: 'build',
    start: Temporal.PlainDate.from('2026-06-08'),
    end:   Temporal.PlainDate.from('2026-06-22'),
    meta: { title: 'Build phase', color: '#06b6d4' },
  },
  {
    id: 'demo',
    start: Temporal.ZonedDateTime.from('2026-06-22T14:00:00[Europe/Vienna]'),
    end:   Temporal.ZonedDateTime.from('2026-06-22T15:30:00[Europe/Vienna]'),
    meta: { title: 'Client demo', color: '#f59e0b' },
  },
]);
const date = ref('2026-06-01');

const { builder } = useTimelineView();
builder
  .events(events)
  .date(date)
  .timezone('Europe/Vienna')
  .timelineRangeDays(45)
  .timelinePixelsPerDay(40);
```

```html
<CoarTimelineView :builder="builder" />
```

## How bars are positioned

Each logical event becomes one row, sorted by its FIRST bar's `start` ascending (group id ascending as tie-break — `meta.__recurrence.seriesId` for recurring events, `event.id` for standalone). The bar's geometry comes from:

* **Left** = `(event.start − windowStart) days × pixelsPerDay`. Cross-zone timed events project into the calendar's `timezone` (display zone) before their date is taken, so a meeting scheduled at 23:00 Tokyo viewed from Vienna still lands on the correct visual day (~16:00 Vienna).
* **Width** = duration in days × `pixelsPerDay`. All-day events use their `[start, end)` date range; timed events use `start..end` projected into the display zone; missing `end` defaults to start + 30 min (same fallback as the other views).
* **Top** = row index × `rowHeight`.

Single-day all-day events get a one-day-wide bar (not zero). Multi-day all-day events span their full range. Timed events that fall entirely within one day in the display zone also get a one-day bar — sub-day precision is intentionally not in this view (use Day / Week for hour-grained scheduling).

## Window clamping

The visible window is `[cursor, cursor + timelineRangeDays)`. Events that fall outside are filtered out entirely; events that **straddle** the window get a `clippedStart` or `clippedEnd` flag on their row + a squared-off bar edge (no rounded corner on the clipped side). Renderers can use the flags to overlay a "continues" chevron.

```ts
// In a custom #bar slot:
<template #bar="{ event, row }">
  <span v-if="row.clippedStart">←</span>
  <span>{{ event.meta?.title }}</span>
  <span v-if="row.clippedEnd">→</span>
</template>
```

## Performance — row virtualization

The label column and bar area are vertically virtualized: only rows inside the viewport (plus a small buffer of 8 rows on each side) render to DOM. A 1000-task project plan still costs ~30-40 DOM rows worth of nodes regardless of total count; scroll and pan stay at ~constant frame cost.

Virtualization is automatic — no opt-in flag. The `rowHeight` setter controls the math: a uniform row height makes the visible-range computation `O(1)` (`floor(scrollTop / rowHeight)`), no per-row measurement required. Slot renderers (`label`, `bar`) only fire for visible rows, so expensive markup inside slots doesn't get instantiated for off-screen tasks.

See the [/calendar-timeline-perf](http://localhost:5188/calendar-timeline-perf) playground page for an interactive bench at 100 / 500 / 1 000 / 2 500 tasks.

## Panning

Click-and-drag anywhere on the timeline (empty grid cells, the date axis, label column, or row whitespace — anything that isn't an interactive child like an event bar) to pan both axes at once. The cursor switches to `grab` over empty areas and to `grabbing` during the active pan. Pointer-capture keeps the pan alive even when the cursor leaves the timeline element (e.g. drags up into the page chrome).

Bar clicks are NOT hijacked — clicking an event bar still fires `onEventClick`. The pan handler walks up from `e.target` to check for `button` / `a` / `input` / `select` / `textarea` / `role="button"` and exits early when it finds one. Custom slots that render their own interactive elements inherit this behavior automatically.

Touch panning uses the same pointer pipeline (`touch-action: none` on the container), so finger-drag on tablets feels identical to mouse-drag on desktop.

## Sizing the view

Three knobs control the visual density:

| Setter | Default | Effect |
|---|---|---|
| `timelineRangeDays(n)` | `60` | How many days the view spans starting from `cursor`. `next()` / `prev()` step by this much. |
| `timelinePixelsPerDay(p)` | `56` | Horizontal density. `24` = quarter overview, `56` = month (date labels readable on one line), `96` = sprint detail. |
| `timelineRowHeight(h)` | `32` | Vertical row height — pick to match your bar content + density theme. |
| `timelineLabelWidth(w)` | `200` | Left-pane label-column width. |

```ts
// Quarter overview: 90 days, narrow bars
builder.timelineRangeDays(90).timelinePixelsPerDay(16);

// Sprint detail: 14 days, wide bars
builder.timelineRangeDays(14).timelinePixelsPerDay(64);
```

## Slots

`<CoarTimelineView>` exposes three slots for custom rendering — all optional, with sensible plain-text defaults:

| Slot | Scope | Default |
|---|---|---|
| `label` | `{ row, event }` | `meta.title ?? id` of `row.bars[0].event` + occurrence-count badge (e.g. `×26`) when `row.isRecurring`. |
| `bar` | `{ row, bar, event }` | `meta.title` over a `meta.color`-tinted bar. Fires once per bar (N times for recurring rows). |
| `dateHeader` | `{ date, isToday, isWeekend }` | `Intl.DateTimeFormat` "MMM d" in the header axis. |

The `row` payload is a `TimelineRow` with `{ id, top, height, isRecurring, bars[] }`. Each `bar` is a `TimelineBar` with `{ event, left, width, clippedStart, clippedEnd }`. The `event` prop on the `bar` slot is a convenience alias for `bar.event`. For a recurring row, the `label` slot sees `row.bars[0].event` — the first occurrence in the window, which carries the series-level meta (title, color).

## Inside `<CoarCalendar>`

The view-switcher includes a "Timeline" button by default. Same builder feeds the embedded `<CoarTimelineView>`; the timeline-specific setters (`timelineRangeDays` etc.) live on the shared builder and are no-ops outside the timeline view, same convention as `timeRange` for day/week.

```ts
const { builder } = useCalendar();
builder
  .timelineRangeDays(90)
  .timelinePixelsPerDay(24);
```

## `useTimelineView<TMeta>()`

```ts
function useTimelineView<TMeta>(): {
  builder: CalendarBuilder<TMeta>;
  api: CalendarApi<TMeta>;
};
```

Returns a fresh standalone builder + its imperative api. Pre-sets `view: 'timeline'` and `availableViews: ['timeline']` so the standalone view doesn't render an inactive view-switcher.

## Builder setters (timeline-specific)

| Setter | Argument | Default | Notes |
|---|---|---|---|
| `timelineRangeDays(n)` | `MaybeRefOrGetter<number>` | `60` | Days the view spans starting from the cursor. Also the `next()` / `prev()` step. |
| `timelinePixelsPerDay(p)` | `MaybeRefOrGetter<number>` | `56` | Horizontal density. |
| `timelineRowHeight(h)` | `MaybeRefOrGetter<number>` | `32` | Per-event row height in pixels. |
| `timelineLabelWidth(w)` | `MaybeRefOrGetter<number>` | `200` | Left-pane label-column width. |
| `eventRenderer(r)` | `EventRenderer<TMeta>` | — | Universal renderer — fires for timeline bars too (no per-layout discriminator here yet — use the dedicated `#bar` slot if you need the `row` geometry). |

Universal setters (`events`, `eventsLoader`, `series`, `seriesLoader`, `recurrenceEngine`, `timezone`, `locale`, …) work identically to the other views.

## `layoutTimeline(events, options)`

Pure layout helper exported from `@cocoar/vue-calendar`. Returns the same row geometry the view uses internally — useful for custom timeline implementations or tests:

```ts
import { layoutTimeline, Temporal } from '@cocoar/vue-calendar';

const { rows, totalWidth, totalHeight } = layoutTimeline(events, {
  windowStart: Temporal.PlainDate.from('2026-06-01'),
  windowEnd:   Temporal.PlainDate.from('2026-08-01'),
  pixelsPerDay: 56,
  rowHeight: 32,
  displayZone: 'Europe/Vienna',
});

for (const row of rows) {
  // row: { id, top, height, isRecurring, bars[] }
  for (const bar of row.bars) {
    // bar: { event, left, width, clippedStart, clippedEnd }
  }
}
```

## Imperative API

Same surface as the other views — see [`<CoarWeekView>` Imperative API](/components/calendar/week-view#imperative-api). `next()` / `prev()` step by `timelineRangeDays`; `getVisibleRange()` returns the `[cursor, cursor + timelineRangeDays)` window.

## `<CoarTimelineView>` props

| Prop | Type | Description |
|---|---|---|
| `builder` | `CalendarBuilder` | **Required.** From `useTimelineView()` (or share the one from `useCalendar()`). |

---

---
url: /components/calendar/performance.md
---
# Performance baseline&#x20;

The calendar's hot paths — virtualization, drag-and-drop with auto-scroll,
2D scrolling — were instrumented via the [Long Animation Frame API][loaf]
during development. This page records the numbers that justified the
architectural choices, plus the targets you should expect on real
hardware.

[loaf]: https://developer.mozilla.org/docs/Web/API/Performance_API/Long_animation_frame_timing

## How the numbers are measured

Two perf signals are reported throughout this page. They answer different
questions and have very different reliabilities:

| Metric | What it measures | Authoritative? |
|---|---|---|
| **Long frames (5 s window)** | Count of actual ≥ 50 ms frames over the last 5 s, from the browser's own pipeline (Long Animation Frame API). | **Yes.** Cannot be fooled by rAF scheduling. |
| **Worst frame (5 s window)** | Duration in ms of the longest frame in the last 5 s. | **Yes.** Same source. |
| **rAF FPS mean / min** | How often the JS `requestAnimationFrame` callback fires. | **No.** Chromium can defer rAF callbacks one or two vsync ticks during wheel-scroll input dispatch without producing visual jank — the rAF counter dips to 30 even on a smooth page. |

**Rule of thumb:** if Long-frames count is `0` and Worst-frame is under
50 ms, the page is genuinely smooth — regardless of what rAF FPS shows.

The Long Animation Frame API was specified by the W3C precisely to
expose the distinction; it is the source of truth in the numbers below.

## Targets

| Surface | Tier A (laptop / desktop) | Tier B (CI / cheap hardware) |
|---|---|---|
| **1D virtualization (≤ 10 000 fixed-size items)** | 0 long frames during wheel-scroll; worst frame < 16 ms | ≤ 1 long frame; worst frame < 30 ms |
| **1D virtualization (variable-size, 10 000 items)** | 0 long frames during wheel + measurement flushes | ≤ 2 long frames; worst frame < 30 ms |
| **2D virtualization (1 000 × 1 000 cells)** | 0 long frames during diagonal wheel-scroll | ≤ 2 long frames; worst frame < 30 ms |
| **Drag with auto-scroll (200-item list)** | 0 long frames over a 2.6 s scripted drag-and-hold session | ≤ 3 long frames; worst frame < 150 ms |
| **Memory (idle, 10 000 items)** | < 60 MB | < 80 MB |

## Validation results

Measured on a Snapdragon X Elite X1E-78-100 dev box (Windows 11 ARM64,
Chrome ARM64), production build, against the components shipped in
`@cocoar/vue-calendar`.

### 1D virtualization, 10 000 fixed-size items

| Scenario | Long frames | Worst frame |
|---|---|---|
| Idle | 0 | 0 ms |
| Wheel-scroll, mixed direction, ~ 30 s session | **0** | 0 ms |
| Bottom-jump from 10 000 items | **0** | 0 ms |

DOM cost: ≤ ~ 30 items mounted at any time. Bottom-jump still mounts
\~ 14 items, never the full 10 000. Add / remove 1 000 items at runtime
updates the surface in place without remounting visible slots.

### 1D virtualization, 10 000 variable-size items

The variable-size path adds the `MeasurementCache` (Fenwick-tree-backed
prefix sums + interval search) and anchor-based scroll restoration.
Items mount with the `estimatedItemSize`, then `ResizeObserver` flushes
real heights inside one rAF.

| Scenario | Long frames | Worst frame |
|---|---|---|
| Wheel-scroll + first-paint measurement flushes | **0** | 0 ms |
| Manual size-toggle above the viewport (anchor restoration) | **0** | 0 ms |

### 2D virtualization, 1 000 × 1 000 cells

| Scenario | Long frames | Worst frame | Cells in DOM |
|---|---|---|---|
| 30 ticks at 50 ms cadence (≈ real wheel) | **0** | 0 ms | 378 |
| 50 ticks at 30 ms cadence (synthetic burst) | 1 | 50 ms | 357 |
| 1D-variable regression under the same regime | **0** | 0 ms | 10 |

The single long frame in the synthetic burst (~ twice the cadence of
natural wheel input) lands exactly on the 50 ms LoAF threshold. Real-
user wheel-scroll does not produce it. Adding 2D had no effect on the
1D path.

### Drag with auto-scroll (200-item list)

A scripted session via Chrome DevTools:

1. `pointerdown` on row 5
2. 30-step diagonal drag down to the bottom hot zone (~ 600 ms)
3. **Hold at bottom hot zone for 800 ms** — auto-scroll down fires each frame
4. 30-step reverse drag back up to the top hot zone (~ 600 ms)
5. **Hold at top hot zone for 600 ms** — auto-scroll up fires
6. `pointerup`

Total session ~ 2.6 s. `surface.scrollTop` ended at 231 px from a start
of 0 — auto-scroll is real, not simulated.

| Metric | Value |
|---|---|
| Long frames over the session | **0** |
| Worst frame | **0 ms** (under the 50 ms LoAF threshold) |

### Math kernel microbenchmarks

The pure-function primitives in `packages/calendar/src/core/`:

| Operation | mean | hz |
|---|---|---|
| `getVisibleRange1D` (variable, midpoint, overscan = 3) | 314 ns | 3.19 M / sec |
| `MeasurementCache.prefixSum` (10 k items, midpoint) | 75 ns | 13.26 M / sec |
| `MeasurementCache.indexAtOffset` (10 k items, midpoint) | 168 ns | 5.95 M / sec |
| `computeAnchorAdjustment` (10 k items, midpoint) | 89 ns | 11.24 M / sec |

The math kernel uses ≈ 0.002 % of a 60 fps frame budget at 10 k items.
The DOM composition pipeline is the bound, not the math.

## Architectural decisions the numbers locked in

* **Fenwick-tree variable-size cache.** `prefixSum` / `indexAtOffset` /
  `set` all in O(log n). Linear scans were measurably worse at 10 k+
  items in early prototypes; the tree paid for itself.
* **Transform-only positioning.** Items render at `transform: translate3d(0, y, 0)`
  rather than re-layouting on scroll. Composite-only updates per frame.
* **Keyed v-for over the visible range, no recycling pool.** Vue's
  diff turned out faster than a stable pool for typical slot content
  in benchmarks. Heavy custom renderers (charts, video) might benefit;
  the surface accepts a custom recycling pool when needed.
* **rAF-throttled drag.** Pointermove batches into a single rAF tick;
  multiple moves between frames coalesce. Auto-scroll velocity is
  computed in a pure function (`computeAutoScrollVelocity`) and
  applied to `scrollTop` / `scrollLeft` per tick.

## Known accessibility gap — drop announcements

The calendar ships full keyboard-driven drag (Tab to focus, arrow keys
to move, Shift + arrow to resize, Enter to confirm, Escape to cancel),
but **non-sighted users currently get no audible confirmation that a
drop landed.** Sighted users see the event jump to the new slot;
screen-reader users hear nothing.

This is a known gap, not by-design. An earlier internal implementation
had a polite-live-region announcement that read e.g.
`"Daily Standup moved to Monday, 15. Juni 2026, 09:00"` after each
drop. The plumbing was lost during a reactivity refactor (the shell-
level handler that prepended the announcement before forwarding to
`state.onEventDrop` was bypassed when sub-views started reading
`state.onEventDrop` directly per the C7 read-on-every-call contract),
and shipping it cleanly requires plumbing the announcer into the
single drop pipeline (`useCalendarDnd`) so every drop path —
mouse, touch, keyboard — surfaces it once.

Estimated effort: 1 – 2 h. Tracked as a post-launch a11y task.

Until then, consumers who need this can wire their own announcement
inside `onEventDrop`:

```ts
import { useA11yAnnouncer } from '@cocoar/vue-calendar';

const announcer = useA11yAnnouncer();
builder.onEventDrop(({ event, next }) => {
  const title = (event.meta as { title?: string })?.title ?? event.id;
  announcer.announce(`${title} moved to ${next.start.toString()}`);
  // …persist the change
});
```

## Reproduce locally

A manual smoke test surface ships with the playground:

```
pnpm --filter @cocoar/playground dev
# open http://localhost:5188/calendar-perf-bench
```

Pick `100 / 500 / 1 000 / 2 500` events from the segmented control,
drag, switch view, wheel-scroll. Generation-ms, in-data count, and
visible-window count are surfaced in the toolbar so you can sanity-check
the workload at a glance.

For automated perf gating (run the same scripted scenarios against a
production build under Playwright + Chromium DevTools), wire up your
own LoAF observer using the same approach documented in the
[Long Animation Frame API spec][loaf]. The patterns from this page
(scripted drag-and-hold, mixed-direction wheel, bottom-jump) are a good
starting fixture set.

---

---
url: /foundations/kitchen-sink.md
---