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

A batch of improvements from the Tellify (CityDiary) build. For the media-library: inline node **creation** and an app-internal **drop target** for `CoarTree`, plus a programmatic **move**, optimistic **create**, and a **browse-only** mode for `@cocoar/vue-file-explorer-core` — so consumers can drop the workarounds they had built around the gaps. For the blog editor: `@cocoar/vue-markdown-editor` gains real **image** support (URL / paste / drag-drop upload / custom picker), full **table** editing (create, align, delete, and Notion-style hover handles with **drag-to-reorder**), and a **`flavor`** portability switch. Everything is additive and opt-in.

### Added

* **`@cocoar/vue-ui` — `CoarTree` inline node creation.** Opt in with `creatable` (mirrors `renamable`) and call `api.startCreate(parentId, { kind?, initialName?, position? })` to insert a transient, focused **draft row** at its target position — `parentId: null` for the root, otherwise the parent auto-expands and the draft renders nested under it. Commit (Enter / blur) fires `@create` with `{ parentId, name, kind }`; Escape or an empty name fires `@create-cancel`. Same input + 200 ms blur-grace timer as inline rename, so it survives the context-menu-close focus race. The draft lives outside the visible-row model (selection / keyboard / DnD never see it) and works virtualized and at the empty-tree root. Optional `#draft` slot overrides the default folder/file icon. For async validation (e.g. a duplicate-name 409), a builder `onCreate` may return a `Promise` — the tree keeps the draft open + focused (name intact) until it settles, dropping it on success and reopening on reject; prop/event-form consumers get the same retry by re-calling `startCreate(parentId, { initialName })`. Everything works in prop-mode too (`startCreate` is on the component template ref). Removes the consumer workaround of a floating `<input>` rendered outside the tree.
* **`@cocoar/vue-ui` — `CoarTree` app-internal drop target (`acceptsData` / `@data-drop`).** Accept a non-OS, in-app drag — a card dragged out of a grid, a palette chip — by listing the MIME type(s) it carries in `acceptsData` (prop or builder `.acceptsData([...])`). A drop fires `@data-drop` / `onDataDrop` with `{ node: T | null, position, dataTransfer }` (`node: null` = the background), reusing the existing drop highlight, auto-expand-on-hover and `before`/`inside`/`after` position logic. Internal node drags (`@node-move`) are never re-delivered as data drops. Lets consumers drop hand-rolled `dragover`/`drop` listeners on the row slot for grid-card → folder moves.
* **`@cocoar/vue-file-explorer-core` — programmatic `move(id, newParentId, position?)`.** `useFileExplorer` now exposes a plain move (same optimistic-update + rollback as a tree drag) for sources that aren't a `CoarTreeNodeMoveEvent` — a "move to folder" `<select>`, a grid card dropped on a folder row, an undo command. `newParentId: null` moves to the root; `position` is honored only in `'manual'` sort mode. `moveNode` (the tree-drag translator) now delegates to it.
* **`@cocoar/vue-file-explorer-core` — optimistic `addFolder`.** A temp node is inserted immediately and reconciled to the backend's real id on resolve (rolled back on error), so an inline-create flow has no round-trip lag. Pairs with `CoarTree`'s `startCreate` for a flicker-free draft → real-node handoff. Stores that surface their own reactive `_assets` skip the temp node (their own mutation is the source).
* **`@cocoar/vue-file-explorer-core` — browse-only stores.** `loadContent`, `save` and `createFile` are now **optional** on `AssetStore<T>` / `AssetStoreConfig<T>`. A consumer that only browses + edits metadata (e.g. an image library) can omit them: the composable skips the post-upload `save`, treats `openFile` as a no-op (no editor tabs, no single-click-preview), and `saveTab` reports failure cleanly — instead of forcing dead stub methods that throw a spurious "saving not supported" error toast. `createAssetStore` attaches optional methods only when supplied, so `'save' in store`-style capability probes stay reliable.
* **`@cocoar/vue-markdown-editor` — image support (insert by URL + paste / drag-drop upload + custom picker).** A new **Insert Image** sidebar button opens a dialog for `url` / `alt` / `title` and inserts at the cursor. A new **`uploadImage`** prop — `(file: File) => Promise<{ url: string; alt?: string }>` — enables **pasting** (e.g. a screenshot) and **dragging / dropping** image files: a spinner placeholder is shown at the insertion point until the upload resolves, then it's replaced by the image. A new **`pickImage`** prop — `(ctx: ImagePickContext) => void` — **overrides** the Insert Image button so consumers can plug in their own asset library / gallery: it's called with an `insertImage(...)` bound to the cursor plus the `selectedText`, can stay open and insert several, and keeps all ProseMirror handling inside the editor. `pickImage` (button) and `uploadImage` (paste / drop) are orthogonal and compose. Without either, image files fall through to the browser's default handling. Everything round-trips as standard Markdown `![alt](url "title")`, so content from another CMS (a WordPress export) renders unchanged. Resize / alignment / captions are intentionally out of scope (a future image-block slice).
* **`@cocoar/vue-markdown-editor` — `flavor` prop (portability contract).** Picks which features the editor offers and **hard-enforces** them — it only registers the matching Milkdown plugins, so a non-flavor construct can't be typed or pasted (it degrades to plain text) and its toolbar buttons are hidden. `'commonmark'` (portable floor) / `'gfm'` (+ tables, task lists, strikethrough) / `'cocoar'` (default; + inline text color, which is non-portable raw HTML), or a partial capability object `{ gfm?, textColor? }` (opt-in; unspecified = off). For consumers whose Markdown is also rendered somewhere stricter than the web (e.g. a native SwiftUI Markdown view), this guarantees authored content stays within the target renderer's capabilities. Orthogonal to and composes with the soft `tools` toolbar whitelist. Defaults to `'cocoar'`, so existing editors are unchanged.
* **`@cocoar/vue-markdown-editor` — table create / align / delete (GFM).** The **Insert Table** button now opens a **grid size picker** (hover/tap `cols × rows`) instead of a fixed 3×3, and typing **`|3x4|`**+space creates a table anywhere (a GFM input rule — works in `floating` mode without a toolbar). The in-table toolbar gains **column alignment** (left / center / right, applied to the whole column so it round-trips as GFM `:--` / `:-:` / `--:`, with the active alignment highlighted) and **Delete table** (alongside the existing row/column insert + delete-cell). The row/column insert buttons get **purpose-built icons** (a table with the target row/column highlighted + a plus) replacing the confusing, semantically-swapped `between-*` lucide icons (vertical-bar icons had been used for *row* ops and vice-versa). Adds three alignment + four table-op icons to `@cocoar/vue-ui`.
* **`@cocoar/vue-markdown-editor` — table hover edge-handles.** Notion/Word-style grips appear along all four edges of a table on hover (a segment per column on the top & bottom edges, per row on the left & right). Hovering a grip highlights the whole column/row; **clicking** it opens a menu (the library's `CoarContextMenu`) to insert before/after or delete that column/row, and **dragging** it reorders the column/row (with a live drop indicator). Geometry-driven (it measures cell rectangles rather than reacting to ProseMirror's `CellSelection`, which doesn't fire `selectionchange`), so it works on any table without a cursor inside it; the floating toolbar is suppressed while the handle menu is open. Only active in flavors with GFM tables.

### Fixed

* **`@cocoar/vue-ui` — `CoarToastContainer` no longer crashes without `:service`.** The `service` prop now defaults to the `getToastService()` singleton that `CoarOverlayPlugin` registers (the same one `useToast()` wraps), so `<CoarToastContainer />` is zero-config. Previously, rendering it without `:service` threw `Cannot read properties of undefined (reading 'position')` on every render — which stalled the reactive flush and silently broke unrelated reactive UI on the page (and meant toasts were never shown in apps that followed the service-less example). An explicit `:service` still wins; a missing plugin now throws a clear "install `CoarOverlayPlugin`" error instead of the cryptic undefined read.
* **`@cocoar/vue-file-explorer-core` — uploads are stamped with the target `parentId`.** After `addFiles(parentId, …)` the merged node now carries the target `parentId` even when the store's returned asset omits it, so a parent-filtered consumer (e.g. a folder-scoped thumbnail grid) shows the new item immediately without a full `refresh()`.
* **`@cocoar/vue-ui` — `CoarTree` create/data-drop payload types are exported from the package root.** `CoarTreeCreateEvent`, `CoarTreeCreateKind`, `CoarTreeDataDropEvent`, `CoarTreeDraftSlotProps` and `CoarTreeStartCreateOptions` are now re-exported from `@cocoar/vue-ui` alongside the other `CoarTree*` event types (they were only reachable via the deep `./components/tree` path). Consumers can drop the locally-redeclared payload types they had as a workaround.
* **`@cocoar/vue-ui` — `CoarTree` inline-create input is localizable.** The draft row's `aria-label` was a hard-coded English `'New folder name'` / `'New file name'`; it now reads the new `draftFolderName` / `draftFileName` `labels` keys (English defaults), so a non-English consumer (e.g. running on `de`) can localize it via `labels` / builder `.labels({ … })` like every other built-in string.

***

## 2.9.0

A fully redesigned **Theme Editor** with a three-layer semantic token system.

### Added

* **`@cocoar/vue-ui` — Theme Editor redesign + semantic token layer.** `CoarThemeEditor` (exported at `@cocoar/vue-ui/theme-editor`) is overhauled to match the library's design language — SVG icons throughout, lighter borders, no rotate animation on the FAB. The editor now exposes three token layers: **Brand** (base hue + per-step L/C palette editor), **Semantic** (new tab — maps each semantic role such as `--coar-background-semantic-error-bold` to any palette + step via a live-preview select row), and **Corners / Type / Spacing / Depth / Motion** tabs unchanged. The **Danger button** is wired directly to `--coar-background-semantic-error-bold` — it no longer has its own formula controls; reassigning the semantic token in the Semantic tab changes the button (and every other error surface) simultaneously.
* **`@cocoar/vue-ui` — Class-based theme system.** Live overrides are scoped to a `.coar-theme-editor` class (injected via `<style>` tag into `<head>`) instead of inline styles on `:root`. The **Download** button exports a named `.coar-theme--{name}` block (name entered in the editor footer); the class is meant to be applied to `<html>` or any ancestor element. Multiple named themes can coexist and be switched by swapping the class. New **`.coar-theme-none`** reset class (in `@cocoar/vue-ui/styles`) re-declares all themeable tokens to light-mode defaults — apply to any element to escape an ancestor theme class, exactly like `.light-mode` / `.dark-mode`.

### Changed

* **`@cocoar/vue-ui` — `new-components.css` danger button tokens.** `--coar-button-danger-bg` / `-hover` / `-active` now reference the semantic error tokens (`--coar-background-semantic-error-bold` / `-hover` / `-active`) instead of the old oklch formula variables (`--coar-button-danger-l` / `-c`). The removed formula vars were internal-only; visual output is unchanged at default settings.

***

## 2.8.0

`@cocoar/vue-markdown-editor` grows from a plain WYSIWYG box into a proper authoring surface: a Markdown **placeholder**, first-class YAML **frontmatter** (parsed, rendered, and round-tripped across the viewer / core / editor), and a **Source view** toggle for editing the raw Markdown — frontmatter included. Plus a new **`CoarWizard`** (Preview) for multi-step flows in modals. Everything is additive and opt-in; existing editors are unchanged.

### Added

* **`@cocoar/vue-markdown-editor` — `placeholder` prop.** A Markdown hint shown while the editor is empty, rendered as a muted, click-through overlay of the shared `<CoarMarkdown>` viewer (so `**bold**`, lists, headings look like real content) and **never written to `modelValue`** — an untouched editor still emits an empty string. Lets consumers drop the antipattern of pre-filling the value just to show a placeholder (which then got persisted as content).
* **`@cocoar/vue-markdown-editor` — `sourceToggle` prop (raw-Markdown Source view).** Opt-in (default `false`) Rendered ↔ Source switch. In Source mode the whole document — body **and** the frontmatter YAML — is editable as raw Markdown in a `<textarea>`; switching back re-parses and re-renders. The toggle lives in the toolbar (the first sidebar item with a `fixed`/`both` toolbar; a corner button with the default `floating` toolbar). The rich editor stays mounted (hidden) so switching is cheap, and `readonly` / `disabled` + the `CoarFormField` wiring carry over to the textarea.
* **`@cocoar/vue-markdown` + `@cocoar/vue-markdown-core` + `@cocoar/vue-markdown-editor` — YAML frontmatter.** A leading `---…---` block is parsed (via `remark-frontmatter`) into a single `frontmatter` node instead of being mis-read as a thematic break + setext heading (which collapsed the whole YAML onto one line), and it round-trips through `serialize()`. It renders as muted (gray-400), italic `key: value` lines in both the viewer (new `DefaultFrontmatter` renderer) and the editor — there as an inert, read-only atom node (not selectable or draggable; edit the values via the Source view). Adds a shared `parseFrontmatter` helper and a `frontmatter` slot in the renderer registry.
* **`@cocoar/vue-ui` — `CoarWizard` (Preview).** A multi-step flow shell built to live **inside a modal** (it renders no modal of its own). Only the active step is mounted and the body **animates its height** between steps — so a wrapping modal grows / shrinks to fit each page. The step indicator **scrolls and auto-centers** the active step, and `indicatorPosition` places it on any of the four edges (`top`/`bottom` scroll horizontally, `left`/`right` vertically). Content goes in a slot per step `id`; built-in Back / Next / Finish footer (overridable via `#footer`), per-step `canAdvance` gate, optional `freeNavigation`, and `v-model:step`.

***

## 2.7.0

A major expansion of `@cocoar/vue-ui`'s `CoarTree` (shipped in 2.4.0) into a tree that holds up as a core, data-management component: multi-select + checkbox tri-state selection, scaling to tens of thousands of nodes, hardened lazy loading, a full imperative API, accessible drag-and-drop, disabled nodes, search/filter, density/theming and i18n. Purely additive — `selectionMode` defaults to `single`, every new prop defaults to the previous behavior, and `api.focusNode` keeps its 2.4.0 select+focus behavior (the new `api.selectNode` is just a clearer alias).

### Added

* **`@cocoar/vue-ui` — `CoarTree` multi-select + checkbox tri-state selection.** New `selectionMode: 'single' (default) | 'multiple' | 'checkbox'`. `multiple` binds `v-model:selectedIds` (a `Set`) with Ctrl/Cmd-click toggle, Shift-click range, `Ctrl/Cmd+A`, and Shift+Arrow extend. `checkbox` adds a per-row tri-state checkbox bound to an **independent** `v-model:checkedIds` (AntD-style — separate from the highlight selection) with parent⇄child cascade + indeterminate, **lazy inheritance** (a checked but unloaded folder propagates the check to its children once they load), and `checkStrictly` for independent parent/child checks. Sets `aria-multiselectable` on the tree and `aria-checked` (`true`/`false`/`mixed`) on rows; new `isChecked` / `isIndeterminate` slot props. Single-select stays the default, so existing `v-model:selected` consumers are unaffected.
* **`@cocoar/vue-ui` — `CoarTree` scales to tens of thousands of nodes.** Drag cycle-guard is now O(depth) off a live `parentId` walk (was O(n)), an `id → index` map makes keyboard nav / type-ahead / rename O(1), and per-row reactivity (injected row-state) means a selection / focus / drag-over change re-renders only the rows whose flag actually flips. A from-scratch fixed-size virtualizer (`virtualize` prop / `.virtualize()`) with an O(1) constant-size fast-path keeps ~30 rows mounted at 50k+ nodes. Browser-verified at 51,200 nodes.
* **`@cocoar/vue-ui` — `CoarTree` lazy / async children.** `loadChildren(node, { signal })` fetches a folder's children on first expand — built-in chevron spinner while pending and a red retry affordance on failure, `isLoading` / `hasError` slot props, `@load-error`, and `api.reloadChildren(id)`. The `AbortSignal` fires when the folder collapses or leaves the tree (a settled-after-abort load is suppressed — no phantom error), and `maxConcurrentLoads` bounds simultaneous loads for rate-limited backends. `hideLoadingSpinner` suppresses the built-in spinner + retry so you can render your own from the slot props.
* **`@cocoar/vue-ui` — `CoarTree` full imperative API (generic `TreeApi<T>`).** `useTree().api` gains `selectNode(id)` (select + focus — the clear name for the selection era), `expandAll()` / `collapseAll()` / `expandTo(id)` (drives lazy reveal along the path) / `revealNode(id)` (scroll into view without stealing focus) / `getNode(id)` / `moveNode(sourceId, targetId, position)` (the a11y/programmatic equivalent of a drop — runs the same cycle + `canDrop` guards), plus readonly `selectedIds` / `checkedIds` refs. `focusNode` keeps its 2.4.0 select+focus behavior as a back-compat alias of `selectNode`. `TreeApi` is now generic but **defaults its type to `unknown`**, so a bare `TreeApi` reference stays valid. The same surface is mirrored on the component's template ref.
* **`@cocoar/vue-ui` — `CoarTree` accessible drag-and-drop.** Keyboard cut/paste move — `Ctrl/Cmd+X` grabs the focused row, `Ctrl/Cmd+V` drops it relative to the focused target, `Escape` cancels — closing the keyboard-operability gap when `draggable` is on. A polite `aria-live` region announces pick-up / moved / cancelled for both pointer and keyboard moves. `getDragImage(node)` supplies a custom drag ghost (element or HTML string).
* **`@cocoar/vue-ui` — `CoarTree` disabled nodes + search / filter.** `isDisabled(node)` marks rows non-interactive (no select / activate / check / keyboard-focus, `aria-disabled`, dimmed, skipped by type-ahead, `Ctrl+A` and drag; `isDisabled` slot prop). `matchedIds` drives `isMatch` / `isMatchAncestor` slot props and auto-expands the ancestors of every match; the opt-in `filter` prop then hides non-matches while keeping the ancestor path ("virtual parents") visible, with `filterMode: 'strict' (default) | 'lenient'` (mirrors PrimeVue) choosing whether a matched folder reveals its whole subtree.
* **`@cocoar/vue-ui` — `CoarTree` density, theming + i18n.** `density: 'xs' | 's' | 'm' (default) | 'l'` scales the whole row — font, padding, indent **and** the built-in chevron + checkbox + their glyphs — via CSS variables (`--coar-tree-indent`, `--coar-tree-control-size`, `--coar-tree-icon-size`, `--coar-tree-row-pad-y` …) you can also override directly (and `--coar-tree-icon-size` cascades into the slot so your own icons can match). `ariaLabel` / `ariaLabelledby` name the tree; `labels` (`CoarTreeLabels` + `DEFAULT_TREE_LABELS`) makes the chevron / spinner / retry / drag-and-load announcements overridable for localization. APG keyboard polish: `*` expands siblings, PageUp/PageDown page by viewport, ArrowLeft/Right invert under RTL; focus re-seeds to a neighbor (not the top) when the focused row is deleted; an empty tree stays Tab-reachable. New `@select` event (`{ node, ids, via }`), `activateOnClick`, and builder setters for everything (`renamable()` / `onRename()` / `filter()` / `filterMode()` / `density()` / `labels()` …) so the fluent builder drives every feature.

### Fixed

* **`@cocoar/vue-ui` — `CoarTree` inline rename is now reachable via the recommended builder path.** `api.startRename(id)` is now an actual method on `TreeApi` (its 2.4.0 JSDoc pointed at it, but it lived only on the template ref), and the builder gains `renamable()` / `onRename()` / `onRenameCancel()` setters — so the documented builder idiom works without a template ref. (The whole rename feature was also previously undocumented and untested; both are now addressed.)

***

## 2.6.0

### Added

* **`@cocoar/vue-ui` — `CoarSplitPane` + `CoarPanelLayout` (resizable panel layout).** A VS-Code-style workbench primitive: `CoarPanelLayout` arranges `top` / `left` / content / `right` / `bottom` / `status` regions (an empty slot renders no region), each sidebar/panel resizable by drag or arrow keys and collapsible via `*-open` props; sizes are two-way (`v-model:left-width` …) for easy persistence. `CoarSplitPane` is the nestable two-pane primitive underneath (`direction`, `side`, `v-model:size`, `min`/`max`) — nest it to stack views inside a region (e.g. a tree above a details panel). Dividers are focusable `role="separator"` window-splitters (Arrow / Home / End). The content region has a guaranteed minimum (`contentMinWidth` / `contentMinHeight`, default 120 × 80) so sidebars/panels can never be dragged — or squeezed by a shrinking window — to crush it to 0. Drag-to-rearrange / docking is intentionally out of scope.
* **`@cocoar/vue-file-explorer-core` — `selectedAsset` + `describeAsset()`.** `useFileExplorer` now exposes the selected node (resolved reactively from `selectedId`) and its framework-known property rows — Name / Type / Language (script files) / Extension / Path — for details panels. The pure helper `buildAssetProperties` (+ `AssetProperty` / `DescribeAssetContext` types) is exported too. Append your own `payload`-derived rows; render the panel wherever your layout puts it (e.g. a nested `CoarSplitPane`).

### Changed

* **Renamed `@cocoar/vue-file-explorer` → `@cocoar/vue-file-explorer-core`** (folder `packages/file-explorer-core/`). It is the headless data + coordination engine (composable + `AssetStore<T>` contract, no layout); the bare `@cocoar/vue-file-explorer` name is now reserved for a future batteries-included, layouted component built on `-core` + the panel-layout primitives. Pre-release (`0.0.1`, Preview) — no published consumers are affected.

### Fixed

* **`@cocoar/vue-ui` — `vue-router` peer range widened to `^4.5.0 || ^5.0.0`** (was `^4.0.0`). Consumers on `vue-router@5` got an "unmet peer dependency" warning on install even though the integration is runtime-detected and optional. Aligns the range with `@cocoar/vue-fragment-parser`, which already accepted v5. No runtime change — `vue-router` stays an optional peer.

***

## 2.5.2

Patch release that fixes an outside-click dismissal bug in the `@cocoar/vue-ui` overlay-service: an anchored panel (date picker, select, popover, menu) opened from inside a modal/dialog would not close when the user clicked elsewhere in the dialog body — it only closed when its own trigger was clicked again. Outside a modal the same panels dismissed correctly, so the bug only surfaced for overlays stacked above another containing overlay. Root cause: `onDocumentPointerDown` treated "click landed inside overlay X" as "collapse X's tree-children and stop", which silently ignored unrelated dismissable overlays stacked above X. A picker opened via the overlay-service is teleported to `<body>` and stacked above the dialog but is not a tree-child of it, so it was skipped. Reported against the date pickers, but the same code path affects every anchored overlay (all three date pickers, `CoarSelect` / `CoarMultiSelect` / `CoarTagSelect`, `CoarPopover`, menus) when used inside a modal.

### Fixed

* **`@cocoar/vue-ui` — overlay-service outside-click dismissal inside modals.** When a click lands inside an overlay, `onDocumentPointerDown` now also closes any dismissable overlay stacked *above* it whose own subtree doesn't contain the click — instead of only collapsing the clicked overlay's tree-children. Fixes anchored panels (date pickers, selects, popovers, menus) staying open after an outside click when opened from inside a `useDialog()` / modal overlay; previously they only closed when the trigger was re-clicked. Sub-menu collapse and modal backdrop behaviour are unchanged.

***

## 2.5.1

Patch release that fixes a pdf.js styling leak in `@cocoar/vue-document-viewer`. `pdfjs-dist` appends an internal working canvas (`canvas.hiddenCanvasElement`) directly to `<body>` and relies on its own `pdf_viewer.css` to keep it invisible. The viewer didn't ship that stylesheet, so the canvas surfaced as a 300×150 black rectangle and inflated `document.body.scrollHeight` by 150 px the moment any PDF source mounted in a non-modal layout. Modal contexts hid the symptom (overlay above, `overflow: hidden` chrome) but full-routed views surfaced it immediately. Reported from Finoxl's BookingView; same pattern would hit any consumer embedding the viewer in a full-page layout. Fix inlines the minimum subset of pdf.js's body-level rules into the viewer's own stylesheet — `import '@cocoar/vue-document-viewer/styles'` stays the complete styling import.

### Fixed

* **`@cocoar/vue-document-viewer` — body-level `.hiddenCanvasElement` + `#hiddenCopyElement`** now hidden via the package's own CSS. Adds an unscoped global rule (`position: absolute; top: 0; left: 0; width: 0; height: 0; visibility: hidden; overflow: hidden`) to `vue-document-viewer.css`, mirroring the minimum subset of `pdfjs-dist/web/pdf_viewer.css` needed for the body-mounted helpers. No API change, no consumer action needed. The block sits next to the existing pdfjs textLayer subset already mirrored in `CoarDocumentViewer.vue` for the same reason.

***

## 2.5.0

Polish release that lands integration-feedback from the first wave of consumers using `@cocoar/vue-file-explorer` v2.4.0 (Atlas — backend-backed Knowledge editor) and Finoxl (Booking modal — `CoarFormField`), and reworks `CoarFormField` from a label-plus-message-row wrapper into a per-field status indicator with a popover-driven severity model that handles hints, warnings, errors, live-validation rules, and X-of-Y aggregate constraints with a single mechanism. Most of the file-explorer changes fix a contract gap where the documented `loadTree()` method was never actually called by the composable — only the in-memory store's undocumented `_assets` ref was. Now both paths work: composables that supply a reactive `_assets` get the zero-overhead live-mirror as before; composables that only implement the typed `AssetStore<T>` get an internal projection seeded by `loadTree()` on mount and patched after every CRUD op. `CoarTabGroup` gains a `fill` opt-in so editor / viewer / file-explorer tabs no longer need `:deep()` workarounds to propagate height. `CoarTree` warns in dev when rendered empty without an `#empty` slot. `CoarFormField` is a meaningful visual change for every consumer: the message-below-input row is gone, replaced by an icon in the label row with a popover that groups everything by severity section (hint → checklist → errors → warnings); form-labels bumped from 12 px to 14 px (caption-size to medium-input-label-size — the caption token kept its 12 px for tags / badges / dropdowns). No breaking API changes — `error: string` stays valid (now sugar for a one-item array), `hint` keeps the same prop shape (only its render location moved).

### Added

* **`@cocoar/vue-file-explorer` — `loading: Ref<boolean>` + `refresh(folderId?)`** on `UseFileExplorerReturn`. `loading` is the initial-`loadTree()` signal (stays `false` for `_assets`-backed stores); `refresh()` re-runs `loadTree()` or per-folder `loadChildren()` for SignalR / multi-tab / retention-sweep scenarios.
* **`@cocoar/vue-ui` — `CoarTabGroup.fill: boolean`** (default `false`). When true, the active tab panel + content wrapper flip from `display: block` to `flex: 1; min-height: 0; display: flex; flex-direction: column`, propagating the root's height down. The root itself stays untouched (consumer's parent layout decides whether the tab-group stretches). Removes the `:deep(.coar-tab-panel)` workaround consumers had to write for Monaco / PDF / file-explorer tabs.
* **`@cocoar/vue-ui` — `CoarFormField.warning`** (`string | readonly string[]`): non-blocking warnings, drives an orange `triangle-alert` icon when no error is also set. Input stays valid (`aria-invalid="false"`); SR announcements are non-urgent (no `role="alert"`). Errors continue to win severity for icon + invalid state.
* **`@cocoar/vue-ui` — `CoarFormField.rules`** + **`CoarFormFieldRule`** type: live-validation rules with two-axis display modes. Each rule has `label`, `fulfilled: boolean`, and optional `whenPass: 'success' | 'hide'` (default `'success'`) + `whenFail: 'pending' | 'warning' | 'error' | 'hide'` (default `'pending'`). The defaults give you the password-checklist UX (✓ green when fulfilled, ○ grey when not). `whenFail: 'error'` promotes the rule to the popover's Errors section and drives `aria-invalid="true"` on the child input — that's the validity signal. `whenPass: 'hide'` + `whenFail: 'error'` gives the live-validation pattern (disappears when ok, red error when not — e.g. "Max 20 chars"). `whenFail: 'warning'` is the live-advisory pattern. Rules are reactive via Vue's template eval — write `text.length <= 20` inline; no `() => boolean` needed. Named types `CoarFormFieldRule`, `CoarFormFieldRulePassMode`, `CoarFormFieldRuleFailMode` exported for IntelliSense in `computed<CoarFormFieldRule[]>(...)` consumer code. Aggregate "X of Y must be satisfied" patterns compose by adding a 5th rule with `whenFail: 'error'` that checks the count — the 4 individual rules stay as progress, the aggregate is the validity gate.
* **`@cocoar/vue-ui` — `CoarFormField` per-section icons in popover**: hint section gets a grey `info` icon, error section a red `circle-alert`, warning section an orange `triangle-alert`. Section icon only renders on the first line of each section; subsequent items in a section flow left-aligned under the first message's text. Per-rule icons (✓ green `check`, ○ grey `circle`) in the rules checklist section.
* **`@cocoar/vue-ui` — `CoarFormFieldStatusPanel.vue`** internal sub-component carrying the popover content. Lifted out of `CoarFormField` so the section layout is testable without spinning up the overlay service.
* **`@cocoar/vue-ui` — `circle` icon** added to core-icons (used by the rules-checklist for unfulfilled `○` state). `check-circle-2` was already present; it's now also used as the trigger icon when the rule severity is `success`.

### Changed

* **`@cocoar/vue-file-explorer` — `useFileExplorer` now calls `store.loadTree()` on mount** and patches its internal projection after each successful CRUD op (`createFolder`, `createFile`, `uploadFile`, `delete`, `rename`, `move`). Stores that surface a reactive `_assets` ref keep their previous zero-overhead path (the in-memory reference impl is unchanged). Before this release, the composable read `store._assets` directly and never invoked `loadTree()` — any store that implemented the typed `AssetStore<T>` contract without the undocumented `_assets` escape hatch rendered an empty tree silently.
* **`@cocoar/vue-ui` — `CoarFormField` error rendering** rebuilt as a per-field status indicator. Replaces the message-below-input row with a single severity-driven icon in the label row that opens a popover listing every applicable message grouped into sections: hint → rules checklist → errors → warnings. The icon is conditionally rendered so its appearance shifts the label-text right by `icon-width + gap` — that small horizontal nudge is the attention signal. Form's vertical geometry stays stable (no row appears below the input, no Submit button moves). Hover the icon for a peek, click to pin (load-bearing for a planned form-wide error-summary panel where each item will scroll to its field + open its popover).
* **`@cocoar/vue-ui` — `CoarFormField` trigger-icon severity model** is "highest severity visible in the popover": ≥1 error item → red; else ≥1 warning item → orange; else ≥1 success item (a fulfilled `whenPass: 'success'` rule, e.g. a green ✓) → green; else ≥1 pending item or hint → grey info; else no icon. Success **wins over** pending — once the user has fulfilled any rule, the icon flips green for positive reinforcement (the popover still shows unfulfilled rules as ○ for "could do more" detail). Validity-gate rules with `whenFail: 'error'` keep ownership of the red/error path; pending is reserved for genuinely optional progress.
* **`@cocoar/vue-ui` — `CoarFormField.error` widened** to `string | readonly string[]` — pass multiple validation errors as an array, single-string form still works as sugar for a one-item array.
* **`@cocoar/vue-ui` — `CoarFormField.hint` moved fully into the popover** — the always-visible help row below the input is gone. Hint sits at the top of the popover (grey, info icon).
* **`@cocoar/vue-ui` — `CoarFormField` label font-size** bumped from `--coar-body-caption-size` (12 px) to `--coar-component-m-label-font-size` (14 px). The caption token kept its 12 px and is still used by tags, badges, dropdowns, and other decoration text — only form labels moved to the medium-input-label-size tier, which is what they were always meant to be. Every `CoarFormField` consumer sees a small visual bump on every label.

### Fixed

* **`@cocoar/vue-file-explorer` — `resolveFileMeta`** now defaults `language` to `'plaintext'` when the resolved editor is `'script'` but no language was supplied (e.g. `Dockerfile`, `Makefile`, `LICENSE`, or any `asset.editor === 'script'` without `asset.language`). Saves every consumer the `?? 'plaintext'` dance when binding to `<CoarScriptEditor :language>`.
* **`@cocoar/vue-ui` — `CoarTree` DEV-only warn when rendered empty without an `#empty` slot**, with a 500-ms grace so async loaders (a store's `loadTree()`) don't trigger false positives. Stripped from production builds via `import.meta.env.DEV`. Catches silent blank-pane regressions.
* **`@cocoar/vue-ui` — `CoarOtpInput.transform` + `accept` props** now have explicit `undefined` defaults to satisfy `vue/require-default-prop` (pre-existing lint warning, not a runtime change).

### Docs

* **`@cocoar/vue-file-explorer` — `AssetStore<T>`** docs spell out that `loadTree()` is called on mount, document the patch-after-CRUD model, and add a "Reacting to out-of-band updates" section covering both patterns: `api.refresh()` on signal (default) and surfacing `_assets` directly (Pinia / live-query escape hatch).
* **`@cocoar/vue-file-explorer` — `useFileExplorer`** `loading` + `refresh` added to the return-surface and imperative-ops tables.
* **`@cocoar/vue-ui` — `CoarTabGroup`** new "Fill-Height Tabs" section with `TabsFill` demo + opt-in rationale tip.
* **`@cocoar/vue-ui` — `CoarFormField`** docs rewritten for the new status indicator + rules system: tip box at the top, new "Status Indicator", "Live Rules", "On-Submit Validation" sections with live demos. Rules section covers the four common patterns table (progress / live-validation / live-advisory / required-with-progress-tick), trigger-icon severity priority list, and the X-of-Y aggregate-rule pattern with a dedicated demo. Refreshed accessibility section explaining the per-message SR-only spans + space-separated `aria-describedby` aggregation.

***

## 2.4.0

Introduces a new package — `@cocoar/vue-file-explorer` — a VSCode-style file/asset explorer for Vue 3 built as a single composable over a pluggable `AssetStore<T>` backend (no wrapper component for v1 — consumers compose the shell themselves; the worked example is the 1280-LoC playground POC, the docs ship five live demos). Composable-only is a deliberate v1 scope decision: the file-explorer's shell varies wildly per consumer (tab styling, editor dispatch, simulator panels, context-menu shape), but the bits that are hard to get right — placeholder-then-fill open with optimistic rollback, conflict pipeline, blob-URL lease tracking, beforeunload-while-dirty, drag-to-reorder tabs, 3-stage file-meta fallback — all live in `useFileExplorer`. Ships alongside a new generic tree primitive in `@cocoar/vue-ui`, `CoarTree`, with full drag-and-drop (reorder + OS file drop), keyboard navigation, declarative per-target context menus via the builder API, inline rename, and virtualisation. The two were designed together — file-explorer composes `CoarTree`'s drop event into `store.move()` and the inline rename UI lives entirely on the tree side — but `CoarTree` stands on its own for any navigable hierarchy. Also lands a `size` prop on `CoarBreadcrumb`, an `onlyOnOverflow` gate on the `v-tooltip` directive, and broader language support on `CoarScriptEditor` (~40 Monaco grammars + plaintext fallback for extension-less files). Purely additive — no breaking changes.

### Added

* **`@cocoar/vue-file-explorer` — new package** (Preview tier): `useFileExplorer<T>({store, ...})` is the entire public surface besides the `AssetStore<T>` types and the `createInMemoryAssetStore` reference impl. The composable owns the data plane (`store._assets` projection with sort-mode + parentId filter, CRUD ops with optimistic rollback, error funnel through a single `onError(op, err, ctx)` callback), the tree state (`selectedId`, `expanded`), the tab state machine (preview vs pinned with VSCode auto-pin-on-edit semantics, dirty tracking via `content !== savedContent`, save-flow with `savingNodes`-blocked close, drag-to-reorder via `reorderTab`), the async state (`loadingNodes: Set<id>` for content fetch + lazy load, `savingNodes: Set<id>` for in-flight mutations), the blob-URL leases (revoked on delete + `onScopeDispose`), and the `beforeunload` warning while any tab is dirty. Returns refs to bind into `<CoarTree>` (`rootNodes`, `getId`, `getChildren`, `getLabel`, `isExpandable`, `expanded`, `selectedId`) + imperative ops for everything else (`openFile`, `saveTab`, `closeTab` / `closeOthers` / `closeToRight` / `closeAll`, `pinTab` / `unpinTab` / `reorderTab`, `addFolder`, `addFiles` for OS drops, `deleteNode`, `moveNode`, `rename`, `revealInTree`, `pathOf`, `fileMeta`). The placeholder-then-fill `openFile` flow pushes the tab + activates immediately so the editor-area overlay shows on the right pane while `store.loadContent` is awaited; on rejection the placeholder rolls back so the user isn't stranded on an empty editor for a file that never loaded. Editors only mount when `!loadingNodes.has(activeTab.id)` — otherwise heavy viewers (CoarDocumentViewer, Monaco, Milkdown) render their own error UI with empty content before the overlay can take over.
* **`@cocoar/vue-file-explorer` — `AssetStore<T>` contract**: flat interface with `Asset<T>` shape (`{ id, name, kind, parentId, hasChildren?, editor?, language?, payload? }`) — hierarchy is filesystem-style flat with `parentId` links, NOT nested `children[]`, so move/delete/rename operate on single objects and the composable projects to tree via filter. Read methods (`loadTree`, optional `loadChildren` for lazy mode, `loadContent`), write methods (`createFolder`, `createFile`, separate `uploadFile` so backends can pick multipart/signed-URL transports, `save`, `rename`, `delete`, `move` with optional `position`). `createAssetStore(config)` is the recommended factory — thin passthrough today, future home for cross-cutting wrappers (request dedup, retry, telemetry). Lazy mode opt-in via the presence of `loadChildren` on the store (capability probe is `'loadChildren' in store`) — the composable defaults `initialExpandedIds = []` in lazy mode for canonical click-to-expand UX, watches `expanded` with `immediate: true` so seeded ids preload, sets `loadingNodes` per folder during fetch. Eager stores leave `loadChildren` undefined and the watcher is dead code.
* **`@cocoar/vue-file-explorer` — `createInMemoryAssetStore` reference implementation**: browser-only backend backed by `ref<Asset<T>[]>` + an `id → content` Map. Reactive knobs (`latencyMs` + `failureRate` are `MaybeRefOrGetter<number>` read per-op via `toValue`; `onConflict` is `MaybeRefOrGetter<ConflictPolicy<T>>`; `sortMode` lives on the composable for the same reactivity). Conflict policy resolution runs BEFORE simulated latency so `'prompt'` UIs aren't blocked behind it. Lazy mode (`lazy: true`) switches `_assets` to a `ComputedRef` filtered by an internal `_publishedIds` Set; only published subtrees are visible to the composable, the complete dataset still lives in the store's internal bookkeeping for move / delete / cycle-guard. The store exposes `_assets` and `_contents` escape hatches for tests + devtools (underscore-prefixed to mark them as non-portable — a real-backend store won't have them).
* **`@cocoar/vue-file-explorer` — conflict policy**: `ConflictPolicy<T> = 'rename' | 'overwrite' | 'prompt' | 'error' | ((info) => ConflictResolution | Promise<…>)`. Default `'rename'` mirrors Finder / VSCode auto-suffixing (`foo.txt` → `foo (2).txt` → `foo (3).txt`, capped at 999 iterations with UUID-tagged fallback). `'overwrite'` recursively deletes the existing entry before proceeding. `'prompt'` opens `window.prompt` with the auto-suggested name as default; cancel → throws conflict error. Function form receives a `ConflictInfo<T>` with `existing` asset, `incoming` (name + kind), `parentId`, and `suggestedRename`. Applies to `createFolder` / `createFile` / `uploadFile` ONLY — `move` and `rename` deliberately bypass the policy because they're explicit user intent (silently changing the requested name would be surprising). Resolution runs BEFORE `settle()` so prompt UIs aren't latency-blocked.
* **`@cocoar/vue-file-explorer` — sort modes**: `SortMode<T> = 'manual' | 'folders-first' | 'alphabetical' | AssetComparator<T>`, default `'folders-first'` (VSCode pattern — folders alphabetical, then files alphabetical). `'alphabetical'` = Finder-style mixed. `'manual'` preserves the store's array order so drag-reorder between siblings sticks. Reactive via `MaybeRefOrGetter` so a toolbar can swap modes live. `api.reorderable: Ref<boolean>` is `true` only in `'manual'` mode; in other modes the composable silently drops the `position` arg on `move` (the comparator decides where the moved node lands). Lives on `FileExplorerConfig`, NOT on the store, because filesystem backends can't persist per-entry order (filesystems have no such concept) — that's why VSCode's explorer doesn't support drag-reorder between siblings, only move-into-folder.
* **`@cocoar/vue-file-explorer` — 3-stage `FileMeta` fallback**: `asset.editor` (explicit on the asset) → `config.getFileMeta(asset)` (consumer override returning `null` to fall through) → `defaultFileMetaFromName(asset.name)` (extension heuristic recognising markdown + PDF + common image formats + the ~40 Monaco script-editor languages). `resolveFileMeta(asset, {getFileMeta})` is exported for use outside the composable. Unrecognised extensions return `null` and the caller skips with a `console.warn` (same as the POC's behaviour).
* **`@cocoar/vue-file-explorer` — error funnel**: single `onError(op, err, ctx)` callback in `UseFileExplorerOptions`. By the time it fires the composable has already rolled back the optimistic mutation — failed `loadContent` removes the placeholder tab, failed `uploadFile` skips the follow-up `save`, failed `move` reverts the parent change. `AssetOp` is one of `'loadTree' | 'loadChildren' | 'loadContent' | 'createFolder' | 'createFile' | 'uploadFile' | 'save' | 'rename' | 'delete' | 'move'`; `AssetOpContext` carries `id`, `parentId`, `name`, and `file` (for `uploadFile`) so consumers can format toast / dialog / inline messages with file context.
* **`@cocoar/vue-document-viewer` — `v-model:sidebar-open` + `v-model:annotations-panel-open`**: the left rail (thumbnails / outline) and right rail (info + annotations list) now expose their open/closed state as `defineModel` props with `default: false`. Without `v-model` the behavior is unchanged (state lives internally, no breaking change). With `v-model`, the state is held by the consumer's parent component — useful inside a file-explorer shell where the user toggles a rail open, switches to a different editor (Markdown / Monaco), and switches back: with `v-model` the panel state survives the remount; without it, the rail comes back closed because the viewer instance is fresh. New emits: `update:sidebarOpen`, `update:annotationsPanelOpen`. No new internal state — the existing `ref(false)` declarations are replaced by `defineModel` which falls back to the same uncontrolled local-ref behavior when the prop isn't bound. Surfaces the "persistent viewer config across file swaps" pattern documented under `/components/file-explorer/use-file-explorer#persistent-viewer-config-across-file-swaps`.
* **`@cocoar/vue-ui` — `CoarTree` component**: generic, keyboard-navigable, drag-drop-aware tree primitive. Identity, children, and label are extracted via prop functions — render any node shape without forcing a common base type. Two APIs that compose but should not be mixed on the same instance: **props-mode** (`nodes`, `getId`, `getChildren`, `getLabel`, `isExpandable`, manual `<CoarContextMenu>` wiring) for simple cases; **builder-mode** (`useTree<T>()` returns `{ builder, api }`, the builder configures data / behavior / handlers / `folderMenu` / `leafMenu` / `viewportMenu` in a fluent chain, the tree renders its `<CoarContextMenu>` itself, the imperative `api` exposes `focusNode` / `startRename`). Features: drag-and-drop reorder with `before` / `after` / `inside` semantics (rejects self-onto-descendant drops, draws a 2-pixel indicator line for siblings + dashed outline for inside, auto-expands collapsed folders after hover dwell); OS file drop via `accepts-files` with `@files-drop` emitting raw `FileList` + target folder (or `null` for background drop); hover-revealed `⋮` button per row that opens the same context menu as right-click (keyboard + left-click parity with right-click); keyboard nav (arrows, Home/End, Enter/Space, type-to-jump); flat-rendering virtualisation under the hood — handles thousands of nodes without DOM bloat; tooltip on truncated labels via the new `vTooltip.onlyOnOverflow` gate; drop zone fills its container (`min-height: 100%`) so OS drops onto the empty area of sparse trees register. Desktop-first by explicit design — right-click context menus and hover-revealed row affordances are part of the intended UX (exception to the library's tablet-first principle, documented inline). Full docs at `/components/tree/` with six live demos (basic, drag-reorder, file-drop, context-menu, builder API, virtualisation).
* **`@cocoar/vue-ui` — `CoarTree.renamable` API**: opt-in inline rename. New `<CoarTreeNodeLabel :label>` drops into the consumer's default slot and swaps `<span>` ↔ `<input>` via inject — the consumer never wires `renamingId` / buffer / blur handlers manually. The tree owns F2-on-focused-row, Enter / Escape / blur with a 200-ms grace timer for menu-overlay focus-restore (so renaming from a context-menu item doesn't immediately blur the input when the menu closes). New events: `@rename({ node, newName })`, `@rename-cancel(node)`. New exposed: `api.startRename(id)`. New types: `CoarTreeRenameContext`, `CoarTreeRenameEvent<T>`, `CoarTreeNodeSlotProps.isRenaming`. File-explorer composable consumes this directly — the consumer just listens to `@rename` and calls `fe.rename(node.id, newName)`; ~80 LoC of inline rename machinery dropped from the POC.
* **`@cocoar/vue-ui` — `CoarBreadcrumb.size` prop** (`'m' | 's'`): `'s'` produces the slim secondary-chrome variant used by the file-explorer's path strip and any "file path under a tab bar" layout. The token cascades to children so links + separators all scale together. Default `'m'` unchanged.
* **`@cocoar/vue-ui` — `vTooltip.onlyOnOverflow` gate** (`boolean | selector | (el) => boolean`): when set, the tooltip only shows if the target element is overflowing — or, with a selector / function, if a specified descendant is. Eliminates the "tooltip-on-everything" anti-pattern for truncated lists. Used by `CoarTree`'s row labels.
* **`@cocoar/vue-ui` — `ellipsis-vertical` icon**: new core icon for `⋮` overflow menus. Used by `CoarTree`'s hover-revealed row menu and available for general consumer use via `<CoarIcon name="ellipsis-vertical" />`.
* **`@cocoar/vue-script-editor` — broader language support**: `LANGUAGE_EXTENSIONS` extended to ~40 Monaco grammars — TypeScript, JavaScript, JSON, YAML, CSS / SCSS / LESS, HTML, XML, SQL, Shell (bash / zsh / fish), Dockerfile, INI / TOML, C#, C / C++ / Objective-C, Java, Python, Go, Rust, Ruby, PHP, Swift, Kotlin, Scala, Lua, Perl, Dart, F#, VB, R, PowerShell, Solidity, Protobuf, GraphQL, Razor / cshtml, Pug, Handlebars, Twig — plus plaintext fallback for `.txt` / `.log` / `.env` / `.csv` / `.tsv` / extension-less files. `LANGUAGE_EXTENSIONS` is now `Partial<Record<CoarScriptEditorLanguage, string[]>>` with an `extensionFor` fallback to the language name itself when no explicit mapping exists. Drives the file-explorer's editor dispatch — `defaultFileMetaFromName` recognises every extension in the table and returns the matching `{ editor: 'script', language: '…' }`.

### Fixed

* **`@cocoar/vue-ui` — `CoarTree` right-click no longer disturbs selection**: opening a context menu on an unselected row leaves the existing selection in place (matches Finder / VSCode behaviour). The previous behaviour swapped the selection on the right-click target, which made multi-action menus (e.g. "Delete selected items") behave inconsistently when the right-clicked row wasn't part of the selection.
* **`@cocoar/vue-ui` — `CoarTree` drop area fills its container**: `min-height: 100%` on the drop surface so OS file drops onto the empty area of a sparsely-populated tree register correctly. Previously drops below the last row sometimes missed the tree entirely.

### Internal

* **Docs site sidebar**: new `File Explorer (Preview)` group with four entries (Overview, useFileExplorer, AssetStore contract, In-memory store). The Overview embeds five live demos (FullDispatch with real editor dispatch across `CoarScriptEditor` / `CoarMarkdownEditor` / `CoarDocumentViewer`; BasicUsage minimal shell; LazyMode; ConflictPolicies; SortModes). Demos use the dynamic-import + `<ClientOnly>` pattern (heavy impl in `_internal/*.vue`, thin SSR-safe shell in `demos/*.vue`) — same shape as the document-viewer demos. Two scoped CSS workarounds for `.vp-doc` cascade interactions: VitePress applies `margin-top: 8px` to consecutive `<li>` elements in prose lists, which inflated the breadcrumb `<ol>` height (`.bc :deep(.coar-breadcrumb-list li) { margin: 0 }`); and `CoarScriptEditor`'s root carries its own 1 px border, which doubled with the demo's outer border in the script-editor branch only (`.editor :deep(.coar-script-editor) { border: 0 }`).
* **VitePress alias for `@cocoar/vue-file-explorer`**: dev-mode resolves to `packages/file-explorer/src/index.ts`; added to `ssr.noExternal` so SSR rendering picks up the workspace package without requiring a prebuild.
* **Playground POC**: `apps/playground/src/views/FileExplorerPocView.vue` — the 1280-LoC worked example. Every feature of the package exercised in one file: tab bar with drag-to-reorder + context menus + middle-click close, simulator panel with localStorage-persisted knobs for latency / failure / sort / conflict / lazy, OS file drop, reveal-in-tree, `Ctrl+P` quick-open with substring match over `pathOf(id)`, editor dispatch across Monaco / Milkdown / `CoarDocumentViewer`. The POC consumes the package via its workspace dep — there's no `apps/playground/src/file-explorer/` folder any more.
* **POC simulator state persists across reloads**: `Latency`, `Failure`, `Sort`, `Conflict`, and `Lazy` all sync to `localStorage`. `Lazy` is a construction-time switch (changing it would require recreating the store and losing state), so the POC reloads the page when it changes; the others are reactive and retune live. Lets a developer dial in `lazy=true, latency=1000` and reload to see the lazy initial-load spinners with the same configuration they had before.

***

## 2.3.0

Introduces a new package — `@cocoar/vue-document-viewer` — for rendering PDFs, single images, and multi-page image galleries through one source-agnostic Vue 3 component. The internal seam (`PageProvider`) keeps the public surface identical across formats: same toolbar, same panels, same annotation layer. Source kind is picked via a small factory (`pdfSource()`, `imageSource()`, `imageGallerySource()`); the toolbar reads `capabilities` flags off the source to disable (never hide) tools that don't apply, so switching between a PDF and an image never causes button layout shift. `pdfjs-dist` is an optional peer dep — only required when rendering PDFs, image-only consumers skip it entirely. The release also lands horizontal-orientation support on `CoarSidebarDivider` + a `splitTrigger` mode on `CoarSidebarGroup`, both needed by the new document-viewer toolbar (which is built on the same `CoarSidebar` primitives as the markdown-editor toolbar). Purely additive — no breaking changes.

### Added

* **`@cocoar/vue-document-viewer` — new package** (Preview tier): `<CoarDocumentViewer :source>` is the entire public surface. One required prop; everything else (toolbar position, sidebars, annotations panel, info section, search, print, position memory, custom toolbar layout, annotation modes, labels for i18n) is optional. Switching `source` keeps the chrome mounted — only the inner page renderer rebinds. The render pipeline is source-agnostic via a `PageProvider` interface (`render(canvas, opts)` / `cancel()` / optional `getTextLayer()`); PDF pages wrap a `PDFPageProxy`, image pages wrap an `HTMLImageElement`, future kinds can plug in by providing the same shape. `usePageRenderer` no longer imports `pdfjs-dist` at all. The internal `useDocumentLoader` dispatcher watches `source.kind` and routes to one of three always-mounted adapters with filtered source slices (composables can't be conditionally instantiated within one render tree, but mounting all three and letting each watch its own filtered source keeps dispatch reactive without component-level remounting). 58 unit tests across 5 files cover the dispatcher, the `PageProvider` per-canvas render tracking (incl. the black-thumbnail-with-DevTools-open regression), the toolbar's `computeEffectiveTools` separator/capability filtering, and the pure-function helpers (`parsePdfDate`, `inferImageFormat`). Full VitePress documentation at `/components/document-viewer/` (overview, component reference, toolbar customization, annotations lifecycle).
* **`@cocoar/vue-document-viewer` — three source factories**: `pdfSource({ url, headers?, withCredentials? })` from the `/pdf` subpath (pdfjs-dist is an optional peer dep, only PDF consumers pay the bundle cost); `imageSource({ url })` accepts anything `<img src>` accepts (JPG, PNG, SVG, WebP, AVIF, GIF, `blob:`, `data:`); `imageGallerySource({ urls })` for multi-page image documents with possibly-mixed orientations. Each factory returns a frozen `DocumentSource` with the appropriate `capabilities` flags pre-populated. Build inside a `computed` so the viewer rebinds only on real source changes.
* **`@cocoar/vue-document-viewer` — capability-driven toolbar**: every `DocumentSource` advertises `{ multiPage, textLayer, search, outline, print }` capability flags; the toolbar reads them to mark unsupported tools as `disabled` with a `notAvailableForSource` tooltip suffix, rather than removing them from the layout. This is the **stable-position rule** — switching from a 14-page PDF to a single-page SVG never makes buttons jump around, just dims the ones that don't apply. Layer 3 of the toolbar filtering pipeline (after section toggles and separator normalization).
* **`@cocoar/vue-document-viewer` — order-driven `tools` prop**: typed `CoarDocumentViewerTool[]`, drives BOTH visible set AND order. A new `'separator'` pseudo-tool renders a `CoarSidebarDivider` at its position. Leading + trailing separators auto-trim, consecutive separators collapse to one, so section-toggle filtering never leaves orphan dividers. Default is `COAR_DOCUMENT_VIEWER_ALL_TOOLS` — an 8-group canonical layout with separators at group boundaries (panels / nav / zoom / view / rotation / pointer-modes / drawing / actions). The trim+collapse logic lives in pure-function form at `internal/effective-tools.ts` (`computeEffectiveTools`), extracted from the toolbar SFC for testability without component mount. Layer 1 and 2 of the toolbar filtering pipeline.
* **`@cocoar/vue-document-viewer` — built-in annotations**: four types — `marker` (multiply-blend highlighter), `comment` (pin + popover), `ink` (freehand), `freetext` (text box). Coordinates are page-relative and normalized to `[0..1]` so annotations render correctly across zoom + rotation, and stay portable across rendering contexts (a normalized stroke renders identically at 50 % zoom and 300 % zoom, on a different screen, in a different document with matching page geometry). Controlled-component pattern: viewer emits `annotation:create` / `annotation:update` / `annotation:delete`, consumer owns the `annotations` array. Pointer modifier conventions for drawing: Shift → 15°-snapped line, Ctrl/Cmd → free-angle line, Alt → append to previous stroke. Mode is `v-model:annotation-mode`-bindable (`'view' | 'select' | 'eraser' | 'marker' | 'comment' | 'ink' | 'freetext'`). Custom color palette via `:annotation-colors`; default is 7 colors (5 pastels + 2 brights). Eraser is destructive — clicking a stroke on a marker/ink annotation deletes that stroke, deleting the last stroke fires `annotation:delete` for the whole annotation. Annotations panel on the right rail with filter chips per type, sort (by page / chronological), substring search over comments and freetext bodies.
* **`@cocoar/vue-document-viewer` — info panel**: a collapsible **Info** section at the top of the annotations panel surfaces source metadata — format string (`"PDF · v1.7"`, `"Image · PNG"`, `"Image gallery · SVG"`), total page count, current-page dimensions (live, updates as the user flips pages), and PDF metadata (title / author / subject / keywords / creator / producer / created / modified / PDF version) parsed from the pdfjs `info` bag with `D:YYYYMMDDHHmmSS±HH'mm'` dates converted to `YYYY-MM-DD HH:mm:ss`. Empty fields are skipped (no "Author:" row for PDFs without an author). File size in bytes is surfaced for PDFs (from pdfjs's `contentLength`); image / gallery sources omit it. Disable with `:show-info-section="false"` for a minimal annotations-only panel.
* **`@cocoar/vue-document-viewer` — position memory**: `storageKey: string` opts into automatic localStorage persistence of `{ page, pageOffset, zoom, rotation }`; alternatively `v-model:position` for consumer-owned persistence (server, IndexedDB, existing state manager). Both compatible — when both are present, the bound `position` wins on mount and afterwards both stay in sync.
* **`@cocoar/vue-ui` — `CoarSidebarDivider` orientation-aware**: detects the parent sidebar's `side` via `SIDEBAR_SIDE_KEY` and renders a 1 px vertical line in horizontal sidebars (top / bottom) instead of the previous border-bottom which only worked in vertical rails. Symmetric along/across margin policy across both orientations + collapsed state. Required by the new document-viewer toolbar (which uses `CoarSidebar` horizontally) and by future horizontal-toolbar consumers.
* **`@cocoar/vue-ui` — `CoarSidebarGroup.splitTrigger` prop**: when combined with `mode='flyout'`, the trigger click emits a new `triggerClick` event instead of toggling the flyout. The flyout still opens via hover (`openOnHover`) or programmatic `v-model:open`. Lets a tool toggle act as the primary action with a separate hover-revealed config panel — the canonical use case is the document-viewer's marker tool with a hover-only width/color picker, mirrored from the markdown-editor's heading dropdown.
* **`@cocoar/vue-ui` — `CoarSidebarGroup.active` prop**: selected-state styling matching `CoarSidebarItem` (side-keyed indicator border, accent color + background). Used by the document-viewer toolbar to highlight the currently-active drawing tool's flyout group.
* **`@cocoar/vue-ui` — seven new core icons** regenerated from `/assets/icons` via `pnpm build:icons`: `highlighter`, `type`, `hand`, `rotate-cw`, `rotate-ccw`, `move-horizontal`, `mouse-pointer-2`. All used by the document-viewer toolbar; available for general consumer use via `<CoarIcon name="..." />`.

### Internal

* **Docs site widening**: `--vp-layout-max-width` bumped from 1440 to 2200 px; `.VPDoc.has-aside .content-container` max-width override removed (was 688 px, now fills the layout). Kitchen Sink coupled to the same `--vp-layout-max-width` so it scales together. On wide monitors the doc content area grows from ~688 to ~1530 px instead of leaving ~30 % side gutter; small screens (under 1440 px viewport) are unchanged. The right "On this page" outline stays in place. `pdfjs-dist` is aliased to a no-op SSR stub in the docs vite config — `DOMMatrix` at module-evaluation time would otherwise break VitePress's SSR pass, and the docs demos don't render real PDFs (the live PDF demo lives in the playground), so the stub is never actually called. If a docs demo ever needs to render a real PDF, remove the alias and lazy-import the adapter inside `onMounted`.
* **Playground demo route**: `/pdf-viewer` (apps/playground) — exercises all three sources, custom toolbar layouts, annotation modes, position memory, and the per-canvas render tracking fix (open DevTools while a PDF is loaded — thumbnails should NOT go black).

***

## 2.2.1

Closes an inconsistency in the v2.2.0 router-link rollout: `CoarMenuItem` shipped without an `active` prop or `RouterLink.isActive` wiring, while `CoarSidebarItem` had both. Consumers who wanted to mark a menu item as "currently selected" (view-mode toggles, settings sub-menus with a ✓ marker, sort-direction indicators) had no built-in way to do so. This release mirrors the sidebar's pattern onto the menu so both components have parity.

### Added

* **`@cocoar/vue-ui` — `CoarMenuItem.active` prop**: typed `boolean | undefined`. Marks the item as the current selection — applies the `coar-menu-item--active` class and `aria-current="page"` attribute. When `to` is set and `active` is omitted, the state follows `<RouterLink>`'s `isActive` slot prop automatically, so consumer-computed `route.path === '/x'` checks aren't needed. Explicit `active` wins over the router-derived value, for non-route selections (e.g. "current view mode is List" — not a route, just app state). The menu still auto-closes when an active item is clicked: the active styling is meaningful while the menu is open (user sees "✓ List view"), then the menu closes and reopens later with the new selection active. Mirrors the `CoarSidebarItem.active` implementation exactly — same `props.active ?? routerIsActive` resolution, same precedence rules, same CSS-token shape. New CSS tokens `--coar-menu-item-active-color` (default `var(--coar-text-accent-primary)`) and `--coar-menu-item-active-bg` (default `var(--coar-background-accent-tertiary)`) match the sidebar's accent-treatment palette so visually the two components stay in sync. 7 new tests across the three render branches (router-installed auto-active, explicit overrides, active-still-closes-menu, no-router explicit-only, `<div>` non-route selection state). Total `CoarMenuItem.test.ts` suite: 28 (was 21).

***

## 2.2.0

This release closes a long-standing usability gap reported from the `cocoarappbase` (Multi-Tenant ASP.NET + Vue + Marten) template: the three component families that consumers most often wire to Vue Router (sidebar navigation, dropdown menu items, and call-to-action buttons) all rendered as `<div role="menuitem">` or `<button>`, so right-click → "Open in new tab", middle-click, and Ctrl/Cmd-click all silently did nothing. Apps had to fall back to `@click="router.push(...)"` and lose every native browser-link affordance. This release adds an optional `to: RouteLocationRaw | string` prop to all three families AND a new `<CoarLink>` SFC wrapper that brings the same router-aware behaviour to inline links, on top of the long-standing CSS-only `.coar-link` pattern. `vue-router` is declared as an **optional `peerDependenciesMeta`** entry — install it for SPA routing, omit it for click-emit-only / external-URL use, and the type-only import keeps consumer apps without a router type-checking cleanly under `skipLibCheck: true` (vue-tsc default). Also lands a 3-line overlay panel CSS fix that closes an `<application-base>` workaround where modals opened with `size: { width: '42rem' }` rendered ~12% narrower than configured.

### Added

* **`@cocoar/vue-ui` — `CoarSidebarItem.to` prop**: optional Vue Router target typed `RouteLocationRaw | string` (type-only import from `vue-router`, runtime-erased). When set, the item renders as `<a href>` instead of `<div role="menuitem">`, so middle-click + Ctrl/Cmd-click open the destination in a new tab via the browser's native handling, right-click exposes "Open in new tab" / "Copy link address", and screenreaders announce "link" instead of "menuitem". Routing is delegated to `<RouterLink>` when `vue-router` is installed and its plugin registered globally; otherwise falls back to a plain `<a href={String(to)}>` that uses the browser's native navigation (works for absolute URLs). The router presence check uses `resolveDynamicComponent('RouterLink')` (centralised in the new `_internal/use-router-link.ts` helper) — no hard import of `vue-router`. Active state inference is automatic: when `to` is set and `active` is left undefined, the `coar-sidebar-item--active` class and `aria-current="page"` attribute follow `RouterLink`'s internal `isActive` — drift between consumer-computed `route.path === '/x'` checks and the router's own matching is eliminated. Setting `active` explicitly still wins. Disabled handling preserved: `aria-disabled="true"`, `tabindex="-1"`, and `preventDefault` on click block navigation and emit alike. The `<a>` branch intentionally drops `role="menuitem"` since the parent `CoarSidebar` is `role="navigation"` and a native link inside `nav` is semantically complete without the role override (documented inline on the prop JSDoc); the legacy `<div>` path (no `to`) keeps `role="menuitem"` for back-compat. Consumer migration is a one-line swap. 24 integration tests across the three branches (router-installed, no-router fallback, no-`to` regression).
* **`@cocoar/vue-ui` — `CoarMenuItem.to` prop**: same shape as `CoarSidebarItem.to` — optional Vue Router target that switches the rendered tag to `<a href>` so menu items can be opened in new tabs and copy-link-addressed. `role="menuitem"` is RETAINED on the `<a>` branch (parent is `role="menu"`, the role pairing is WAI-ARIA-correct). **Modifier-click does NOT auto-close the menu** — explicit `!isModifier` guard in the close logic (refactored for clarity in this release after the original implementation accidentally conflated "don't navigate" and "don't close" in a single early-return) — when the user Ctrl/Cmd/Middle-clicks a link item, the browser handles the new-tab open natively and the menu stays open so the user can open several links in a row (matches macOS Finder + Chrome bookmarks bar behaviour). Plain click still triggers SPA navigation AND auto-closes the menu. `keepMenuOpen()` inside the `@clicked` handler continues to suppress auto-close on the link path. **Space-key navigates on link-rendered items** — Space does NOT natively activate `<a>` elements in any browser, so the keydown handler synthesizes a click on the item's `<a>` ref when `to` is set, unifying Space with the Enter / mouse-click pathway (without this, Space on a link-menu-item closed the menu without ever navigating — silent UX bug, caught in independent review). Roving-tabindex (arrow-key navigation inside the menu) works on the `<a>` branch too — registration with the menu's `MENU_NAV_KEY` happens regardless of tag. 21 integration tests cover all branches, the modifier-click / `keepMenuOpen` matrix, the Space-key regression, and the slot fallback for the `<div>` path.
* **`@cocoar/vue-ui` — `CoarButton.to` prop**: optional Vue Router target that turns the button into a real `<a href>` link so right-click / middle-click / Ctrl-click all work as expected. `CoarButton` uses `RouterLink` in **non-custom mode** (single-template `<component :is>` root, no slot wrapper) — the button has no `active` prop or `aria-current` concern, so RouterLink's built-in click handler and `guardEvent` modifier-click pass-through are sufficient. `type` and `disabled` HTML attributes are intentionally dropped on the `<a>` branch (invalid on anchors); disabled / loading state is enforced via `aria-disabled`, `tabindex="-1"`, `pointer-events: none` from CSS, and a `@click.capture` JavaScript guard that runs BEFORE RouterLink's bubble-phase `onClick` so `preventDefault` actually blocks navigation in test environments. `stopPropagation` (not `stopImmediatePropagation`) is used so capture-phase listeners on the same element — `v-tooltip` directives, consumer analytics handlers — still fire. Object-shaped `to` values (e.g. `{ name: 'docs' }`) work with router installed; without router they degrade to `String(to)` which produces `[object Object]` — a DEV-only `console.warn` (via `_internal/use-router-link.ts`) fires once per component instance to make this footgun loud at dev-time, silent in production. 24 integration tests across the three render branches.
* **`@cocoar/vue-ui` — `CoarBreadcrumbItem` `to` / `href` / `icon` / `active` props**: the breadcrumb item used to be a pure `<slot />` wrapper that forced consumers to write `<CoarBreadcrumbItem><a href="/x">Foo</a></CoarBreadcrumbItem>` for every link — the 90% case. Now picks its render strategy automatically from props: (1) `active=true` → `<span aria-current="page">` (current page is not a link to itself, WAI-ARIA convention; **`active` wins over `to`** so consumers can pass `to` on every crumb in a `.map()` loop without filtering the last item); (2) `to` + router → `<RouterLink>` custom-slot → `<a>` with SPA navigation; (3) `to` without router or `href` → plain `<a href>`; (4) none of the above → bare `<slot />` for the escape-hatch case (inline dropdowns, custom pickers, the original CSS-only API). Icon goes via either the `icon` prop (Lucide name) or the `#icon` slot (avatar, badge, coloured icon — slot overrides prop). Icon renders INSIDE the `<a>` / `<span>` so it shares the link's hit-area and hover/focus/disabled styling. Legacy `<CoarBreadcrumbItem><a href>…</a></CoarBreadcrumbItem>` slot pattern still works — it falls into mode 4. 19 new tests across the four modes + icon-precedence + composition with `<CoarBreadcrumb>`. Total breadcrumb suite 40 tests.
* **`@cocoar/vue-ui` — `<CoarLink>` SFC**: new component wrapping the long-standing `.coar-link` CSS pattern with the same router-aware ergonomics as the other three. Four render branches: (1) `to` + RouterLink available → SPA-routed `<a>` with `aria-current="page"` on match; (2) `to` set, no router → plain `<a href={String(to)}>` fallback; (3) `href` set (external link) → plain `<a>` with auto `rel="noopener"` when `target="_blank"` is set and no explicit `rel` is provided (tab-nabbing defence); (4) neither → styled `<a role="button">` for click-emit-only "fake-link" UI (Enter + Space activate). Props: `to` (router target), `href` (external URL), `variant: 'accent' | 'subtle'` (default `accent`), `size: 's' | 'm' | 'l'` (default `m`), `disabled`, `target`, `rel`. The CSS-only pattern (`<a class="coar-link">` with hand-written `href` / `<RouterLink>`) is unchanged and stays supported indefinitely — the SFC is purely additive, the styles in `packages/ui/styles/link.css` remain the source of truth so both layers share appearance. 23 tests across the four branches plus the legacy CSS-class tests.

### Changed

* **`@cocoar/vue-ui` — `to` prop typing tightened from `unknown` to `RouteLocationRaw | string`**: type-only import of `RouteLocationRaw` from `vue-router` (erased at runtime, no bundling impact). Consumers passing object route literals (`:to="{ name: 'docs', params: { id: 42 } }"`) now get full IntelliSense and structural type-checking instead of silently accepting any value. Non-router consumers reading the emitted `.d.ts` are unaffected because `skipLibCheck: true` (the modern tsconfig default, and the vue-tsc default) skips the unresolvable `vue-router` reference.

### Fixed

* **`@cocoar/vue-ui` — `CoarOverlayOutlet` panel fills its host width**: the `.coar-overlay-panel` had `display: flex` but was missing `flex: 1` and `min-width: 0`, so as a flex child of `.coar-overlay-host` it shrank to its content's intrinsic width and ignored the host width that `overlay-service.applySize` writes from `size: { width: '...' }`. Symptom: a modal opened with `overlayOptions.size: { width: '42rem' }` in a 2560 × 893 viewport rendered as `panel.width = 588px` instead of the configured 672px (an 84px / ~12% deficit), and the modal sat 42px left of the viewport center despite `position: { placement: 'center' }` because the host stayed correctly-positioned but the inner panel was content-sized. Consumer apps worked around this with a global `.coar-overlay-panel { flex: 1; min-width: 0 }` rule in their root component. Three-line patch in the SFC style block (`flex: 1` for fill, `min-width: 0` to override the default `min-width: auto` for flex children — without it a long unbreakable string in the panel content would push the panel past the host's configured width). Five new tests pin both the SFC source declarations (regression doc — anyone editing the style block must keep both rules) and the runtime cascade (`getComputedStyle()` against an injected stylesheet + service-integration test that the host receives the right inline width while the panel stays inline-width-free).

### Internal

* **`@cocoar/vue-ui` — `_internal/use-router-link.ts` shared composable**: extracted after the round-2 review flagged the soft-router-dep pattern as duplicated across components. Centralises `resolveDynamicComponent('RouterLink')` detection AND the DEV-only `console.warn` for non-string `to` without a router (silent footgun was: object `to` + no router → `href="[object Object]"` → broken link). Used by `CoarSidebarItem`, `CoarMenuItem`, `CoarButton`, `CoarLink`. The warn fires at most once per component instance, gated on `import.meta.env.DEV` so production bundles tree-shake the branch.
* **`@cocoar/vue-ui` — `vue-router` declared as optional `peerDependenciesMeta`**: previously declared as devDep only, which forced consumer-app type-checking to break unless they also installed `vue-router` (defeating the "optional" intent). Now consumers explicitly opt-in by installing `vue-router`; type-only import resolution works for both cases thanks to `skipLibCheck: true`. Still NOT a hard runtime dependency — `resolveDynamicComponent` detection is the runtime gate.
* **`@cocoar/vue-ui` — `env.d.ts` ambient module for `?raw` imports**: Vite's `import sfcSource from './Foo.vue?raw'` returns the file's source text as a string, used by SFC-source regression tests (e.g. the panel-CSS pin in `CoarOverlayOutlet.test.ts`) to assert that declarations stay in the style block without needing `@types/node` for `fs/path/url`. Single `declare module '*?raw'` line.

### Docs

* **`docs(button|sidebar|menu)` — `to` prop added to API tables + usage prose**: each of the three component pages gains a "Router Integration" / "Router-aware navigation" section with a before/after code snippet showing the migration from `@click="router.push(...)"` to `to="/path"`. New `to` row in each props table with the `RouteLocationRaw | string` type and the soft-router-dep behaviour described. Includes a "Common Pitfall" warning callout about object `to` without a router. The docs site doesn't ship a router, so the examples are static code snippets rather than `<preview>` live demos — the integration tests in `packages/ui/src/components/{sidebar,menu,button,link}/*.test.ts` are the executable spec.
* **`docs(menu)` — keyboard support section for link items**: explicitly documents the Enter / Space / Modifier+Enter behaviour difference between action items and link items.
* **`docs(link)` — rewritten to cover both the SFC and the CSS-only pattern side-by-side**: SFC examples for router-aware nav, external links with `target="_blank"` auto-rel, fake-link buttons; CSS-only escape hatch retained for advanced consumers.

***

## 2.1.0

This release introduces `@cocoar/vue-page-builder` in Preview status — a generic, headless visual page composition framework. Two components ship from the same package, sharing one `PageConfig`. Built primarily for the IDP tenant login-customisation use case, but the schema is generic enough to cover most form-style use cases (login, registration, contact) by narrowing `config.allowedElements`.

### Added

* **`@cocoar/vue-page-builder` — Preview release**: generic, headless visual page composition framework. Users drag UI primitives onto a canvas, configure them, and the result is a portable JSON schema that a companion renderer turns back into live Cocoar components. Two components ship from the same package: `<CoarPageBuilder>` (the 3-panel visual editor with outline / canvas / props panel, drag-and-drop, undo-redo, JSON paste-and-apply, responsive preview, validation) and `<CoarPageRenderer>` (the runtime renderer that maps JSON nodes to live Cocoar components and wires action IDs to consumer-provided handler functions). The JSON schema is the single artifact that flows between them — plain JSON with no library dependency, any renderer (including a custom one) can interpret it. Schema root is always a `type: 'page'` marker (cannot be added or deleted). Layout containers: `stack` (with toggleable `direction: 'column' | 'row'` — change direction in the props panel without re-creating; children stay put), `card` (CoarCard with optional title), `section` (semantic section with optional title heading), `divider`, `spacer`. Typography: `heading` (level 1-6), `paragraph`. Inputs: `text-input` (with `inputType: 'text' | 'email' | 'password' | 'url'`), `checkbox`, `select`. Actions: `button` (with `variant` / `size` / `icon` / `validates`), `link`. Media: `image` (stores `assetId`, never raw URL). All inputs support `name` (wires the value into the action payload), `disabled`, and rich `validation` (`required` / `minLength` / `maxLength` / `pattern` / `matchField` / custom `message`). Per-element architecture: each element type ships its own props component in `src/builder/props/` registered in a single map (`registry.ts`); the main `BuilderPropsPanel.vue` is a thin shell that does `<component :is="entry.component" :node :patch />`. Adding a new element type requires one new `<Type>Props.vue` file and one registry line — no central files are touched. Validation is consumer-defined (the renderer's `onValidate` prop accepts a cross-field validator that fires before action triggers; the builder runs schema-level validation reactively and surfaces issues via outline warning icons + colored banners in the props panel for missing actions, duplicate field names, and missing asset IDs). Three-panel CSS Grid shell with resizable + collapsible outline and props pane. Drop zones collapse to zero size when not dragging (gap setting accurately reflects what shows) and expand on drag start with proximity-based fade. Responsive preview toggle in the Preview tab (Desktop / Tablet · 768 / Mobile · 375) with a capped, centered frame. Keyboard shortcuts: `Ctrl+Z` / `Ctrl+Y` undo/redo, `Delete` / `Backspace` removes the selected node when focus is not in an input. Three docs pages at `/components/page-builder/` (Overview), `/components/page-builder/coar-page-builder`, `/components/page-builder/coar-page-renderer`, plus a complete IDP integration walkthrough on the overview page covering shared config helper + admin builder mount + runtime login renderer.
* **`@cocoar/vue-page-builder` — `PageConfig` consumer contract**: a single config object passed to BOTH the builder and the renderer. `allowedElements?: ElementType[]` is enforced at both layers — the builder hides disallowed types from the palette and add-child menu; the renderer skips them at render time (with one console warning per type) even if they appear in hand-written or tampered JSON. This is the hard security boundary. `availableActions?: { id, label }[]` turns the Action ID input on Button/Link from free text into a labeled dropdown; stored IDs that aren't in the list surface as `auth:something (not configured)` so orphans don't silently disappear. `assetResolver?: (id) => string` resolves asset IDs to URLs — same contract as the renderer's `:asset-resolver` prop, used by the builder for thumbnails (canvas preview, props panel, Preview-tab renderer) and by the runtime renderer for `<img src>`. `pickAsset?: (currentId?) => Promise<string | null>` opens the consumer's own asset picker UI and resolves to the chosen asset id or `null` on cancel — **the library does NOT ship a picker dialog**, the consumer owns the entire picker UX (browse, upload, search, delete, categorisation, …) and the page-builder just gets the id back. A reference picker implementation lives in `apps/playground/src/components/PlaygroundAssetPicker.vue`. The renderer's `actions` map is the real security boundary for buttons / links — only handlers present there fire; everything else is a silent no-op. Arbitrary JavaScript is never stored in the schema.

### Internal

* **`@cocoar/vue-page-builder` — `useSchemaValidation` composable**: reactive `Map<nodeId, issues[]>` computed once over the entire schema. Built-in rules: button/link without action, action not in `availableActions`, image without assetId, duplicate field names across `text-input` / `checkbox` / `select` nodes. The result is provided via the `BUILDER_VALIDATION` inject key and consumed by `BuilderOutlineNode.vue` (warning icon + tooltip per affected row) and `BuilderPropsPanel.vue` (colored banner stack at the top of the selected node's properties). Validation is purely a UX scaffold — the renderer ignores it entirely; renderer enforcement happens via `allowedElements` and the `actions` map.

### Docs

* **`docs(page-builder)` — three new docs pages**: `/components/page-builder/` (overview with Quick start + Architecture + PageConfig contract + Security Model + complete IDP integration walkthrough + Roadmap), `/components/page-builder/coar-page-builder` (builder API + features + validation + per-element architecture), `/components/page-builder/coar-page-renderer` (renderer API + Schema reference + Built-in Elements reference + Security boundary). Page Builder marked Preview in sidebar and on every page heading. The integration walkthrough on the overview page contains three numbered steps with full Vue file contents — shared `buildLoginConfig(tenantId)` helper, admin app builder mount with save-to-backend, runtime login page renderer wiring.

***

## 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/theming.md
---
# Theme Editor

The **Theme Editor** is a live token editor built into every Cocoar app. It lets you explore the entire token system — from raw palette shades all the way to semantic roles — and export a ready-to-paste CSS snippet.

> The editor is visible as a small icon in the bottom-right corner of this page. Click it to try everything described here in real time.

## Setup

Add `CoarThemeEditor` to your app's layout. It renders as a floating panel — no wrapper or portal needed.

```ts
import CoarThemeEditor from '@cocoar/vue-ui/theme-editor';
```

```vue
<!-- In your root layout -->
<CoarThemeEditor />
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `hideDarkToggle` | `boolean` | `false` | Hides the light/dark toggle. Set to `true` when your app manages dark mode itself. |

## The Token Tree

Cocoar's token system has three layers. Each layer builds on the one above it.

```
Layer 1 — Primitives
  --coar-color-red-600          oklch-formula of --coar-error

Layer 2 — Semantic
  --coar-background-semantic-error-bold   → var(--coar-color-red-600)

Layer 3 — Component
  --coar-button-danger-bg                 → var(--coar-background-semantic-error-bold)
```

Changing a primitive ripples through semantic tokens, which ripple through every component that uses them. The Theme Editor exposes all three layers.

## Tabs

### Presets

Four built-in starting points: **Enterprise** (default), **Modern SaaS** (rounded), **Playful** (pill buttons, vivid accent), and **Minimal** (sharp corners, no shadows). Selecting a preset resets all other tabs to the preset's values.

### Brand

Sets the five base hue values that anchor the entire palette:

| Token | Default | Purpose |
|-------|---------|---------|
| `--coar-accent` | `#1183CD` | Primary actions, links, focus rings |
| `--coar-success` | `#1e8f48` | Positive feedback |
| `--coar-error` | `#d63b3b` | Errors, destructive actions |
| `--coar-warning` | `#cc821f` | Caution |
| `--coar-info` | `#5e6b84` | Neutral informational |

Each color opens a **palette editor** (floating panel) where you can fine-tune the L (lightness) and C (chroma) for individual steps 50–900 using oklch relative color syntax.

### Semantic

Maps semantic roles to palette entries. Each row shows the resolved color, lets you pick a palette (Accent / Red / Green / Amber / Slate) and a step (50–900), and has a reset button that turns accent-colored when changed.

This is the layer that connects intent to color: `--coar-background-semantic-error-bold` points at `Red / 600` by default. Reassigning it to `Amber / 600` would make all error surfaces amber — including form field borders, toast backgrounds, and the danger button — without touching any component code.

### Corners

Controls the global radius scale (`xxs` → `xl`) plus per-component-group overrides for buttons, inputs, cards, menus, popovers, dialogs, and toasts. Select from named scale steps or `Full` (pill shape).

### Type

Font family for body text and headings, chosen from a curated list of Google Fonts. Fonts load on demand when selected.

### Spacing

Component density slider: **Compact** (0.75×), **Default** (1×), or **Comfortable** (1.33×). Scales horizontal padding on all interactive components.

### Depth

Box shadow per component group (buttons never have shadows; cards, menus, dialogs, and toasts do).

### Motion

A single duration multiplier that scales all `--coar-duration-*` tokens proportionally. Set to 0 for instant transitions, or push it above 2× to slow everything down for testing.

## Exporting

Type a class name into the name field at the bottom of the editor (default: `custom`), then click **Download CSS** to get a scoped block containing only the tokens you changed:

```css
/* coar-theme--myapp.css */
.coar-theme--myapp {
  --coar-accent: #7C3AED;
  --coar-button-radius: var(--coar-radius-m);
  --coar-input-radius: var(--coar-radius-m);
}
```

Drop it into your app after the Cocoar stylesheet and apply the class to your root element:

```html
<!-- index.html -->
<html class="coar-theme--myapp">
<head>
  <link rel="stylesheet" href="@cocoar/vue-ui/styles" />
  <link rel="stylesheet" href="/coar-theme--myapp.css" />
</head>
```

Or import in your entry file:

```ts
import '@cocoar/vue-ui/styles';
import './coar-theme--myapp.css';
```

Because themes are classes, you can apply different themes to different subtrees:

```html
<html class="coar-theme--myapp">
  <!-- most of the app uses the custom theme -->

  <div class="coar-theme--compact">
    <!-- this section uses a separate theme -->
  </div>

  <div class="coar-theme-none">
    <!-- this section always uses library defaults -->
  </div>
</html>
```

### `.coar-theme-none`

The library ships a built-in reset class. Apply `.coar-theme-none` to any element to restore all themeable tokens to their library defaults inside that subtree, regardless of what theme class is set on an ancestor. Useful for "always default" widgets like admin panels or embedded forms.

---

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

## Router Integration

Pass `to` to render the button as a real `<a href>` link instead of a `<button>`. The button keeps its full visual styling — variants, sizes, icons, loading spinner — but right-click → "Open in new tab", middle-click, and Ctrl/Cmd-click all work as expected via the browser's native link handling. Screenreaders announce "link" instead of "button".

```vue
<!-- Before — modifier-clicks silently did nothing -->
<CoarButton variant="primary" @click="router.push('/docs')">
  Open documentation
</CoarButton>

<!-- After — full browser link affordances -->
<CoarButton variant="primary" to="/docs">
  Open documentation
</CoarButton>
```

If `vue-router` is installed and registered (`app.use(router)`), the button renders via `<RouterLink>` and plain clicks trigger SPA navigation. Without a router it falls back to a plain `<a href={String(to)}>` that uses the browser's native navigation — useful for external links.

```vue
<!-- External link — works with or without vue-router -->
<CoarButton variant="ghost" iconEnd="external-link" to="https://docs.cocoar.dev">
  Documentation
</CoarButton>
```

`@click` still emits on plain click for telemetry and other consumer side-effects. Modifier-clicks (Ctrl/Cmd/Shift/Alt/middle-button) pass through to the browser without SPA navigation, so the user can open the destination in a new tab. `disabled` and `loading` block both navigation and the emit; the `type` attribute is only applied when rendering as `<button>` (it is invalid on `<a>`).

::: info
`vue-router` is declared as an **optional `peerDependenciesMeta`** entry of `@cocoar/vue-ui` — install it if you want SPA routing, omit it for click-emit-only / external-URL use. Apps without a router can use `<CoarButton>` exactly as before; setting `to` to a string URL still gives you a proper `<a href>` for browser navigation.
:::

::: warning Object `to` without router
Passing an object literal (`:to="{ name: 'docs' }"`) when no router is installed falls back to `String(to)`, producing `href="[object Object]"` — a broken link. The component logs a DEV-only `console.warn` once per component instance to make this loud at dev-time. Pass a string path for the no-router case.
:::

## 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 (ignored when `to` is set — invalid on `<a>`) |
| `to` | `RouteLocationRaw \| string` | `undefined` | Vue Router target. When set, renders as `<a href>` via `<RouterLink>` (or plain `<a>` if no router is installed). Enables right-click / middle-click / Ctrl+click new-tab behaviour and "Copy link address". See [Router Integration](#router-integration). |

### 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 an inline error indicator around any form control. Instead of each input managing its own label and validation display, `CoarFormField` handles these concerns in one place.

::: tip Field-status indicator
`hint`, `warning`, and `error` all surface through one **status icon** in the label row, opening a popover that lists everything that applies. The icon picks the most severe state: error → red `circle-alert`, else warning → orange `triangle-alert`, else hint → grey `info`. When nothing is set, no icon renders.

The icon is conditionally rendered — when it appears the label-text shifts right by `icon-width + gap`. That small horizontal nudge is the attention signal; the form's vertical geometry stays stable. Hover the icon for a peek, click to pin the popover open.
:::

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

## Status Indicator

Toggle hint / warning / error individually and watch the icon shift severity and the popover stack content in priority order (hint → errors → warnings). Hover the icon, or click to pin.

## Live Rules

Pass a `rules` array for live-evaluated validation. Each rule has a `label`, a `fulfilled: boolean` (the consumer computes this from reactive state — Vue re-evaluates on every state change), and optional `whenPass` / `whenFail` flags that control what to render in each state. **Defaults**: `whenPass: 'success'` and `whenFail: 'pending'` — that's the password-checklist UX (✓ green when fulfilled, ○ grey when not), so a bare `{ label, fulfilled }` rule is the common case.

Import the named types for IntelliSense:

```ts
import type {
  CoarFormFieldRule,             // the rule object
  CoarFormFieldRulePassMode,     // 'success' | 'hide'
  CoarFormFieldRuleFailMode,     // 'pending' | 'warning' | 'error' | 'hide'
} from '@cocoar/vue-ui';

const rules: CoarFormFieldRule[] = [...];
```

### Display modes

The two-axis `whenPass` / `whenFail` covers every common pattern:

| `whenPass` | `whenFail` | Pattern | Example |
|---|---|---|---|
| `'success'` (default) | `'pending'` (default) | Progress checklist | Password policies — ✓ green when met, ○ grey when not |
| `'hide'` | `'error'` | Live validation | "Max 20 chars" — disappears when ok, red error when not |
| `'hide'` | `'warning'` | Live advisory | "Looks like a tracking link" — disappears when fine, orange warning when not |
| `'success'` | `'error'` | Required with progress tick | Hard requirement that's also part of a checklist |

The defaults (`whenPass: 'success'`, `whenFail: 'pending'`) give you the password-checklist pattern with zero extra config.

### Trigger-icon severity

The icon reflects **what's visible in the popover** — pick the highest-severity section that has at least one entry:

1. Popover has ≥1 entry in the **Errors** section → red `circle-alert`
2. else popover has ≥1 entry in the **Warnings** section → orange `triangle-alert`
3. else popover has ≥1 **success** item (a fulfilled `whenPass: 'success'` rule, i.e. a green ✓) → green `check-circle-2`
4. else popover has ≥1 **pending** checklist item or a hint → grey `info`
5. else → no icon at all

Notice that **success wins over pending** — once the user has fulfilled *any* rule, the icon flips green for positive reinforcement. The unfulfilled rules still appear as ○ in the popover so the user can hover to see the "could do more" detail; the icon just doesn't shout orange about them.

For genuinely **required** rules (must-do-this), use `whenFail: 'error'` — those make the field invalid and the icon stays red until satisfied. Pending is for **optional** progress (part of an X-of-Y, polish-up rules, or any "could do more for strength but already valid" pattern). The Save-button-disabled state binds to `hasError` (or the `aria-invalid` attribute on the input), not to the icon color.

### Why no green check for `whenPass: 'hide'` rules

A rule whose natural state is "no problem" shouldn't show a green checkmark when satisfied — there's nothing to celebrate; the field is just fine. The trigger icon stays unset unless something is actively wrong or you have explicit `whenPass: 'success'` rules to show progress.

### Icon ≠ Validity — composing rules for "Save disabled" UX

**The icon shows visual state. `hasError` (via the `FORM_FIELD_INJECTION_KEY`) shows validity.** They're related but deliberately decoupled — `whenFail: 'pending'` and `whenFail: 'warning'` rules contribute to the icon but **not** to `hasError`. Only `whenFail: 'error'` rules (plus the `error` string-prop) make the field invalid.

That decoupling is intentional. It lets you express more than "every rule is mandatory":

#### Pattern: each rule individually required

Each rule both shows progress AND drives validity. `whenFail: 'error'` on every entry — the rule appears in the popover's Errors section while unfulfilled, flips to a green ✓ in the checklist when fulfilled.

```ts
const rules = computed<CoarFormFieldRule[]>(() => [
  { label: 'At least 8 chars', fulfilled: pw.length >= 8, whenFail: 'error' },
  { label: 'Contains an uppercase letter', fulfilled: /[A-Z]/.test(pw), whenFail: 'error' },
  // …
]);
```

#### Pattern: X of Y must be satisfied

The 4 individual rules stay as `pending` progress (default), and a 5th **aggregate rule** with `whenFail: 'error'` checks the count. Both coexist in the popover — the user sees per-rule progress AND why the field is currently invalid. The Save button binds to the aggregate's `fulfilled` flag (or to the field's injected `hasError`), not to the icon.

The same pattern handles any aggregate constraint: "at least 2 tags selected", "between 5 and 50 items", "either email OR phone filled" — one extra rule with `whenFail: 'error'` does the gating.

::: tip Why the icon goes green at 3/4 (not orange)
The severity model picks the highest-severity item visible in the popover. With 3 ✓ and 1 ○ showing, success wins over pending — the icon goes green. The unfulfilled rule stays as ○ in the popover so the user can hover to see "could do more for strength", but the summary icon respects that validity is passing. See [Trigger-icon severity](#trigger-icon-severity) for the full priority order.
:::

## On-Submit Validation

The canonical on-submit-validation pattern: every required field starts clean, the user fills what they like, hits **Submit**, and any missing / invalid fields flip to the error state. The error icon appears in the label row, shifting the label-text right by `icon-width + gap` — a small horizontal nudge that catches the eye **without** any vertical row push that would move the Submit button or rearrange the form.

The shift is the point. A reserved-slot approach (icon hidden via `visibility` to keep the label at a fixed offset) would be visually quieter but would also lose the cue — users wouldn't notice the state change. The icon-in-label-with-shift pattern strikes the balance: noticeable, but never disorienting.

## 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 and wires them through `aria-describedby` on the child input:

* **Label**: `<label for="...">` points to the input — clicking the label focuses the control.
* **Hint** / **errors** / **warnings**: each rendered as a visually-hidden span with its own ID. The child input's `aria-describedby` is the **space-separated list** of all currently-present IDs (hint first, then every error, then every warning). Screen readers read them all on focus.
* **Errors** additionally carry `role="alert"` so they're announced when they appear (warnings + hint are silent — they're descriptive, not urgent).
* **`aria-invalid="true"`** on the input is driven by `error` only; warnings keep the input valid.
* **Required**: asterisk is `aria-hidden="true"` — use `required` on the input itself for semantics.

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | `undefined` | Label text rendered next to the status icon. |
| `hint` | `string` | `''` | Informational help text. Sits at the top of the popover (grey). When it's the only thing set, the icon is a grey `info` glyph. |
| `error` | `string \| readonly string[]` | `[]` | Validation error(s). Drives the red `circle-alert` icon + `aria-invalid="true"` on the child input. Single string is sugar for a one-item array. Each entry is announced as a `role="alert"` to screen readers. |
| `warning` | `string \| readonly string[]` | `[]` | Non-blocking warning(s). Drives the orange `triangle-alert` icon (when no error is also set). The input stays valid; SR announcements are non-urgent. |
| `rules` | `readonly CoarFormFieldRule[]` | `[]` | Live-validation rules. Each rule has `label`, `fulfilled: boolean`, and optional `whenPass: 'success' \| 'hide'` (default `'success'`) + `whenFail: 'pending' \| 'warning' \| 'error' \| 'hide'` (default `'pending'`). See [Live Rules](#live-rules) for the four common patterns. Rules with `whenFail: 'error'` drive the input's `aria-invalid="true"`. |
| `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 for in-page navigation, external references, and any clickable text that isn't a button action. Two equivalent APIs:

* **`<CoarLink>` SFC** (recommended) — `to` for router navigation, `href` for external links, automatic `rel="noopener"` for new-tab safety, disabled handling.
* **CSS classes** — `<a class="coar-link">` with hand-written `href` / `<RouterLink>` for consumers who want zero abstraction.

Both layers share the same CSS in `@cocoar/vue-ui/styles`. Mix them freely.

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

## Basic usage

```vue
<!-- Router navigation (when vue-router is installed) -->
<CoarLink to="/docs">Documentation</CoarLink>

<!-- External link with safe new-tab default -->
<CoarLink href="https://docs.cocoar.dev" target="_blank">
  Cocoar Docs
</CoarLink>

<!-- mailto / tel still works via href -->
<CoarLink href="mailto:hi@example.com">hi@example.com</CoarLink>
```

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.

```vue
<CoarLink to="/docs" variant="subtle">Read the docs</CoarLink>
```

## Sizes

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

```vue
<CoarLink href="#" size="s">Small</CoarLink>
<CoarLink href="#" size="m">Medium (default)</CoarLink>
<CoarLink href="#" size="l">Large</CoarLink>
```

## Disabled state

Pass `disabled` to deactivate the link visually and semantically. The component sets `aria-disabled="true"`, `tabindex="-1"`, and intercepts clicks — navigation and `@click` emit are both suppressed.

```vue
<CoarLink to="/admin" disabled>Admin (insufficient permissions)</CoarLink>
```

## Inline usage

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

## Router Integration

When `to` is set, the link renders via `<RouterLink>` (if `vue-router` is installed and `app.use(router)` has registered the plugin) for SPA navigation. Without a router, it falls back to a plain `<a href={String(to)}>` that works for absolute URLs. The router detection uses `resolveDynamicComponent('RouterLink')` — no hard dependency, no peerDependency requirement.

```vue
<!-- SPA navigation when router available -->
<CoarLink to="/docs">Documentation</CoarLink>

<!-- Object-shaped routes work too (with router) -->
<CoarLink :to="{ name: 'docs', params: { section: 'intro' } }">
  Intro
</CoarLink>
```

`aria-current="page"` is applied automatically when the current route matches `to` (via `RouterLink.isActive`).

::: warning Object `to` without router
Passing an object literal (`{ name: 'docs' }`) when no router is installed falls back to `String(to)`, producing `href="[object Object]"` — a broken link. The component logs a DEV-only `console.warn` once per call site to make this loud. Pass a string path for the no-router case.
:::

## External Links

For absolute URLs and `mailto:` / `tel:` schemes, use `href` instead of `to`. The component skips the router entirely and renders a plain `<a>`. When `target="_blank"` is set, `rel="noopener"` is added automatically as a tab-nabbing defence (browsers do this by default since 2021, but the explicit attribute documents intent and works in older browsers).

```vue
<CoarLink href="https://github.com/cocoar-dev" target="_blank">
  GitHub
</CoarLink>
<!-- Renders: <a href="..." target="_blank" rel="noopener" class="coar-link"> -->
```

You can override the auto-rel by passing your own:

```vue
<CoarLink
  href="https://untrusted.example.com"
  target="_blank"
  rel="noopener noreferrer external"
>
  External (extra-cautious)
</CoarLink>
```

## CSS-only usage (no SFC)

If you only need the styling and want to wire the link element yourself (typically inside a `<RouterLink>` slot, breadcrumb, or templated context), apply the CSS classes directly to a native `<a>`:

```vue
<RouterLink to="/docs" custom v-slot="{ href, navigate, isActive }">
  <a
    :href="href"
    class="coar-link"
    :class="{ 'coar-link--disabled': !canVisit }"
    @click="navigate"
  >
    Documentation
  </a>
</RouterLink>
```

This is the original API and stays supported indefinitely — the SFC is purely additive.

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `to` | `RouteLocationRaw \| string` | `undefined` | Vue Router target. Takes precedence over `href`. Renders via `<RouterLink>` if installed, else falls back to plain `<a href={String(to)}>`. |
| `href` | `string` | `undefined` | External URL. Used when `to` is not set. Works for `https:`, `mailto:`, `tel:`, etc. |
| `variant` | `'accent' \| 'subtle'` | `'accent'` | Visual variant. `accent` for primary links, `subtle` for blending into body text. |
| `size` | `'s' \| 'm' \| 'l'` | `'m'` | Typography size. |
| `disabled` | `boolean` | `false` | Disabled state (aria-disabled, tabindex=-1, click suppressed). |
| `target` | `string` | `undefined` | Anchor target attribute. Only applied to the plain `<a>` branches (not via `<RouterLink>`). |
| `rel` | `string` | *(see below)* | Anchor rel attribute. Auto-fills to `noopener` when `target="_blank"` is set and no explicit `rel` is provided. |

### Events

| Event | Payload | Description |
|-------|---------|-------------|
| `click` | `MouseEvent` | Emitted on every plain click (not when disabled). Modifier-clicks (Ctrl/Cmd/Middle) pass through to the browser. |

### Slots

| Slot | Description |
|------|-------------|
| `default` | Link content (text, icons, anything inline). |

### CSS Classes (legacy / advanced)

| Class | Description |
|-------|-------------|
| `.coar-link` | Base link style — accent color, underline on hover |
| `.coar-link--subtle` | Subtle variant with less color emphasis |
| `.coar-link--s` / `--m` / `--l` | Typography size |
| `.coar-link--disabled` | Disabled appearance (combine with `aria-disabled="true"`) |

---

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

## Router-aware items

Pass `to` to `CoarMenuItem` to render it as a real `<a href>` link instead of `<div role="menuitem">`. Same payoff as on the sidebar: middle-click and Ctrl/Cmd-click open the destination in a new tab via the browser's native handling, right-click exposes "Open in new tab" / "Copy link address", and screenreaders announce "link to {label}". `role="menuitem"` is preserved on the `<a>` branch (the parent `CoarMenu` is `role="menu"`, so the role pairing is WAI-ARIA-correct).

```vue
<CoarMenu>
  <CoarMenuItem icon="user" label="Profile" to="/profile" />
  <CoarMenuItem icon="settings" label="Settings" to="/settings" />
  <CoarMenuDivider />
  <CoarMenuItem icon="log-out" label="Logout" @clicked="auth.signOut()" />
</CoarMenu>
```

**Modifier-clicks do NOT auto-close the menu.** When the user Ctrl/Cmd/Middle-clicks a link item the browser opens a new tab natively and the menu stays open — matches the macOS Finder / Chrome bookmarks bar pattern, lets the user fire several link items in a row without re-opening the menu. Plain click still triggers SPA navigation and auto-closes the menu (subject to `keepMenuOpen()` in your `@clicked` handler).

::: info
`vue-router` is declared as an **optional `peerDependenciesMeta`** entry of `@cocoar/vue-ui` — install it for SPA routing, omit it for click-emit-only use. Items without `to` keep the original `<div role="menuitem">` rendering and the `@clicked` event pathway exactly as before.
:::

::: warning Object `to` without router
Passing an object literal (`:to="{ name: 'profile' }"`) when no router is installed falls back to `String(to)`, producing `href="[object Object]"` — a broken link. The component logs a DEV-only `console.warn` once per component instance to make this loud at dev-time. Pass a string path for the no-router case.
:::

## Active state

Use `active` to mark a menu item as the current selection — view-mode toggles, settings checkmarks, sort-direction indicators. The library renders the `coar-menu-item--active` class + `aria-current="page"`. When `to` is set and `active` is omitted, the state follows `<RouterLink>`'s `isActive` automatically.

```vue
<CoarMenu>
  <CoarMenuItem icon="list" :active="view === 'list'" @clicked="view = 'list'">
    List view
  </CoarMenuItem>
  <CoarMenuItem icon="grid" :active="view === 'grid'" @clicked="view = 'grid'">
    Grid view
  </CoarMenuItem>
</CoarMenu>
```

The menu still auto-closes on click — active styling is meaningful while the menu is open (the user sees what's currently selected), then the menu closes and reopens later showing the new selection as active.

### Keyboard support on link items

When `to` is set the menu item renders as `<a href>`, so the keyboard pathway differs slightly from action items:

* **Enter** — delegated to the browser, which fires a native click on the `<a>`. RouterLink navigation runs, the menu auto-closes.
* **Space** — synthesizes a click on the underlying anchor element (Space does not natively activate `<a>` in any browser). Same outcome as Enter / mouse click: navigation + auto-close.
* **Modifier+Enter** — browser opens a new tab natively; the menu stays open so the user can fire additional link items.

`@clicked` fires for all three pathways. `keepMenuOpen()` still suppresses auto-close on the link path.

## 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 |
| `to` | `RouteLocationRaw \| string` | `undefined` | Vue Router target. When set, renders as `<a href>` via `<RouterLink>` (or plain `<a>` if no router is installed). Modifier-clicks open a new tab without closing the menu. See [Router-aware items](#router-aware-items). |
| `active` | `boolean` | `undefined` | Mark the item as the current selection (view-mode toggle, settings checkmark, sort indicator). Renders `coar-menu-item--active` + `aria-current="page"`. Defaults to `<RouterLink>`'s `isActive` when `to` is set; explicit value always wins. The menu still auto-closes on click — active state is meaningful WHILE the menu is open. |
| `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.

## Router-aware navigation

Pass `to` to `CoarSidebarItem` to render it as a real `<a href>` link instead of `<div role="menuitem">`. The item keeps its full visual styling — collapsed mode, tooltips, side-aware indicator border, all sidebar tokens — but the user gains native browser link behaviour: right-click → "Open in new tab" / "Copy link address", middle-click + Ctrl/Cmd-click open a new tab, and screenreaders announce "link" instead of "menuitem".

```vue
<!-- Before — modifier-clicks silently did nothing -->
<CoarSidebarItem
  icon="layout-dashboard"
  label="Dashboard"
  :active="route.path === '/dashboard'"
  @click="router.push('/dashboard')"
/>

<!-- After — full browser link affordances + auto isActive -->
<CoarSidebarItem
  icon="layout-dashboard"
  label="Dashboard"
  to="/dashboard"
/>
```

When `to` is set and `active` is omitted, the highlighted state and `aria-current="page"` attribute follow `<RouterLink>`'s internal `isActive` automatically — no more `route.path === '/x'` drift. Setting `active` explicitly still wins:

```vue
<!-- Manual override — keep "Settings" highlighted while a child modal is open -->
<CoarSidebarItem
  icon="settings"
  label="Settings"
  to="/settings"
  :active="modal.isOpen || undefined"
/>
```

Items without `to` keep the original `<div role="menuitem">` rendering and the `@click` emit pathway — use this for action items that don't map to a route (logout, drawer-toggle, external help link):

```vue
<CoarSidebarItem icon="log-out" label="Logout" @click="auth.signOut()" />
```

::: info
`vue-router` is declared as an **optional `peerDependenciesMeta`** entry of `@cocoar/vue-ui` — install it for SPA routing, omit it for click-emit-only / external-URL use. Apps without a router can still use `<CoarSidebarItem>` with `@click` exactly as before. Setting `to` to a string URL (`to="https://docs.example.com"`) falls back to a plain `<a href>` that works without a router.
:::

::: warning Object `to` without router
Passing an object literal (`:to="{ name: 'dashboard' }"`) when no router is installed falls back to `String(to)`, producing `href="[object Object]"` — a broken link. The component logs a DEV-only `console.warn` once per component instance to make this loud at dev-time. Pass a string path for the no-router case.
:::

## 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) |
| `to` | `RouteLocationRaw \| string` | `undefined` | Vue Router target. When set, renders as `<a href>` via `<RouterLink>` (or plain `<a>` if no router is installed). Enables native browser link behaviour (new-tab, copy address). See [Router-aware navigation](#router-aware-navigation). |
| `active` | `boolean` | `undefined` | Highlight as current page. Defaults to `<RouterLink>`'s `isActive` when `to` is set; explicit value always wins. |
| `disabled` | `boolean` | `false` | Disabled state |

**Events:** `@click` — standard `MouseEvent` (emitted on both the `<div>` and `<a>` branches for telemetry / side-effects)

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

## Fill-Height Tabs

By default `CoarTabGroup` is content-sized — the panel grows to fit whatever you put inside it. Settings panes, form sections, anything documentation-shaped wants that. For **editor / viewer / file-explorer** tabs, where the content is expected to stretch (Monaco, PDF viewer, anything VSCode-shaped), opt in with the `fill` prop.

The consumer is still responsible for sizing the tab-group root — `fill` only propagates the height **down** through the internal wrappers. Typical wiring:

```vue
<!-- Your view -->
<div class="my-view">
  <CoarTabGroup fill>
    <CoarTab id="editor">
      <template #content>
        <MonacoEditor />          <!-- now sees a flex parent that fills -->
      </template>
    </CoarTab>
  </CoarTabGroup>
</div>

<style scoped>
.my-view {
  display: flex;
  flex-direction: column;
  height: 100%;
}
.my-view :deep(.coar-tab-group) {
  flex: 1;
  min-height: 0;
}
</style>
```

::: tip Why opt-in?
Without `fill`, the content wrapper is `display: block` — the active panel sizes to its children. That's the right default for the common case (form tabs, settings). Auto-fill would silently break every existing consumer whose tabs sit inside a taller container. Flipping it via a typed prop keeps the change additive and discoverable.
:::

## 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 |
| `fill` | `boolean` | `false` | Make the active panel fill the remaining vertical space below the tab bar. Opt-in for editor / viewer / file-explorer tabs. See [Fill-Height Tabs](#fill-height-tabs). |

### 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/tree.md
---
# Tree

A generic, keyboard-navigable, drag-drop-aware tree primitive. Identity, children and label are extracted via prop functions — render any node shape (file systems, navigation, settings, categories, …) without forcing a common base type.

```ts
import {
  CoarTree,
  useTree,
  type CoarTreeNodeMoveEvent,
  type CoarTreeFilesDropEvent,
} from '@cocoar/vue-ui';
```

::: info Two APIs
`<CoarTree>` works in two modes:

* **Props-mode** — pass `nodes`, `getId`, `getChildren`, etc. as props; wire `<CoarContextMenu>` yourself. Good for simple cases.
* **Builder-mode** — `useTree()` returns a fluent builder. Declarative per-target context menus are rendered internally, the imperative `api` lets you focus nodes from outside the component. Recommended for anything beyond the basics.

The two compose — but pick one per `<CoarTree>` instance; mixing props and builder on the same instance is a footgun.
:::

::: tip Desktop-first
`<CoarTree>` is an explicit exception to the library's tablet-first principle. Right-click context menus and hover-revealed UI on rows (⋮ buttons, inline actions) are part of the intended UX. The component still works on touch devices but isn't tuned for them — use it for power-user surfaces (file managers, settings explorers, asset trees) rather than mobile navigation.
:::

## Playground

Flip every option on or off, switch density, filter, drag-reorder, rename, drive the imperative `api`, and watch the event log — the whole feature surface in one sandbox.

## Basic Tree

Pass a list of root nodes and four extractors: `getId`, `getChildren`, `getLabel`, and optionally `isExpandable`. Render the row body via the default slot. Two `v-model`s — `expanded` (a `Set<string>` of node ids) and `selected` (a single id or `null`) — let the consumer control state.

## Selection

`selectionMode` picks one of three behaviours (default `'single'`, fully back-compatible):

| Mode | Bound to | Interaction |
|------|----------|-------------|
| `'single'` | `v-model:selected` (`string \| null`) | One highlighted row |
| `'multiple'` | `v-model:selectedIds` (`Set<string>`) | Ctrl/Cmd-click toggles, Shift-click ranges, `Ctrl/Cmd+A` selects all, Shift+Arrow extends |
| `'checkbox'` | `v-model:checkedIds` (`Set<string>`) + `v-model:selectedIds` | A per-row tri-state checkbox **independent** of the highlight selection |

In **checkbox** mode the checkbox state (`checkedIds`) and the highlight (`selectedIds`) are separate models — a row can be focused/highlighted while a different set is checked. Checking a folder cascades to its descendants and a partially-checked folder shows the indeterminate (`mixed`) state; checking a folder whose children aren't loaded yet propagates the check to them once they arrive (lazy inheritance). Set `check-strictly` for independent parent/child checks with no cascade.

```vue
<script setup lang="ts">
const selectedIds = ref(new Set<string>())
const checkedIds = ref(new Set<string>())
</script>

<template>
  <CoarTree
    selection-mode="checkbox"
    v-model:selected-ids="selectedIds"
    v-model:checked-ids="checkedIds"
    :nodes="nodes" :get-id="n => n.id" :get-children="n => n.children"
  />
</template>
```

## Drag-and-Drop Reorder

Set `draggable` to allow internal moves. Drop **between** sibling rows to reorder; drop **into** a folder (middle 50 % of the row) to move it inside. The tree rejects self-onto-descendant drops, draws a 2-pixel indicator line for `before`/`after` and a dashed outline for `inside`, and auto-expands collapsed folders after a short hover.

The consumer handles the actual mutation in `@node-move` — splice the source out of its current parent and re-insert it at the target's location.

## OS File Drop

Set `accepts-files` to receive operating-system file drops onto folder rows or the empty background. The tree emits `@files-drop` with the raw `FileList` plus the target folder (or `null` when dropped on the background). Use this for asset uploaders, image inboxes, or any flow where the user drags files in from outside the browser.

## App-internal drops (drag something onto a node)

`accepts-files` is for **OS** files. For an **in-app** drag — a card dragged out of your grid, a chip from a palette — set `accepts-data` to the MIME type(s) your source registered, and handle `@data-drop`. The tree reuses the same drop highlight, auto-expand-on-hover, and `before`/`inside`/`after` position as node reordering, but emits a generic event so your handler decides what the drop means (move the asset into the folder, link it, etc.).

```vue
<!-- your grid card -->
<div draggable="true" @dragstart="e => e.dataTransfer.setData('application/x-myapp-asset', asset.id)">…</div>

<!-- the tree -->
<CoarTree
  :builder="builder"
  :accepts-data="['application/x-myapp-asset']"
  @data-drop="onDataDrop"
/>
```

```ts
function onDataDrop({ node, position, dataTransfer }) {
  const assetId = dataTransfer.getData('application/x-myapp-asset') // read at drop time
  const targetFolderId = node?.id ?? null                          // null = dropped on the background
  moveAssetToFolder(assetId, targetFolderId)
}
```

Internal node drags (`@node-move`) are never delivered as `@data-drop` even when `accepts-data` is set — the two channels don't cross. The `DataTransfer` is only valid inside the handler (the browser neuters it afterwards), so read your payload synchronously.

## Context Menu + ⋮ Button

`@context-menu` fires on right-click of any row and on background right-click (`node` is `null`). Wire it to a single `useContextMenu()` controller — the menu's contents adapt to whether a folder, file, or background was hit. The same controller doubles as the click handler for a hover-revealed `⋮` button per row, giving keyboard / left-click users equal access.

## Builder API

`useTree<T>()` returns `{ builder, api }`. Configure data, behavior, handlers and three context menus in a single fluent chain — the tree renders the `<CoarContextMenu>` itself, so the template is just `<CoarTree :builder>`.

### Context menus per target

Three setters, one per target type. Each callback returns an array of menu entries (`{ label, icon?, danger?, disabled?, onClick }` or the literal string `'divider'`):

```ts
builder
  .folderMenu(folder => [
    { label: 'Upload here', icon: 'upload', onClick: () => upload(folder.id) },
    { label: 'New subfolder', icon: 'plus', onClick: () => newFolder(folder.id) },
    'divider',
    { label: 'Delete', icon: 'trash-2', danger: true, onClick: () => del(folder) },
  ])
  .leafMenu(leaf => [
    { label: 'Open', icon: 'file', onClick: () => openFile(leaf) },
    { label: 'Delete', icon: 'trash-2', danger: true, onClick: () => del(leaf) },
  ])
  .viewportMenu(() => [
    { label: 'New folder', icon: 'plus', onClick: () => newFolder(null) },
  ]);
```

| Setter | Fires on | Receives |
|--------|----------|----------|
| `.folderMenu(folder => [])` | Right-click an expandable node | The folder node |
| `.leafMenu(leaf => [])` | Right-click a non-expandable node | The leaf node |
| `.viewportMenu(() => [])` | Right-click empty tree background | Nothing (`null` target) |

If a setter is omitted for a target, no menu opens on that target. Items without an `icon` align flush left; the tree allocates the icon column when *any* item in the menu uses an icon.

### Escape hatch — raw events

When you want a fully custom popover (form inputs, async sub-menus, third-party menu component) instead of the standard menu, use the event variants. They **override** the declarative setters for that target:

```ts
builder.onLeafContextMenu((leaf, ev) => {
  ev.preventDefault();
  myCustomPopover.openAt(ev.clientX, ev.clientY, leaf);
});
```

| Event setter | Overrides |
|--------------|-----------|
| `.onFolderContextMenu((folder, ev) => …)` | `.folderMenu` |
| `.onLeafContextMenu((leaf, ev) => …)` | `.leafMenu` |
| `.onViewportContextMenu((ev) => …)` | `.viewportMenu` |

### The `api`

`useTree()`'s second return value is a narrow imperative interface — call from anywhere without needing a template ref:

```ts
const { builder, api } = useTree<MyNode>();

// readonly refs (suitable for watch / computed)
api.selectedId   // Ref<string | null>
api.expandedIds  // Ref<Set<string>>

// readonly refs (multiple / checkbox modes)
api.selectedIds  // Ref<Set<string>>
api.checkedIds   // Ref<Set<string>>

// imperative (warn until mounted)
api.selectNode('some-id')       // highlight-select + focus (preferred)
api.focusNode('some-id')        // alias of selectNode (back-compat since 2.4.0)
api.expandTo('some-id')         // reveal a deep node
api.revealNode('some-id')       // scroll into view without stealing focus
api.moveNode('a', 'b', 'after') // accessible/programmatic move
api.getNode('some-id')          // resolve node by id, or null
api.reloadChildren('some-id')   // re-run loadChildren (retry / refresh)
api.startRename('some-id')      // enter inline-rename (needs `renamable`)
api.startCreate('some-id')      // open inline-create draft under a parent (needs `creatable`)
```

## Lazy loading (async children)

Fetch a node's children the first time it's expanded — for trees backed by an API where loading everything up front isn't an option. Two pieces:

* **`isExpandable`** must return `true` for a folder *before* its children exist (otherwise there's no chevron to expand). Derive it from the node's own "is a folder" flag, not from `getChildren`.
* **`loadChildren(node)`** fires on first expand of an unloaded folder. Return a `Promise` and the tree shows a spinner in the chevron until it settles; on rejection the row flips to an error state and `@load-error` fires. Your handler attaches the fetched children to your own `nodes` data — the tree re-renders and stops asking (a node counts as loaded once `getChildren` returns an array; `[]` is loaded-but-empty). Attach so `nodes` updates reactively — produce a **new root `nodes` reference** (`nodes.value = [...]`) or keep `nodes` deeply reactive; a pure in-place mutation on a shallow source leaves the spinner spinning. An unrelated `nodes` change never re-fires a node that already attempted-and-settled — retry is explicit (`api.reloadChildren(id)` or collapse + re-expand).

The demo below is interactive — dial in **latency** and a **failure rate** to watch the loading spinner, the error + **Retry** path, and the load-once-then-cache behaviour, then drill in to see each level load on its own. It renders the spinner at the row-icon position (the `hide-loading-spinner` + `isLoading` pattern below) rather than the built-in chevron spinner.

```ts
const { builder, api } = useTree<FsNode>();
builder
  .nodes(tree)
  .getId(n => n.id)
  .getChildren(n => n.children)            // undefined until loaded; [] = loaded-but-empty
  .isExpandable(n => n.kind === 'folder')  // expandable BEFORE children exist
  .loadChildren(async (node, { signal }) => {
    const kids = await myApi.fetchChildren(node.id, { signal }); // aborts on collapse
    attachChildren(node.id, kids);         // mutate your own `nodes` data
  })
  .maxConcurrentLoads(6)                   // cap fan-out for rate-limited backends (0 = unlimited)
  .onLoadError(({ node, error }) => toast.error(`Couldn't open ${node.name}`));
```

`loadChildren`'s second argument carries an `AbortSignal` that fires when the folder is collapsed or leaves the tree mid-flight — forward it to `fetch` so a cancelled load doesn't waste work or race a later reopen. A load that settles after being aborted is suppressed (no phantom error). `maxConcurrentLoads` (default `0` = unlimited) bounds simultaneous loads so an `expandAll()` / state-restore can't fan out unbounded.

The `default` slot exposes `isLoading` and `hasError` per row, and `api.reloadChildren(id)` forces a re-fetch — wire it to a retry button (or a "refresh folder" action):

```vue
<template #default="{ node, hasError }">
  <FileRow :node="node" />
  <button v-if="hasError" @click.stop="api.reloadChildren(node.id)">Retry</button>
</template>
```

::: tip Default loading + error visuals
By default the chevron shows a spinner while loading and a red **retry** icon on error (click it to re-fetch) — no extra markup needed. Set `hide-loading-spinner` to suppress **both** and render your own from `isLoading` / `hasError`. Collapsing then re-expanding an errored folder also retries.
:::

::: tip Render your own loading indicator
Prefer a spinner that replaces the row icon (or anything else)? Set `hide-loading-spinner` to suppress the built-in chevron spinner and render your own from the `isLoading` slot prop — the tree still owns the *when* (expand-trigger, dedupe, error state), you own the *look*:

```vue
<CoarTree :builder="builder" hide-loading-spinner>
  <template #default="{ node, isLoading }">
    <Spinner v-if="isLoading" />
    <Icon v-else :name="node.icon" />
    <span>{{ node.label }}</span>
  </template>
</CoarTree>
```

:::

## Virtualization

For trees with hundreds or thousands of visible rows, enable virtualization to mount only the rows actually inside the viewport. The component is built on `useVirtualList` — fixed-known-size virtualizer, no DOM auto-measure — so you declare the row height once.

### Scale (50 000 nodes)

Virtualization plus the flat-render pipeline scales to tens of thousands of nodes. Hit **Expand all** to flatten ~51 200 rows into the visible list — only ~30 row components stay mounted, and selecting / arrow-keying / dragging stays smooth. Expand-all is O(1) in the virtualizer for the constant row height, and a selection or drag-over re-renders only the rows that actually change.

**Configuration:**

```ts
// builder mode
builder.virtualize(true);                                      // defaults: itemSize 28, overscan 5
builder.virtualize({ itemSize: 32 });                          // uniform 32-px rows
builder.virtualize({ itemSize: (i) => myHeights[i] });         // variable per visible-row
builder.virtualize({ itemSize: 28, overscan: 10 });            // larger scroll buffer

// props mode
<CoarTree :virtualize="true" ... />
<CoarTree :virtualize="{ itemSize: 32 }" ... />
```

**Requirements + caveats:**

* **Explicit height.** The tree owns its scroll container when virtualized. Put it in a sized parent (fixed `height`, flex with `flex: 1` + `min-height: 0`, grid cell with `1fr`, etc.). Without a measurable viewport `useVirtualList` produces an empty render.
* **Row height must match.** The configured `itemSize` is what the spacer + absolute positioning use. If your slot renders a row taller than `itemSize`, content overflows; shorter and there's empty space. Measure your row in DevTools and configure accordingly.
* **No auto-measurement.** This is a fixed-known-size virtualizer (unlike TanStack Virtual's `measureElement`). For trees with truly dynamic row heights (e.g. wrapping multi-line labels), keep virtualization off — performance is fine up to ~500 visible rows even without it.
* **Both modes use flat rendering.** Whether virtualized or not, the tree renders rows as a flat DFS list (depth via `padding-left`, ARIA hierarchy via `aria-level`). `<ul role="group">` nesting was dropped on purpose — it's optional under WAI-ARIA and incompatible with flat virtualization.

## Accessibility

### Keyboard

| Key | Action |
|-----|--------|
| `↑` / `↓` | Move focus to previous / next visible row (skips disabled). Hold `Shift` (multi modes) to extend the selection |
| `→` / `←` | Expand / descend, collapse / ascend (inverted under RTL) |
| `Home` / `End` | First / last visible (enabled) row |
| `PageUp` / `PageDown` | Move focus by one viewport of rows |
| `*` | Expand all sibling folders at the focused row's level |
| `Enter` | Activate (emits `@activate`) — typically opens the node |
| `Space` | Checkbox mode: toggle the row's checkbox. Otherwise: expand a folder / select a leaf |
| `Ctrl`/`Cmd` + `A` | Select all visible rows (multiple / checkbox) |
| `Ctrl`/`Cmd` + `X` … `V` | Grab the focused row, then drop it relative to the focused target (accessible move); `Escape` cancels |
| `F2` | Start an inline rename on the focused row (needs `renamable`) |
| Letter | Type-ahead: jump to the next visible row whose label starts with the typed prefix (resets after 500 ms) |

### ARIA

* Root has `role="tree"` — give it an accessible name via `ariaLabel` / `ariaLabelledby`. `aria-multiselectable="true"` in multiple / checkbox modes.
* Each row has `role="treeitem"` with `aria-level`, `aria-posinset`, `aria-setsize`. `aria-selected` is set on **every** row (`true` on selected, `false` otherwise — the APG multi-select pattern). Checkbox rows also carry `aria-checked` (`true` / `false` / `mixed`); disabled rows `aria-disabled`; loading rows `aria-busy`.
* A polite **live region** announces drag / keyboard-move state (pick-up, dropped, cancelled) and lazy-load **errors**. All strings are overridable via [`labels`](#i18n-labels).
* **Flat rendering** — rows are a single DFS list, not nested `<ul role="group">`. Hierarchy is conveyed by `aria-level` (WAI-ARIA permits this and it's what enables flat virtualization; see [Virtualization](#virtualization)).

## Inline rename

Set `renamable` to opt into built-in inline editing. Drop `<CoarTreeNodeLabel>` into the default slot in place of your label span — it swaps to an `<input>` while its row is being renamed and picks up the rename machinery via injection (no extra wiring). Start a rename from a context-menu item or button with `api.startRename(id)`, or press **F2** on the focused row. Commit on Enter / blur fires `@rename`; Escape (or an empty name) fires `@rename-cancel`. Conflict handling / validation is the consumer's job — the tree is stateless about it, so on failure just call `api.startRename(id)` again.

```vue
<script setup lang="ts">
import { CoarTree, CoarTreeNodeLabel, useTree } from '@cocoar/vue-ui'
const { builder, api } = useTree<FsNode>()
builder
  .nodes(tree).getId(n => n.id).getChildren(n => n.children).getLabel(n => n.name)
  .renamable(true)
  .onRename(({ node, newName }) => applyRename(node.id, newName))
  .folderMenu(folder => [{ label: 'Rename', icon: 'pencil', onClick: () => api.startRename(folder.id) }])
</script>

<template>
  <CoarTree :builder="builder">
    <template #default="{ node }">
      <CoarIcon :name="node.children ? 'folder' : 'file'" size="xs" />
      <CoarTreeNodeLabel :label="node.name" />
    </template>
  </CoarTree>
</template>
```

## Inline create

The counterpart to inline rename. Set `creatable` and call `api.startCreate(parentId, opts?)` to insert a **transient draft row** at its target position — `parentId: null` creates at the root, otherwise the parent auto-expands and the draft renders nested under it. The draft shows a focused `<input>` with the same blur-grace timer as rename; **Enter / blur** commits and fires `@create` with `{ parentId, name, kind }`, while **Escape** or an empty name fires `@create-cancel`. The draft is purely transient: persist the node in your `@create` handler and feed the real one back via your data source — the tree drops the draft on commit.

`opts`: `kind` (`'folder'` | `'leaf'`, default `'folder'` — picks the default icon and is echoed back on `@create`), `initialName` (prefill, default `''`), `position` (`'first'` | `'last'` within the parent, default `'last'`). Override the default draft icon with the optional `#draft` slot (`{ kind, depth }`).

```vue
<script setup lang="ts">
import { CoarTree, CoarTreeNodeLabel, useTree } from '@cocoar/vue-ui'
const { builder, api } = useTree<FsNode>()
builder
  .nodes(tree).getId(n => n.id).getChildren(n => n.children).getLabel(n => n.name)
  .creatable(true)
  .onCreate(({ parentId, name, kind }) => createNode(parentId, name, kind))
  .folderMenu(folder => [
    { label: 'New folder', icon: 'folder-plus', onClick: () => api.startCreate(folder.id, { kind: 'folder' }) },
  ])
  .viewportMenu(() => [
    { label: 'New folder', icon: 'folder-plus', onClick: () => api.startCreate(null) },
  ])
</script>

<template>
  <CoarTree :builder="builder">
    <template #default="{ node }">
      <CoarIcon :name="node.children ? 'folder' : 'file'" size="xs" />
      <CoarTreeNodeLabel :label="node.name" />
    </template>
    <!-- optional: custom draft icon -->
    <template #draft="{ kind }">
      <CoarIcon :name="kind === 'folder' ? 'folder' : 'file'" size="xs" />
    </template>
  </CoarTree>
</template>
```

Pairs with `@cocoar/vue-file-explorer-core`'s optimistic `addFolder` so the draft → real-node handoff has no flicker.

### Async validation — keep the draft open on rejection

If creation can fail server-side (a duplicate-name 409, a permission check), you don't want the user's typed name discarded. Two paths, depending on which API form you use:

* **Builder form** — return a `Promise` from `onCreate`. The tree keeps the draft mounted + focused (name intact) until it settles: it drops the draft on resolve and **reopens it on reject** so the user can fix the name and retry.

  ```ts
  builder.creatable(true).onCreate(async ({ parentId, name }) => {
    await api.createFolder(parentId, name) // throws on 409 → draft stays open
  })
  ```

* **Prop / event form** — Vue's `emit` can't return a value, so reopen imperatively: on a rejected `@create`, re-call `startCreate` with `initialName` to restore the draft with the typed text.

  ```ts
  async function onCreate({ parentId, name }) {
    try {
      await createFolder(parentId, name)
    } catch {
      treeRef.value?.startCreate(parentId, { initialName: name }) // reopen, name preserved
    }
  }
  ```

> Both `creatable` / `@create` / `@create-cancel` and `api.startCreate` work in **prop-mode** too (without `useTree()`): `startCreate` is on the component's template ref alongside `startRename`.

## Disabled nodes

`isDisabled(node)` marks rows non-interactive: they can't be selected, activated, directly checked, focused by keyboard, matched by type-ahead, or dragged, and they render `aria-disabled` + dimmed. The `isDisabled` slot prop lets you adjust your own row content. Cascade from a *checked ancestor* still flows through a disabled descendant — disabled blocks **direct** interaction, not bulk parent operations.

```ts
builder.isDisabled(n => n.readonly)
```

## Search / filter

Pass the matching ids as `matchedIds` and the tree handles the rest. Two modes:

* **Highlight (default):** every row stays visible; the slot gets `isMatch` / `isMatchAncestor` for styling, and the ancestors of each match auto-expand so deep hits are revealed (add-only — your manual collapses survive).
* **Filter** (`filter` prop / `.filter()`): non-matches are hidden — but the **ancestor path of each match stays visible as "virtual parents"** (flagged `isMatchAncestor`, so you can de-emphasize them). The tree never collapses into a contextless flat list; you always see *where* a hit lives. Computing `matchedIds` itself stays yours (any fuzzy / regex / field match you like).

  `filterMode` (mirrors PrimeVue) decides what a matched **folder** keeps:

  * **`'strict'`** (default) — matches + ancestor path only; a matched folder's non-matching children stay hidden. This is the VS Code / react-arborist "filter down to what I searched for" convention.
  * **`'lenient'`** — a matched folder reveals its whole subtree.

```vue
<script setup>
const matchedIds = computed(() => {
  const q = query.value.toLowerCase()
  if (!q) return undefined
  return new Set(allNodes.value.filter(n => n.name.toLowerCase().includes(q)).map(n => n.id))
})
</script>

<template>
  <CoarTree :builder="builder" :matched-ids="matchedIds" :filter="hideNonMatches">
    <template #default="{ node, isMatch, isMatchAncestor }">
      <span :class="{ hit: isMatch, 'virtual-parent': isMatchAncestor }">{{ node.name }}</span>
    </template>
  </CoarTree>
</template>
```

## Density & theming

`density` (`xs` / `s` / `m` / `l`, default `m`) scales the **whole** row — font, padding, indent, **and** the built-in chevron + checkbox (box and glyph) together. Under the hood it sets CSS variables you can also override directly to retheme without forking:

| Variable | Default (`m`) | Controls |
|----------|---------------|----------|
| `--coar-tree-indent` | `14px` | Per-level indent step |
| `--coar-tree-indent-base` | `8px` | Base (level-0) indent |
| `--coar-tree-row-pad-y` / `-x` | `3px` / `4px` | Row padding |
| `--coar-tree-row-font` | inherits body-small | Row font size |
| `--coar-tree-control-size` | `16px` | Chevron + checkbox box size |
| `--coar-tree-icon-size` | `12px` | Glyph inside (checkmark / dash / chevron) |

The icons **you** render in the slot are still yours to size — but `--coar-tree-icon-size` cascades into the slot, so you can scale them with the tree:

```vue
<template #default="{ node }">
  <CoarIcon :name="node.children ? 'folder' : 'file'" size="var(--coar-tree-icon-size)" />
  <span>{{ node.name }}</span>
</template>
```

::: warning
When virtualizing, set `virtualize.itemSize` to match your density's row height — the virtualizer is fixed-size and doesn't auto-measure.
:::

## i18n / labels {#i18n-labels}

Every built-in string (chevron Expand / Collapse, the loading spinner, the retry button, the inline-create input's `aria-label`, and all the polite drag / move / load-error announcements) is overridable via `labels` for localization. Unset fields fall back to the English `DEFAULT_TREE_LABELS`.

```ts
builder.labels({
  expand: 'Aufklappen',
  collapse: 'Zuklappen',
  loading: 'Lädt …',
  retry: 'Erneut',
  draftFolderName: 'Name des neuen Ordners',
  draftFileName: 'Name der neuen Datei',
  moveCancelled: 'Verschieben abgebrochen.',
})
```

## Recipes

### Truncation in narrow sidebars

The tree owns indentation and the chevron but doesn't render the label — the consumer does, via the default slot. The standard pattern is **ellipsis + `v-tooltip` with `onlyOnOverflow: true`** on the label span — the styled Coar tooltip appears only when the text is actually clipped, and stays out of the way when the full label is visible:

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

<template #default="{ node }">
  <!--
    The tooltip lives on a wrapper around the icon + label — NOT the label
    alone. When the row gets so narrow that the label collapses to 0 px
    (deep nesting in a slim sidebar), the icon still has a hit area and the
    tooltip remains reachable. The string form of `onlyOnOverflow` tells the
    directive to gate on the *child label's* overflow, not the wrapper's.
  -->
  <span
    v-tooltip="{ content: node.label, onlyOnOverflow: '.label' }"
    class="row-main"
  >
    <CoarIcon :name="node.children ? 'folder' : 'file'" size="xs" />
    <span class="label">{{ node.label }}</span>
  </span>
</template>

<style>
.row-main {
  display: flex;
  align-items: center;
  gap: 6px;
  flex: 1;
  min-width: 0;
}
.label {
  flex: 1;
  min-width: 0;            /* allow shrink inside the flex row */
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}
</style>
```

`onlyOnOverflow` accepts three forms — all evaluated lazily on hover/focus, no `ResizeObserver` overhead:

| Form | Meaning |
|------|---------|
| `true` | Check `scrollWidth > clientWidth` on the trigger element itself |
| `string` (CSS selector) | Check overflow on the matched descendant — use when the tooltip is on a wrapper but only an inner element is what gets truncated |
| `function: (el) => boolean` | Custom predicate; return `true` to show the tooltip |

::: tip Scale
A tree with hundreds of mounted rows means hundreds of `v-tooltip` directive listeners. Combine this pattern with [virtualization](#virtualization) for very large trees — only the ~visible rows hold listeners. For low-overhead plain-text fallback (e.g. mobile / embedded contexts where the overlay system isn't installed), use the native `:title` attribute instead — same UX, zero JS.
:::

### File-explorer shell

Combine `<CoarTree>` with `CoarTabGroup`, `CoarScriptEditor`, `CoarMarkdownEditor`, and `CoarDocumentViewer` to get a VS-Code-style document explorer. The tree owns the asset hierarchy and DnD; tabs hold the open editors; per-row `⋮` and right-click expose CRUD actions through a single `<CoarContextMenu>`.

### Multi-tree drag

Two `<CoarTree>` instances on the same page can exchange nodes via the shared `application/x-coar-tree-node` MIME type. Each tree's `@node-move` only fires when the drop lands on one of its own rows — you decide on the consumer side how to coordinate the source/target trees (e.g. a parent component that owns both data stores).

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `builder` | `TreeBuilder<T>` | `undefined` | Fluent builder from `useTree()`. When set, the other config props are ignored. Recommended for non-trivial cases |
| `nodes` | `readonly T[]` | — | Root nodes (required in props-mode; ignored when `builder` is set) |
| `getId` | `(node: T) => string` | — | Identity extractor. Must be unique across the entire visible tree (required in props-mode) |
| `getChildren` | `(node: T) => readonly T[] \| null \| undefined` | `undefined` | Returns the children of a node — return `undefined` or `null` for leaves. Without it, the tree is a flat list |
| `getLabel` | `(node: T) => string` | `undefined` | Used by type-ahead navigation. Optional but recommended for keyboard UX |
| `isExpandable` | `(node: T) => boolean` | derived from `getChildren` | Override branch detection — useful when a folder should always render as expandable even if its children are lazy-loaded |
| `isDisabled` | `(node: T) => boolean` | `undefined` | Mark nodes non-interactive: no select / activate / check / keyboard-focus, `aria-disabled`, dimmed. See [Disabled nodes](#disabled-nodes) |
| `loadChildren` | `(node: T, ctx: { signal: AbortSignal }) => void \| Promise<void>` | `undefined` | Lazily fetch a node's children on first expand. Pair with `isExpandable`. `ctx.signal` aborts on collapse / removal. See [Lazy loading](#lazy-loading-async-children) |
| `maxConcurrentLoads` | `number` | `0` | Cap simultaneous in-flight `loadChildren` calls (extra ones queue). `0` = unlimited. Set a small number (e.g. `6`) for rate-limited backends |
| `hideLoadingSpinner` | `boolean` | `false` | Suppress the built-in chevron spinner **and** retry affordance. Set it when you render your own from `isLoading` / `hasError` |
| `selectionMode` | `'single' \| 'multiple' \| 'checkbox'` | `'single'` | See [Selection](#selection). `single` → `v-model:selected`; `multiple`/`checkbox` → `v-model:selectedIds` (+ `v-model:checkedIds` for checkbox) |
| `checkStrictly` | `boolean` | `false` | Checkbox mode only: independent parent/child checks, no cascade / indeterminate |
| `draggable` | `boolean \| ((n: T) => boolean)` | `false` | Allow internal drag-to-reorder. Pass a function to enable per-node |
| `canDrop` | `(source: T, target: T \| null, position: 'before' \| 'inside' \| 'after') => boolean` | `undefined` | Veto drops on top of the built-in cycle guard. Advisory — `source` is the dragstart snapshot; integrity is guaranteed regardless |
| `getDragImage` | `(node: T) => HTMLElement \| string \| null \| undefined` | `undefined` | Custom drag ghost (element or HTML string); falls back to the default row image |
| `activateOnClick` | `boolean` | `false` | Fire `activate` on a single click too (not only double-click / Enter) |
| `renamable` | `boolean` | `false` | Opt into built-in inline rename (`api.startRename` / F2 / `@rename`). See [Inline rename](#inline-rename) |
| `creatable` | `boolean` | `false` | Opt into built-in inline create (`api.startCreate` / `@create`). See [Inline create](#inline-create) |
| `acceptsFiles` | `boolean` | `false` | Accept OS file drops onto folder rows / the background |
| `acceptsData` | `string[]` | `undefined` | MIME type(s) of app-internal drags to accept as a drop (e.g. a card from a grid). Fires `@data-drop`. See [App-internal drops](#app-internal-drops-drag-something-onto-a-node) |
| `autoExpandDelay` | `number` | `700` | Milliseconds the cursor must hover before a collapsed folder auto-expands during a drag |
| `virtualize` | `boolean \| { itemSize?, overscan? }` | `false` | Enable row virtualization. `true` uses defaults (28-px rows, 5-row overscan); pass an object to customize |
| `density` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Row spacing preset (sets the spacing CSS vars). With virtualization, match `virtualize.itemSize` to the density's row height |
| `ariaLabel` | `string` | `undefined` | Accessible name on the `role="tree"` element |
| `ariaLabelledby` | `string` | `undefined` | Id of an external label element for the `role="tree"` element |
| `labels` | `Partial<CoarTreeLabels>` | English defaults | Override built-in / screen-reader strings (chevron, spinner, retry, announcements) for i18n |
| `matchedIds` | `Set<string>` | `undefined` | Search hits — drives `isMatch` / `isMatchAncestor` slot props + auto-expand-to-match. See [Search / filter](#search-filter) |
| `filter` | `boolean` | `false` | With `matchedIds`, hide non-matches but keep the matches + their ancestor path ("virtual parents"). See [Search / filter](#search-filter) |
| `filterMode` | `'strict' \| 'lenient'` | `'strict'` | What a matched **folder** keeps when filtering. `strict` = matches + path only; `lenient` = the matched folder's whole subtree. See [Search / filter](#search-filter) |
| `v-model:expanded` | `Set<string>` | empty `Set` | Ids of expanded folders. Replaced with a fresh `Set` on each change to trigger reactivity |
| `v-model:selected` | `string \| null` | `null` | Selected row id (**single** mode) |
| `v-model:selectedIds` | `Set<string>` | empty `Set` | Highlight selection (**multiple** / **checkbox** modes) |
| `v-model:checkedIds` | `Set<string>` | empty `Set` | Checkbox selection (**checkbox** mode), independent of the highlight |

### Events

| Event | Payload | Fires |
|-------|---------|-------|
| `activate` | `(node: T)` | Double-click on a row or `Enter` on the focused row (also single click if `activateOnClick`) |
| `select` | `({ node: T \| null, ids: readonly string[], via: 'user' \| 'api' })` | The highlight selection changed. `node` = the row acted on, `ids` = the full selection after, `via` = user gesture vs `api` call |
| `context-menu` | `(node: T \| null, ev: MouseEvent)` | Right-click on a row (`node` set) or background (`node` is `null`). The default action is suppressed automatically by `useContextMenu().open(ev)` |
| `files-drop` | `({ files: FileList, target: T \| null })` | OS files dropped on a folder (`target` set) or empty background (`target` is `null`). Only fires when `accepts-files` is `true` |
| `data-drop` | `({ node: T \| null, position, dataTransfer: DataTransfer })` | An app-internal drag (an `accepts-data` MIME) dropped on a row (`node` set) or background (`node` is `null`). Read your payload via `dataTransfer.getData(mime)` in the handler |
| `node-move` | `({ source: T, target: T \| null, position })` | Internal drag-drop OR keyboard move / `api.moveNode`. `position` is `'before'`, `'inside'`, or `'after'`. `target: null` + `'inside'` means "move to root" |
| `rename` | `({ node: T, newName: string })` | An inline rename committed (Enter / blur, non-empty). Needs `renamable`. See [Inline rename](#inline-rename) |
| `rename-cancel` | `(node: T)` | An inline rename cancelled (Escape, or committed empty) |
| `create` | `({ parentId: string \| null, name: string, kind: 'folder' \| 'leaf' })` | An inline create committed (Enter / blur, non-empty). Needs `creatable`. See [Inline create](#inline-create) |
| `create-cancel` | — | An inline create cancelled (Escape, or committed empty) |
| `load-error` | `({ node: T, error: unknown })` | A lazy `loadChildren` promise rejected. Only fires when `loadChildren` is set |
| `update:expanded` | `(Set<string>)` | Folder expanded / collapsed |
| `update:selected` | `(string \| null)` | Selection changed (single mode) |
| `update:selectedIds` | `(Set<string>)` | Highlight selection changed (multiple / checkbox modes) |
| `update:checkedIds` | `(Set<string>)` | Checkbox selection changed (checkbox mode) |

### Slots

| Slot | Props | Description |
|------|-------|-------------|
| `default` | `{ node, depth, isExpanded, isSelected, isChecked, isIndeterminate, isFocused, isExpandable, isMatch, isMatchAncestor, isDisabled, isRenaming, isLoading, hasError }` | Row body. The tree renders indentation, chevron, checkbox (checkbox mode), focus ring and drop indicators; you render the icon, label, inline action buttons, dirty markers, etc. |
| `empty` | — | Shown when `nodes` is empty. Defaults to nothing — provide your own empty-state copy |
| `draft` | `{ kind: 'folder' \| 'leaf', depth }` | Leading content (icon) for the inline-create draft row. Defaults to a folder/file icon. Needs `creatable`. See [Inline create](#inline-create) |

The `default` slot props in full:

| Prop | Meaning |
|------|---------|
| `isSelected` | In the highlight selection (`selected` / `selectedIds`) |
| `isChecked` / `isIndeterminate` | Checkbox fully / partially checked (checkbox mode) |
| `isMatch` / `isMatchAncestor` | A search hit / an ancestor of one (see [Search / filter](#search-filter)) |
| `isDisabled` | `isDisabled(node)` returned true |
| `isRenaming` | This row is in inline-rename mode |
| `isLoading` / `hasError` | Lazy `loadChildren` in flight / failed |

### Exposed methods

Available on both the **template ref** and the builder **`api`** (the `api` warns if called before mount; `getNode` returns `null`):

| Method | Description |
|--------|-------------|
| `selectNode(id)` | Highlight-select **and** focus a node (the "reveal & select" action) — preferred |
| `focusNode(id)` | Builder `api`: alias of `selectNode` (selects + focuses, back-compat since 2.4.0). Template ref: focus-only. Prefer `selectNode` / `revealNode` for explicit intent |
| `expandAll()` / `collapseAll()` | Expand every loaded, expandable node / collapse everything |
| `expandTo(id)` | Expand all loaded ancestors of `id` so its row becomes visible |
| `revealNode(id)` | Scroll a node into view **without** stealing focus (expands ancestors first) |
| `getNode(id)` | Resolve a node by id from the loaded tree, or `null` |
| `moveNode(sourceId, targetId, position)` | Move a node (keyboard / a11y equivalent of a drop); runs the cycle + `canDrop` guards; returns whether it emitted |
| `reloadChildren(id)` | Force `loadChildren` to (re)run — retry after an error or refresh a loaded folder |
| `startRename(id)` | Enter inline-rename mode on a node (needs `renamable`) |
| `startCreate(parentId, opts?)` | Open an inline-create draft under `parentId` (`null` = root); needs `creatable`. `opts`: `{ kind?, initialName?, position? }` |

### Constants

| Constant | Value | Use |
|----------|-------|-----|
| `COAR_TREE_DRAG_MIME` | `'application/x-coar-tree-node'` | Mime type set on `DataTransfer` for internal drags. Read it on `drop` if you're orchestrating drags between two trees that share an outer container |

---

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

Pass `to` to render each crumb as a link. The library handles the `<a>` element for you — no need to wrap content in a manual anchor. Mark the last item `active` to indicate the current page; it renders as a non-interactive `<span aria-current="page">` (current page is not a link to itself, per WAI-ARIA convention).

```vue
<CoarBreadcrumb>
  <CoarBreadcrumbItem to="/projects" icon="folder">Projects</CoarBreadcrumbItem>
  <CoarBreadcrumbItem to="/projects/alpha">Alpha</CoarBreadcrumbItem>
  <CoarBreadcrumbItem to="/projects/alpha/issues">Issues</CoarBreadcrumbItem>
  <CoarBreadcrumbItem active>#142 Fix date picker</CoarBreadcrumbItem>
</CoarBreadcrumb>
```

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

## Three render modes

`CoarBreadcrumbItem` picks its render strategy automatically from the props:

| Mode | Trigger | Renders as |
|------|---------|------------|
| **Active** | `:active="true"` | `<span aria-current="page">` — non-interactive, current page |
| **Router-aware link** | `:to="..."` and `vue-router` installed | `<a href>` via `<RouterLink>` (SPA navigation, middle-click new-tab, etc.) |
| **Plain link** | `:to="..."` without router, or `:href="..."` | `<a href>` with browser-native navigation |
| **Bare slot (escape hatch)** | none of the above | Whatever the slot contains (custom dropdown, button, plain text…) |

**Active wins over `to`**: you can pass `to` on every crumb (including the last) without filtering — the `active` flag is the single source of truth for "this is the current page". Useful when generating the trail programmatically from `router.matched`.

```vue
<!-- All four crumbs in one loop, no special-case for the last item -->
<CoarBreadcrumb>
  <CoarBreadcrumbItem
    v-for="(crumb, i) in trail"
    :key="crumb.path"
    :to="crumb.path"
    :icon="crumb.icon"
    :active="i === trail.length - 1"
  >
    {{ crumb.label }}
  </CoarBreadcrumbItem>
</CoarBreadcrumb>
```

## Icons

Pass `icon` for a Lucide-style leading icon, or use the `#icon` slot for custom content (avatar, badge, coloured icon).

```vue
<CoarBreadcrumb>
  <!-- Named icon via prop -->
  <CoarBreadcrumbItem to="/" icon="home">Home</CoarBreadcrumbItem>

  <!-- Custom icon via #icon slot — overrides icon prop -->
  <CoarBreadcrumbItem to="/teams/alpha">
    <template #icon>
      <CoarAvatar :src="team.avatarUrl" size="xs" />
    </template>
    {{ team.name }}
  </CoarBreadcrumbItem>

  <CoarBreadcrumbItem active>Settings</CoarBreadcrumbItem>
</CoarBreadcrumb>
```

The icon renders inside the `<a>` / `<span>` so it shares the link's hit-area and styling (hover, focus, disabled states all apply uniformly).

## Custom content (dropdown, picker, etc.)

When `to` / `href` / `active` are all omitted, the item falls back to rendering the bare slot. Use this for inline UI like a project-switcher dropdown embedded in the trail:

```vue
<CoarBreadcrumb>
  <CoarBreadcrumbItem to="/projects">Projects</CoarBreadcrumbItem>

  <!-- Bare-slot mode: library renders just the <li>, you control the rest -->
  <CoarBreadcrumbItem>
    <CoarSelect
      v-model="currentProject"
      :options="availableProjects"
      size="s"
      variant="ghost"
    />
  </CoarBreadcrumbItem>

  <CoarBreadcrumbItem active>Settings</CoarBreadcrumbItem>
</CoarBreadcrumb>
```

This also covers the legacy CSS-only pattern (`<CoarBreadcrumbItem><a href="/x">Foo</a></CoarBreadcrumbItem>`) — consumer-slotted anchors keep working without changes.

## Router Integration

When `to` is set and `vue-router` is registered (`app.use(router)`), the item renders via `<RouterLink>` in custom-slot mode for SPA navigation. Without a router, it falls back to a plain `<a href={String(to)}>`. The detection uses `resolveDynamicComponent('RouterLink')` — no hard dependency on `vue-router`.

::: info
`vue-router` is declared as an **optional `peerDependenciesMeta`** entry. Install it for SPA routing, omit it for static / `href`-only / bare-slot use.
:::

::: warning Object `to` without router
Passing an object literal (`:to="{ name: 'projects' }"`) when no router is installed falls back to `String(to)`, producing `href="[object Object]"` — a broken link. The component logs a DEV-only `console.warn` once per component instance. Pass a string path for the no-router case.
:::

## Sizes

Two sizes:

* **`m`** (default, 14 px) — primary navigation. Sits at the top of a page above the page title.
* **`s`** (13 px) — secondary chrome. File-explorer paths, settings trails, address-bar style indicators sitting above other content.

```vue
<CoarBreadcrumb separator="›" size="s" aria-label="File path">
  <CoarBreadcrumbItem>src</CoarBreadcrumbItem>
  <CoarBreadcrumbItem>components</CoarBreadcrumbItem>
  <CoarBreadcrumbItem active>Button.tsx</CoarBreadcrumbItem>
</CoarBreadcrumb>
```

Pass items without `to` / `href` to render as plain text (the slot-only escape hatch) — useful for path indicators where the segments aren't independently navigable.

## 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 |
| `size` | `'m' \| 's'` | `'m'` | Visual density. `'s'` (13 px) for secondary chrome — file-explorer paths, settings trails, etc. Drives only the font-size token; spacing + colors stay identical to `'m'` so both sizes look consistent in the same UI. |

### CoarBreadcrumbItem Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `to` | `RouteLocationRaw \| string` | `undefined` | Vue Router target. Library renders an `<a>` (via `<RouterLink>` if available, plain `<a>` otherwise). Ignored when `active` is true. |
| `href` | `string` | `undefined` | External URL. Used when `to` is not set. |
| `icon` | `string` | `undefined` | Leading icon name. Rendered inside the link / active span. |
| `active` | `boolean` | `false` | Mark as the current/active page — renders as `<span aria-current="page">`, NOT a link to itself. Takes precedence over `to` / `href`. |
| `disabled` | `boolean` | `false` | Disabled link (only meaningful in link modes): `aria-disabled`, `tabindex=-1`, navigation suppressed. |

### CoarBreadcrumbItem Slots

| Slot | Description |
|------|-------------|
| `default` | Item content — text for the common case, or any custom content (dropdown, button, etc.) in bare-slot mode |
| `icon` | Custom icon content. Overrides the `icon` prop when both are provided. Use for avatars, badges, coloured icons. |

---

---
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/panel-layout.md
---
# Panel Layout&#x20;

A VS-Code-style workbench: named, resizable regions you fill with whatever you like. Two pieces:

* **`CoarSplitPane`** — the primitive: two panes with a draggable divider. Nestable.
* **`CoarPanelLayout`** — a ready-made shell with `top / left / content / right / bottom / status` regions, built on `CoarSplitPane` so every divider feels identical.

```ts
import { CoarSplitPane, CoarPanelLayout } from '@cocoar/vue-ui';
```

The layout owns the arrangement and the drag-to-resize; **you own the contents** of every slot. Resizing works by pointer drag or arrow keys (the dividers are real `role="separator"` widgets).

## Split pane

`CoarSplitPane` lays out two slots — `#first` and `#second` — with a divider between them. The `side` pane carries a controlled px `size` (`v-model:size`); the other flexes. `direction="row"` gives a vertical divider (left/right); `direction="column"` gives a horizontal one (top/bottom).

```vue
<CoarSplitPane v-model:size="width" :min="120" :max="420">
  <template #first>…sidebar…</template>
  <template #second>…content…</template>
</CoarSplitPane>
```

| Prop | Default | Notes |
|---|---|---|
| `direction` | `'row'` | `'row'` = side by side (vertical divider); `'column'` = stacked (horizontal divider). |
| `side` | `'first'` | Which pane carries the controlled `size`. Use `'second'` for a right sidebar or bottom panel. |
| `size` (`v-model`) | — | Controlled px size of the `side` pane. Omit for uncontrolled (seeded by `defaultSize`). |
| `defaultSize` | `240` | Initial size when uncontrolled. |
| `min` / `max` | `0` / `∞` | Clamp for the `side` pane (also clamped to the container). |
| `resizable` | `true` | `false` hides the divider and fixes the split. |

Panes clip overflow (`overflow: hidden`) — put a scroll container inside if the content can exceed the pane.

## Workbench

`CoarPanelLayout` arranges the canonical regions. An **empty slot renders no region** (and no divider), so you take only what you need; `#default` (content) always fills the centre. Sidebars and the bottom panel are resizable and collapsible (`:left-open` …). Toggle the buttons and drag the dividers:

```vue
<CoarPanelLayout v-model:left-width="leftW" :left-min="160" :left-max="360">
  <template #top>…toolbar…</template>
  <template #left>…sidebar…</template>
  <template #default>…content…</template>
  <template #right>…inspector…</template>
  <template #bottom>…panel…</template>
  <template #status>…status bar…</template>
</CoarPanelLayout>
```

```
┌───────────────────────────────────────┐
│  #top            (fixed, full width)   │
├────────┬────────────────────┬──────────┤
│ #left  │     #default        │  #right  │
│        ├────────────────────┤          │
│        │     #bottom         │          │
├────────┴────────────────────┴──────────┤
│  #status         (fixed, full width)   │
└───────────────────────────────────────┘
```

| Prop | Default | Notes |
|---|---|---|
| `leftWidth` / `rightWidth` / `bottomHeight` (`v-model`) | `240` / `280` / `200` | Controlled px sizes. Two-way, so persisting them (localStorage, user prefs) is a one-liner. |
| `leftOpen` / `rightOpen` / `bottomOpen` | `true` | Collapse a region without unmounting the rest. Render your own toggle button. |
| `leftMin/Max`, `rightMin/Max`, `bottomMin/Max` | `0` / `∞` | Per-region clamps. |
| `leftResizable` / `rightResizable` / `bottomResizable` | `true` | `false` fixes that region (no divider). |
| `contentMinWidth` / `contentMinHeight` | `120` / `80` | Floor the content region keeps — sidebars / the bottom panel can never be dragged (or a shrinking window squeeze them) past it, so **content is never crushed to 0**. Set to `0` to opt out. |

The `#bottom` panel sits **under the content, between the sidebars** (VS-Code default). `#top` and `#status` are fixed-height, full-width, and not resizable. Content is **protected by default**: a divider stops before the content region would drop below `contentMinWidth` / `contentMinHeight`, and that floor also holds as the window shrinks (the over-constrained edge clips rather than collapsing the content).

## Nesting — a panel within a region

Need a split *inside* a region — say a file tree above a details panel in the left sidebar? Nest a `CoarSplitPane`. Same divider, same behaviour:

```vue
<CoarPanelLayout :left-width="leftW">
  <template #left>
    <CoarSplitPane direction="column" side="second" v-model:size="detailsHeight" :min="80">
      <template #first><CoarTree … /></template>      <!-- tree fills -->
      <template #second>…details panel…</template>     <!-- sized, draggable -->
    </CoarSplitPane>
  </template>
  <template #default>…editor…</template>
</CoarPanelLayout>
```

This pairs naturally with the [file explorer](/components/file-explorer/)'s `selectedAsset` + `describeAsset` for a tree-over-details sidebar.

## Accessibility

Each divider is a `role="separator"` with `aria-orientation`, `aria-valuenow/valuemin/valuemax`, and an `aria-label`. It's in the tab order — focus it and use **Arrow keys** to resize, **Home/End** to jump to min/max. Clicking a divider focuses it too.

## Scope

Resize and collapse are in. Drag-to-rearrange panels, tab docking, and floating panels are intentionally **out** — compose those on top if you need them.

---

---
url: /components/wizard.md
---
# Wizard&#x20;

A multi-step flow shell — built to live **inside a modal** (it renders no modal of its own). Three things make it a wizard rather than a plain stepper:

* **Animated body resize.** Only the active step is mounted, and the body smoothly animates its height between steps — so the surrounding modal grows / shrinks to fit each page.
* **A scrollable indicator that follows you.** The step indicator can be far wider (or taller) than the modal; it scrolls and auto-centers the active step on every move.
* **Edge-placeable indicator.** `indicatorPosition` puts the progress strip on any of the four edges.

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

::: warning Preview
`CoarWizard` is new and on the `0.0.x` line. The API (props, slots, events) may still change before it stabilises — pin a version if you depend on it.
:::

## Basic Usage

Pass an ordered `steps` array — each step's `id` is the name of its content slot, and only the active step is rendered. Bind the active step with `v-model:step`. Try the **Top / Right / Bottom / Left** toggle, and watch the modal resize as you move between the short and tall steps. Step 1 gates **Next** via `canAdvance` until a name is entered.

```vue
<template>
  <CoarWizard :steps="steps" v-model:step="step" @finish="create">
    <template #basics>…</template>
    <template #scopes>…</template>
    <template #review>…</template>
  </CoarWizard>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { CoarWizard, type CoarWizardStep } from '@cocoar/vue-ui';

const step = ref('basics');
const steps: CoarWizardStep[] = [
  { id: 'basics', label: 'Basics', canAdvance: true },
  { id: 'scopes', label: 'Scopes' },
  { id: 'review', label: 'Review' },
];
</script>
```

::: tip Designed for modals
The wizard renders no modal — drop it into your modal / routed-modal body. Give that modal a **content-driven height** (and a `max-height` for very tall steps) so the per-step resize animation is visible.
:::

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `steps` | `CoarWizardStep[]` | — | Ordered steps. Each `id` names that step's content slot. |
| `step` (`v-model:step`) | `string` | *first step* | The active step id. Uncontrolled (defaults to the first step) when not bound. |
| `indicatorPosition` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Which edge the indicator sits on. `top`/`bottom` scroll horizontally; `left`/`right` vertically. |
| `freeNavigation` | `boolean` | `false` | Allow jumping to any non-disabled step from the indicator (default: only completed steps are clickable). |
| `hideFooter` | `boolean` | `false` | Hide the built-in Back / Next / Finish footer. |
| `disableAnimation` | `boolean` | `false` | Skip the height + content transition (also auto-skipped under `prefers-reduced-motion`). |
| `backLabel` / `nextLabel` / `finishLabel` | `string` | `Back` / `Next` / `Finish` | Built-in button labels. |

### `CoarWizardStep`

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Stable id + content slot name. |
| `label` | `string` | Indicator label. |
| `description` | `string?` | Optional second line under the label. |
| `optional` | `boolean?` | Marks the step optional in the indicator. |
| `canAdvance` | `boolean?` | When `false`, the built-in Next is disabled on this step (per-step gate). Defaults to allowed. |
| `disabled` | `boolean?` | Prevents navigating to this step from the indicator. |

## Slots

| Slot | Props | Description |
|---|---|---|
| `<step id>` | `{ step, index }` | Content for that step. Only the active step's slot is rendered. |
| `footer` | `{ next, back, goTo, isFirst, isLast, canAdvance, activeStep, activeIndex }` | Replace the built-in footer with your own controls. |

## Events

| Event | Payload | Description |
|---|---|---|
| `update:step` | `string` | Active step id changed. |
| `step-change` | `(id, index)` | Active step changed. |
| `finish` | — | Next pressed on the last step. |

---

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

`<CoarToastContainer />` needs no props — its `service` defaults to the `getToastService()` singleton that `CoarOverlayPlugin` registers (the same one `useToast()` wraps). Pass an explicit `:service` only for a non-singleton instance (e.g. an isolated test harness). If the plugin isn't installed it throws a clear "install `CoarOverlayPlugin`" error rather than rendering nothing.

## 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

## Frontmatter

A leading YAML frontmatter block (`---` … `---`) is parsed into a single `frontmatter` node and rendered as muted, italic `key: value` lines (styled like disabled text, so it reads as metadata rather than body content). Without this, CommonMark mis-reads the block as a thematic break followed by a setext heading, collapsing the entire YAML onto one line.

```ts
import { parse } from '@cocoar/vue-markdown-core';

const doc = parse(`---
title: Release notes
tags:
  - editor
  - markdown
---

# Heading
`);

doc.nodes[0].type;          // 'frontmatter'
doc.nodes[0].attrs.data;    // { title: 'Release notes', tags: ['editor', 'markdown'] }
doc.nodes[0].attrs.entries; // [{ key: 'title', value: 'Release notes' }, { key: 'tags', value: 'editor, markdown' }]
doc.nodes[0].attrs.raw;     // the original YAML text (used for round-trip via serialize())
```

The node carries three attrs: `raw` (verbatim YAML, the round-trip source), `data` (the parsed object, or `null` for non-map/invalid YAML), and `entries` (flattened, display-ready key/value rows). The default `DefaultFrontmatter` renderer reads `entries`; on a parse failure it falls back to the raw text so nothing is hidden. Override it like any other slot via `MARKDOWN_RENDERERS_KEY` (key: `frontmatter`).

`@cocoar/vue-markdown-editor` renders it the **same** way and round-trips the block on save — see the [editor's Frontmatter section](/components/markdown-editor#frontmatter).

## Node Types

```ts
type MarkdownNodeType =
  | 'frontmatter'
  | '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`: a link insertion dialog and hover-based table edge-handles (row/column selection). 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"
/>
```

## Flavors (portability)

The **`flavor`** prop is a portability contract: it picks which features the editor offers and **hard-enforces** them — it only registers the matching Milkdown plugins, so a non-flavor construct can't be typed *or pasted* (it degrades to plain text), and its toolbar buttons are hidden.

This matters when the same Markdown is rendered somewhere stricter than the web — e.g. a **native SwiftUI Markdown view** that only understands CommonMark, or CommonMark+GFM. Pick the flavor that matches your strictest renderer and authors physically can't produce content it won't render.

| Flavor | Adds on top of CommonMark | Renders in |
|---|---|---|
| `'commonmark'` | *(nothing — the portable floor)* headings, bold/italic, lists, links, images, code, blockquote, hr | **any** Markdown renderer |
| `'gfm'` | tables, task lists, strikethrough | GFM-capable renderers (GitHub, swift-markdown-ui, …) |
| `'cocoar'` *(default)* | inline **text color** (non-portable raw HTML) | the Cocoar viewer / your own renderer |

```vue
<!-- Strict: only portable CommonMark can be authored -->
<CoarMarkdownEditor v-model="value" flavor="commonmark" toolbar-mode="both" />

<!-- Fine control: GFM tables etc. but no color, via a capability object -->
<CoarMarkdownEditor v-model="value" :flavor="{ gfm: true, textColor: false }" />
```

A capability object (`{ gfm?, textColor? }`) is **opt-in** — unspecified capabilities are off, so `{}` ≡ `'commonmark'`. The default is `'cocoar'`, so existing editors are unchanged.

::: tip flavor vs. tools
`flavor` is the **hard format contract** (what can exist in the document). The [`tools`](#restricting-the-toolbar) whitelist is **soft toolbar curation** (which buttons show) *within* the flavor — e.g. keep GFM parsing but hide the table button. They compose.
:::

::: warning Changing flavor at runtime
Plugin registration happens once at mount. To switch `flavor` on a live editor, **re-key** the component (`:key="flavor"`) so it remounts and re-registers — otherwise only the toolbar updates, not the parser. Switching to a stricter flavor degrades unsupported constructs already in the document (a table becomes its literal `| … |` text). The standalone `<CoarMarkdown>` viewer has its own parse options and is not affected by the editor's flavor.
:::

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

## Placeholder

Pass a `placeholder` string to show a hint while the editor is empty. The
placeholder **is itself Markdown** — it renders through the same viewer the
editor uses for content, so `**bold**`, lists, and headings all work and match
the editor's typography.

```vue
<CoarMarkdownEditor
  v-model="value"
  :placeholder="'**Describe the change…**\n\n- What changed?\n- Why?'"
/>
```

::: tip Never persisted — unlike pre-filling the value
The placeholder is a muted, click-through **overlay** of the `<CoarMarkdown>` viewer, shown only while the document is empty. It never enters `modelValue`. An untouched editor therefore still emits an empty string — so you can leave the field genuinely blank.

Do **not** work around a missing placeholder by writing the hint into `v-model`: that turns the hint into real content, which then gets saved even when the user meant to leave the field empty.
:::

The hint disappears the moment the document has any content and reappears if it's emptied again. It tracks the live `placeholder` prop, so you can swap it at runtime. Because it's a real Markdown render, the placeholder also picks up [custom renderers](#code-blocks-view-edit-toggle) you provide via `MARKDOWN_RENDERERS_KEY`.

## Frontmatter

A leading YAML frontmatter block (`---` … `---`) is recognised and shown as muted, italic `key: value` lines instead of being mis-parsed as a thematic break + setext heading (which collapses the whole block onto one line). It renders the same way in the [viewer](/components/markdown#frontmatter), so editing and reading look identical.

The frontmatter is an **atomic block**: display-only in the rendered editor (muted + italic, like disabled text), selectable/deletable as a unit, and — crucially — it **round-trips**. The raw YAML is preserved verbatim, so `v-model` keeps emitting the `---` … `---` block untouched while you edit the body. To **edit** the YAML values, switch to [Source view](#source-view-raw-markdown).

::: info Parsing & nesting
Detection is powered by [`remark-frontmatter`](https://github.com/remarkjs/remark-frontmatter) on Milkdown's shared remark instance (and the matching parse path in `@cocoar/vue-markdown-core`). Only a YAML block at the very **top** of the document is treated as frontmatter — a `---` in the middle stays a horizontal rule. Malformed YAML falls back to showing the raw text in the card rather than collapsing.
:::

## Source view (raw Markdown)

Set `source-toggle` to add a **Rendered ↔ Source** switch. In Source mode the entire document — body **and** the frontmatter YAML — is editable as raw Markdown in a `<textarea>`; switching back re-parses and re-renders it.

```vue
<CoarMarkdownEditor v-model="value" source-toggle toolbar-mode="fixed" />
```

This is the way to hand-edit frontmatter, fix up exact Markdown, or paste raw content. The toggle is **off by default** — without `source-toggle` the editor is WYSIWYG-only with no extra chrome.

::: info Where the toggle lives
With a **fixed** sidebar toolbar (`toolbar-mode` `'fixed'` / `'both'`) the toggle is the **first item in the sidebar** — and in Source mode the sidebar collapses to just that toggle (the formatting buttons act on the hidden rich editor, so they're hidden). With the default **floating** toolbar there's no persistent toolbar, so a small toggle button appears in the editor's top-right corner instead.
:::

::: info Behaviour
The rich editor stays mounted in Source mode (just hidden), so switching is cheap and the toolbar stays put. `readonly` / `disabled` and the `CoarFormField` wiring carry over to the Source `<textarea>`. Switching back re-seeds the rich editor from the current value, so raw edits (incl. frontmatter) are picked up — the rich editor's undo history resets across a mode switch.
:::

## Images

Images round-trip as standard Markdown — `![alt](url "title")` — so anything you paste from another CMS (a WordPress export, say) renders as-is in both the editor and `<CoarMarkdown>`.

There are three ways to add one:

* **Insert by URL** — the **Insert Image** button in the sidebar opens a small dialog for `url` / `alt` / `title`. (Like the table and code-block buttons, it lives in the **sidebar**, so use `toolbar-mode="fixed"` or `"both"`.)
* **Paste** an image from the clipboard (e.g. a screenshot).
* **Drag & drop** an image file into the writing area.

Paste and drop require an `upload-image` callback. It receives the dropped/pasted `File`, stores it wherever you like, and resolves with the resulting `url` (plus optional `alt`). A spinner placeholder is shown at the insertion point until it resolves, then is replaced by the image. Without the callback, image files fall through to the browser's default handling.

```vue
<CoarMarkdownEditor
  v-model="value"
  toolbar-mode="both"
  :upload-image="uploadImage"
/>

<script setup lang="ts">
async function uploadImage(file: File) {
  const url = await myAssetService.upload(file) // your storage
  return { url, alt: file.name }
}
</script>
```

### Custom image source (`pickImage`)

To wire the **Insert Image** button to your own asset library or gallery, pass a `pickImage` callback. When set, it **replaces** the built-in URL dialog: clicking the button calls your callback with a context bound to the cursor position — `insertImage(...)` plus the `selectedText` (a handy default for `alt`). Open your own modal, then call `ctx.insertImage(...)` for each chosen image. The modal can stay open and insert several; the editor keeps ownership of cursor handling and the Markdown round-trip, so you never touch ProseMirror.

```vue
<CoarMarkdownEditor v-model="value" toolbar-mode="both" :pick-image="openGallery" />

<script setup lang="ts">
function openGallery(ctx) {
  myGalleryModal.open({
    defaultAlt: ctx.selectedText,
    onPick: (asset) => ctx.insertImage({ url: asset.url, alt: asset.title }),
  })
}
</script>
```

`pickImage` (button → your picker) and `uploadImage` (paste / drop) are orthogonal and compose — wire both for a full gallery-plus-paste experience.

::: info Resize / alignment / captions
Width, alignment, and captions aren't part of standard Markdown, so they're not supported yet — a richer image block (a separate slice) is planned. Today an image is the plain `![alt](url "title")`.
:::

## Tables

GFM tables are portable (they render on GitHub, in `swift-markdown-ui`, etc.), so they're available in the `'gfm'` and `'cocoar'` [flavors](#flavors-portability). The editor offers a full set of table operations:

**Create** — two ways:

* The **Insert Table** sidebar button opens a small **grid size picker** — hover (or tap) to choose `cols × rows`, then click to insert.
* Type **`|3x4|`** followed by a space anywhere — a GFM input rule turns it into a 3-column × 4-row table. This needs no toolbar, so it's the way to create a table in the default `floating` mode.

**Edit** — two ways:

* **Hover edge-handles** (Notion/Word-style) — point at any edge of a table and grips appear along all four sides (a segment per column on top & bottom, per row on left & right). Hovering a grip highlights the whole column/row; **clicking** it opens a menu to **insert before / after** or **delete**, and **dragging** it **reorders** the column/row (with a live drop indicator).
* **In-cell toolbar** — with the cursor inside a cell, the floating toolbar (and the sidebar in `fixed`/`both` mode) offers insert row/column, **column alignment** (left / center / right, applied to the whole column — round-trips as GFM `:--` / `:-:` / `--:`, active alignment highlighted), **delete cell** and **delete table**.

::: info How the handles work
The handles are geometry-driven — they measure the hovered table's cell rectangles and render fixed-position grips, rather than reacting to ProseMirror's `CellSelection` (which doesn't fire `selectionchange`). Clicking a grip targets that column/row by position, so it works on any table without needing a cursor inside it first.
:::

## 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` `image` | Insert blocks (sidebar only) |
| `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"` |
| `placeholder` | `string` | `''` | Markdown hint shown while the editor is empty. Overlay-only — never written to `modelValue`. See [Placeholder](#placeholder) |
| `sourceToggle` | `boolean` | `false` | Show a Rendered ↔ Source toggle for editing the raw Markdown. See [Source view](#source-view-raw-markdown) |
| `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) |
| `flavor` | `'commonmark' \| 'gfm' \| 'cocoar' \| { gfm?, textColor? }` | `'cocoar'` | Portability contract — hard-enforces which features can be authored. See [Flavors](#flavors-portability) |
| `uploadImage` | `(file: File) => Promise<{ url: string; alt?: string }>` | *undefined* | Enables paste / drag-drop image upload. Returns the stored image's URL. See [Images](#images) |
| `pickImage` | `(ctx: ImagePickContext) => void` | *undefined* | Override the Insert Image button with your own asset picker. See [Custom image source](#custom-image-source-pickimage) |

## 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

* \[ ] Link insert/edit dialog
* \[x] Image support (insert by URL, paste / drag-drop upload, custom `pickImage`)
* \[x] Table create (size picker + `|CxR|`), column alignment, delete table
* \[x] Hover edge-handles (row/column grips on all four edges → insert / delete menu)
* \[ ] 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/page-builder.md
---
# Page Builder&#x20;

`@cocoar/vue-page-builder` is a generic, headless visual page composition framework. Users drag UI primitives onto a canvas, configure them, and the result is a portable JSON schema that a companion renderer turns back into live Cocoar components.

Everything domain-specific — what actions a button can trigger, where images come from, which elements are permitted — is defined by the **consumer application**, not the library.

## Two components

| Component | Purpose | Docs |
|-----------|---------|------|
| `<CoarPageBuilder>` | Visual editor — 3-panel layout, drag-and-drop, props panel | [→ CoarPageBuilder](./coar-page-builder) |
| `<CoarPageRenderer>` | Runtime renderer — schema → live Cocoar components | [→ CoarPageRenderer](./coar-page-renderer) |

Both share the same `PageConfig`. The builder uses it as UI affordances; the renderer uses it as the security boundary.

## Quick start

```vue
<script setup lang="ts">
import { ref } from 'vue';
import {
  CoarPageBuilder,
  CoarPageRenderer,
  type PageNode,
  type PageConfig,
  type ActionValues,
} from '@cocoar/vue-page-builder';

const schema = ref<PageNode>({
  id: 'root',
  type: 'page',
  style: { gap: '16px', padding: '24px' },
  children: [],
});

const config: PageConfig = {
  allowedElements: ['stack', 'card', 'heading', 'paragraph',
                    'text-input', 'checkbox', 'button', 'link', 'image'],
  availableActions: [
    { id: 'auth:login',  label: 'Sign in' },
    { id: 'auth:forgot', label: 'Forgot password' },
  ],
};

const actions: Record<string, (v: ActionValues) => void> = {
  'auth:login':  (values) => api.login(values),
  'auth:forgot': ()       => router.push('/forgot'),
};
</script>

<template>
  <!-- Visual editor — user builds the page -->
  <CoarPageBuilder v-model="schema" :config="config" style="height: 700px" />

  <!-- Renderer — plays back the schema at runtime -->
  <CoarPageRenderer
    :schema="schema"
    :config="config"
    :actions="actions"
    :asset-resolver="(id) => `/tenant/${tenantId}/assets/${id}`"
  />
</template>
```

The **same `config` is passed to both** — the builder uses it to filter UI affordances; the renderer uses it as the security boundary at render time.

## Architecture

```
Consumer app
  │
  ├── <CoarPageBuilder v-model="schema" :config />     ← visual editor
  │
  └── <CoarPageRenderer :schema :config                ← runtime renderer
                        :actions :asset-resolver />      maps JSON nodes → Cocoar components
                                                         wires action IDs → real handler functions
```

The JSON schema is the single artifact that flows between builder and renderer. It is plain JSON with no library dependency — any renderer (including a custom one) can interpret it.

## PageConfig — the consumer contract

Everything tenant-facing or domain-specific is declared here. Pass the **same value** to both the builder and the renderer.

```ts
interface PageConfig {
  /**
   * Element types permitted to appear in the tree. Omit to allow every type.
   * `page` (the root marker) is always implicitly allowed.
   */
  allowedElements?: ElementType[]

  /**
   * Action IDs that buttons and links may reference. When provided, the
   * builder's Action input becomes a dropdown of these labeled choices
   * instead of free text. The renderer's `actions` map is the actual
   * security boundary — `availableActions` is a UX affordance.
   */
  availableActions?: { id: string; label: string }[]

  /**
   * Resolves an assetId to a URL. Used by the builder for thumbnails
   * (canvas preview, props panel, Preview tab) and by the runtime
   * renderer for `<img src>`. Same contract as the renderer's
   * `:asset-resolver` prop.
   */
  assetResolver?: (id: string) => string

  /**
   * Opens the consumer's own asset picker UI and resolves to the chosen
   * `assetId`, or `null` if the user cancelled. The library does NOT
   * ship a picker — the IDP owns the entire picker UX (browse, upload,
   * search, delete, categorisation, …). When omitted, the image element
   * falls back to a free-text Asset ID input.
   */
  pickAsset?: (currentId?: string) => Promise<string | null>
}
```

### `allowedElements`

Enforced at **both** layers:

* *Builder*: hidden from the palette and add-child menu; tenants can't insert disallowed types.
* *Renderer*: disallowed nodes are skipped at render time even if they appear in hand-written or tampered JSON. This is the security boundary.

```ts
allowedElements: [
  'stack', 'card', 'section', 'divider',
  'heading', 'paragraph',
  'text-input', 'checkbox', 'button', 'link', 'image',
],
```

Drop element types the tenant shouldn't be able to use. `page` is implicitly always allowed.

### `availableActions`

When provided, the Action ID input in Button/Link props becomes a dropdown. Stored action IDs that aren't in the list are surfaced as `auth:something (not configured)` so orphans don't silently disappear.

```ts
availableActions: [
  { id: 'auth:login',           label: 'Sign in' },
  { id: 'auth:register',        label: 'Create account' },
  { id: 'auth:forgot-password', label: 'Forgot password' },
  { id: 'auth:sso-google',      label: 'Sign in with Google' },
  { id: 'auth:sso-microsoft',   label: 'Sign in with Microsoft' },
],
```

The runtime `actions` map on the renderer is the real boundary — it only invokes handlers that exist there. `availableActions` is purely a UX affordance.

### `assetResolver` + `pickAsset`

The library does **not** ship an asset picker. You build your own — a modal, a drawer, a sidebar, however you want — and wire it in via two simple callbacks.

```ts
const config: PageConfig = {
  // ...
  /** Resolves an asset id to a URL. The builder uses this for thumbnails;
      pass the same function (or one equivalent) to the renderer's :asset-resolver. */
  assetResolver: (id) => `https://cdn.example.com/t/${tenantId}/${id}`,

  /** Opens YOUR picker and resolves to the chosen id (or null on cancel). */
  async pickAsset(currentId) {
    const result = await myAssetModal.open({ initial: currentId });
    return result ?? null;
  },
};
```

The image element's props panel renders:

* a **thumbnail** using `assetResolver(node.assetId)`
* a **Choose…/Change…** button that calls `pickAsset(currentId)` and patches the returned id onto the schema
* a **Clear** button when an id is set

When `pickAsset` is omitted, the image element falls back to a free-text Asset ID input — useful for development or scripted authoring.

#### What your picker needs to do

The full contract is just `(currentId?: string) => Promise<string | null>`. Inside, you do whatever fits your stack:

* list assets from your API
* handle uploads (sign URL, POST file, etc.)
* search, filter, paginate
* delete
* categorise by tag/folder
* show metadata, dimensions, file size

Return the chosen asset's id, or `null` if the user cancelled. The library doesn't care about anything else.

Example skeleton using Cocoar's `useDialog`:

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

const dialog = useDialog();

const config: PageConfig = {
  // ...
  assetResolver: (id) => assetUrlMap.value.get(id) ?? '',
  async pickAsset(currentId) {
    const { result } = dialog.open<string>(
      MyAssetPicker,
      { title: 'Choose image', size: 'l' },
      { initial: currentId },
    );
    return (await result) ?? null;
  },
};
```

A complete reference implementation lives at `apps/playground/src/components/PlaygroundAssetPicker.vue` — copy it as a starting point.

## Security Model

**Allowed elements** — `config.allowedElements` is enforced at both layers (builder hides; renderer skips). The renderer is the hard boundary — even tampered JSON cannot smuggle in disallowed types.

**Actions** — buttons and links store an action `id`. The renderer only invokes handlers from the consumer-provided `actions` map. Arbitrary JavaScript is never stored in the schema. When `config.availableActions` is set, the builder also constrains the Action input to a labeled dropdown.

**Images** — `image` nodes store an `assetId` reference, never a raw URL. The renderer calls `assetResolver(id)` at render time. Tenants cannot reference external domains. Uploads happen entirely inside the consumer-built picker (whatever `pickAsset` opens) — that's where you validate file type, scan for malware, and enforce per-tenant size quotas.

## Complete IDP integration walkthrough

Here's how a tenant-customisable login flow fits together end-to-end.

### 1. Define the tenant config

In a shared file your admin app and your login app both import:

```ts
// tenants/loginConfig.ts
import type { PageConfig } from '@cocoar/vue-page-builder';

export function buildLoginConfig(tenantId: string): PageConfig {
  return {
    allowedElements: [
      'stack', 'card', 'divider',
      'heading', 'paragraph',
      'text-input', 'checkbox', 'button', 'link', 'image',
    ],
    availableActions: [
      { id: 'auth:login',           label: 'Sign in' },
      { id: 'auth:sso-google',      label: 'Sign in with Google' },
      { id: 'auth:sso-microsoft',   label: 'Sign in with Microsoft' },
      { id: 'auth:forgot-password', label: 'Forgot password' },
      { id: 'auth:register',        label: 'Create account' },
      { id: 'nav:login',            label: 'Go to login' },
    ],
    assetResolver: (id) => `https://cdn.example.com/t/${tenantId}/${id}`,
    async pickAsset(currentId) {
      // Open your own asset picker — the library does not ship one.
      // Inside MyAssetPickerModal you'd call your /api/tenants/${tenantId}/assets
      // endpoint for the list, POST for uploads, etc.
      return await openMyAssetPickerModal({ tenantId, initial: currentId });
    },
  };
}
```

### 2. Admin page — the builder

```vue
<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { CoarPageBuilder, type PageNode } from '@cocoar/vue-page-builder';
import { buildLoginConfig } from '@/tenants/loginConfig';

const props = defineProps<{ tenantId: string }>();
const schema = ref<PageNode>({
  id: 'root', type: 'page', style: { gap: '16px', padding: '24px' }, children: [],
});
const config = buildLoginConfig(props.tenantId);
const saving = ref(false);

onMounted(async () => {
  const res = await fetch(`/api/tenants/${props.tenantId}/login-schema`);
  if (res.ok) schema.value = await res.json();
});

async function save() {
  saving.value = true;
  try {
    await fetch(`/api/tenants/${props.tenantId}/login-schema`, {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(schema.value),
    });
  } finally {
    saving.value = false;
  }
}
</script>

<template>
  <div class="tenant-login-editor">
    <header>
      <h1>Login page editor</h1>
      <button @click="save" :disabled="saving">
        {{ saving ? 'Saving…' : 'Save' }}
      </button>
    </header>
    <CoarPageBuilder v-model="schema" :config="config" style="height: 80vh" />
  </div>
</template>
```

### 3. Runtime — the login page itself

```vue
<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { CoarPageRenderer, type PageNode, type ActionValues } from '@cocoar/vue-page-builder';
import { buildLoginConfig } from '@/tenants/loginConfig';

const props = defineProps<{ tenantId: string }>();
const schema = ref<PageNode | null>(null);
const config = buildLoginConfig(props.tenantId);

onMounted(async () => {
  const res = await fetch(`/api/tenants/${props.tenantId}/login-schema`);
  schema.value = await res.json();
});

const actions: Record<string, (v: ActionValues) => void> = {
  'auth:login':           (v) => authService.login(v),
  'auth:forgot-password': ()  => router.push('/forgot'),
  'auth:sso-google':      ()  => authService.startSso('google'),
  'auth:sso-microsoft':   ()  => authService.startSso('microsoft'),
  'auth:register':        (v) => authService.register(v),
  'nav:login':            ()  => router.push('/login'),
};
</script>

<template>
  <CoarPageRenderer
    v-if="schema"
    :schema="schema"
    :config="config"
    :actions="actions"
    :asset-resolver="config.assetResolver"
  />
</template>
```

### Notes for the IDP wiring

* **Schema migration** — JSON pasted into the builder is normalised (`column`/`row` → `stack`, non-`page` roots get wrapped in a `page`). Schemas loaded from your backend that pre-date these types still work — the renderer accepts them implicitly because the builder migrates on paste, but if you have old saved schemas you should run the same migration server-side before storing the new shape.
* **Validation** — the builder warns about missing actions, duplicate field names, and missing asset IDs, but lets the tenant save anyway. If you want hard server-side validation before persisting, walk the tree and reject (e.g., reject if any `image.assetId === ''`).
* **CSP** — image URLs come from `assetResolver`, so your CDN domain needs to be in `img-src`. Action IDs and labels are plain strings — nothing executable lives in the schema.
* **Full-screen / centering** — the renderer is `display: contents`, so the `page` fills the host element's width. To center a login card on a full-height screen, set the `page` node's `minHeight: '100vh'` + `justify: 'center'` + `align: 'center'` — no host CSS needed. See [Sizing and alignment](./coar-page-renderer#sizing-and-alignment).
* **Per-tenant theming** — the renderer uses the Cocoar Design System tokens; override CSS variables on a wrapping container for tenant brand colors.

## Implementation Roadmap

| Phase | Scope | Status |
|-------|-------|--------|
| **1 — Foundation** | `schema.ts` types · `CoarPageRenderer` · playground demo | ✅ Done |
| **2 — Builder shell** | Canvas + palette · Outline · Props panel · DnD · Undo/redo · JSON tab | ✅ Done |
| **3 — Config + safety** | `page` root · `stack` (direction toggle) · `:config.allowedElements` · `:config.availableActions` | ✅ Done |
| **4 — Asset callbacks + polish** | `:config.pickAsset` + `:config.assetResolver` · builder validation · responsive preview | ✅ Done |
| **5 — Layout & sizing** | Flex model — `justify` / `align` / `alignSelf` / `size` (fit · fill · fixed) / `minHeight`; guided Style-panel controls; Editor matches Preview | ✅ Done |
| **5b — Style editor (visual)** | Spacing sliders + colour pickers (rolls into the tenant theming track) | Planned |
| **6+ — Schema versioning** | Formal `version` field + migration framework | Planned |

---

---
url: /components/page-builder/coar-page-builder.md
---
# `<CoarPageBuilder>`&#x20;

The visual-editor half of `@cocoar/vue-page-builder`. Renders a three-panel layout — outline tree on the left, canvas with palette in the centre, properties panel on the right — and emits a `PageNode` JSON tree as `v-model`. The same tree is consumed by [`<CoarPageRenderer>`](./coar-page-renderer) at runtime.

All three panels are resizable via drag handles and collapsible.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `modelValue` / `v-model` | `PageNode` | empty `page` | The page schema. Bound two-way; every edit updates the ref. |
| `config` | [`PageConfig`](./#pageconfig-the-consumer-contract) | — | Allowed elements, available actions, asset callbacks. The same value must be passed to the renderer. |

## Features

* **Palette toolbar** — drag containers (Stack, Card, Section) and elements onto the canvas. Hidden types per `config.allowedElements`.
* **Outline tree** — hierarchical node list with selection, drag-to-reorder, inline add/delete. Stacks display "Column" or "Row" based on direction. Warning icons (⚠ / ⛔) mark nodes with validation issues.
* **Canvas** — real component previews with dashed selection borders. Switches to live preview in the **Preview** tab and to a paste-and-apply JSON editor in the **JSON** tab.
* **Properties panel** — per-element configuration. Each element type ships its own props component. Validation issues for the selected node are surfaced at the top with colored banners.
* **Stack direction toggle** — change a stack from column to row direction without re-creating it. Children stay put.
* **Layout controls** — every node's Style section exposes the flex model: container `Justify` (main axis) + `Align items` (cross axis), and per-node `Align self`, `Size` (Fit / Fill / Fixed → Width) and `Min height`. Center a single element, distribute a row, or build a full-screen centered page — and the Editor canvas mirrors the result 1:1 with the Preview.
* **Asset picker entry point** — when `config.pickAsset` is set, the image element shows a thumbnail + "Choose…" button that defers to your own picker UI.
* **Responsive preview** — Desktop · Tablet · 768 · Mobile · 375 segmented toggle in the Preview tab. The render area is capped and centered so you can verify the design at common breakpoints.
* **Undo / redo** — `Ctrl+Z` / `Ctrl+Y` (or `Cmd+Z` / `Cmd+Shift+Z`), also via toolbar buttons.
* **Keyboard** — `Delete` / `Backspace` removes the selected node (when focus is not in an input).
* **JSON paste migration** — legacy `column` / `row` types are auto-coerced to `stack` on import; other non-`page` root types are auto-wrapped in a `page`.

## Builder-side validation

The builder runs schema-level validation reactively and surfaces issues at two layers:

* **Outline** — a warning icon next to the affected node row (red ⛔ for errors, yellow ⚠ for warnings). Hover the icon for the full message.
* **Props panel** — a colored banner at the top of the selected node's properties listing every issue for that node.

Built-in rules:

| Rule | Severity |
|------|----------|
| Button / link has no Action | warning |
| Action ID is not in `config.availableActions` | warning |
| Image has no Asset ID | error |
| Two named inputs share the same `name` | error |

Validation is a builder UX scaffold — it does **not** affect what the renderer does. The renderer is governed by `allowedElements` (the hard security boundary) and by which handlers exist in the `actions` map.

## Per-element architecture

Each element type brings its own props component, registered in a single map:

```
packages/page-builder/src/builder/props/
├── registry.ts        ← ElementType → { component, sectionTitle }
├── StackProps.vue
├── CardProps.vue
├── HeadingProps.vue
├── ButtonProps.vue
├── ImageProps.vue
├── …
└── StyleProps.vue     ← universal Gap/Justify/Align/Align-self/Size/Min-height/Padding
```

The main `BuilderPropsPanel.vue` is a thin shell that resolves the registry entry and renders `<component :is="entry.component" :node :patch />`. Adding a new element type requires creating one new `<Type>Props.vue` file and adding one line to the registry — no central files are touched.

## Pairing with the renderer

The builder's Preview tab uses `<CoarPageRenderer>` internally, passing through `config.assetResolver` so thumbnails work without extra wiring. For the actual runtime page (outside the builder), you mount the renderer yourself — see [`<CoarPageRenderer>`](./coar-page-renderer) and the [integration walkthrough](./#complete-idp-integration-walkthrough).

---

---
url: /components/page-builder/coar-page-renderer.md
---
# `<CoarPageRenderer>`&#x20;

The runtime-renderer half of `@cocoar/vue-page-builder`. Takes a `PageNode` schema (produced by [`<CoarPageBuilder>`](./coar-page-builder) or written by hand) and renders it as live Cocoar components. This is the component you mount on the actual page that end-users see.

The renderer is also the **security boundary** — elements not in `config.allowedElements` are skipped at render time, even if they appear in hand-written or tampered JSON.

## Props

| Prop | Type | Description |
|------|------|-------------|
| `schema` | `PageNode` | Required. The page schema to render. |
| `config` | [`PageConfig`](./#pageconfig-the-consumer-contract) | Security/allowlist boundary. Elements not in `config.allowedElements` are skipped at render time (with one console warning per type). |
| `actions` | `Record<string, (values: ActionValues) => void>` | Map of action IDs to handler functions. Buttons and links call these. |
| `onValidate` | `(values: ActionValues) => Promise<Record<string, string>>` | Developer-only async/cross-field validation. Returns `{ fieldName: errorMessage }`. Not exposed in builder UI. |
| `assetResolver` | `(id: string) => string` | Resolves an `assetId` to a URL at render time. Required when the schema contains `image` nodes. |

## Usage

```vue
<CoarPageRenderer
  :schema="savedSchema"
  :config="tenantConfig"
  :actions="{
    'auth:login':           (v) => auth.login(v),
    'auth:forgot-password': ()  => router.push('/forgot'),
  }"
  :on-validate="async (v) => serverValidate(v)"
  :asset-resolver="(id) => `/tenant/${tenantId}/assets/${id}`"
/>
```

`ActionValues` is `Record<string, string | boolean>` — a flat map of all named fields at the time the action fires. Fields are collected from `text-input`, `checkbox`, and `select` nodes that have a `name` property.

## JSON Schema

Every node shares a common base:

```ts
interface PageNode {
  id:        string      // stable UUID, assigned by the builder
  type:      ElementType
  style?:    NodeStyle
  children?: PageNode[]  // containers only
  // ...element-specific props
}

interface NodeStyle {
  // ── Container: how this node lays out its children ──
  gap?:       string   // CSS gap between children — '8px', '1rem', …
  padding?:   string   // CSS padding inside this node
  justify?:   'start' | 'center' | 'end'             // justify-content — main-axis
            | 'space-between' | 'space-around' | 'space-evenly'
  align?:     'start' | 'center' | 'end' | 'stretch' // align-items — cross-axis

  // ── Self: how this node sits inside its parent ──
  alignSelf?: 'start' | 'center' | 'end' | 'stretch' // align-self — overrides parent `align`
  size?:      'fit' | 'fill' | 'fixed'               // sizing along the parent's main axis
  width?:     string   // used when size: 'fixed' — '380px', '100%', …
  minHeight?: string   // 'min-height' — e.g. '100vh' to make the page fill the viewport
}
```

### Layout behaviour

Containers are flexbox. The `page` root and `card` / `section` bodies are columns; a `stack` is either (`direction: 'column' | 'row'`, default `column`, plus optional `wrap` for rows).

* **page** — the schema root. A vertical stack; the only element allowed at the top of the tree.
* **stack** — generic flex container. Toggle `direction` between `column` and `row`. Row children are **natural-width by default** — opt a child into growing with `size: 'fill'`.
* **card** — `CoarCard` wrapper, optional `title`. Children stacked vertically.
* **section** — semantic `<section>` with optional `title` heading.

#### Sizing and alignment

`NodeStyle` separates *how a container arranges its children* from *how a node sizes and places itself*:

| Field | Applies to | Maps to | Use |
|-------|-----------|---------|-----|
| `justify` | containers | `justify-content` | distribute children on the main axis (e.g. push a button row right with `end`) |
| `align` | containers | `align-items` | align children on the cross axis |
| `alignSelf` | any node | `align-self` | override the parent's `align` for one node — e.g. center a single button in a left-aligned column |
| `size` | any node | flex / width | `fit` (natural) · `fill` (take available space) · `fixed` (+ `width`) |
| `minHeight` | any node | `min-height` | give a node a minimum height (see below) |

`size: 'fill'` is **direction-aware**: in a row it grows along the row; in a column it becomes full-width (so a "fill" Sign-in button spans the whole card).

#### Full-screen / centered pages

The renderer adds no box of its own (`display: contents`), so the `page` node sits directly inside whatever element you mount `<CoarPageRenderer>` in — that **host provides the width**. To center content on a full-screen page (the classic login card), size the `page` itself:

```json
{ "type": "page", "style": { "minHeight": "100vh", "justify": "center", "align": "center" } }
```

`minHeight: '100vh'` makes the page fill the viewport; `justify: 'center'` centers vertically (a column's main axis is vertical) and `align: 'center'` centers horizontally — no host CSS required beyond the host having its natural width.

### Example — login page

```json
{
  "id": "root",
  "type": "page",
  "style": { "minHeight": "100vh", "justify": "center", "align": "center", "padding": "48px" },
  "children": [
    {
      "id": "n1",
      "type": "card",
      "style": { "size": "fixed", "width": "400px", "gap": "16px" },
      "children": [
        { "id": "n2", "type": "image",      "assetId": "logo-primary", "alt": "Acme logo" },
        { "id": "n3", "type": "heading",    "text": "Welcome back",  "level": 1 },
        { "id": "n4", "type": "text-input", "label": "Email",    "name": "email",    "inputType": "email"    },
        { "id": "n5", "type": "text-input", "label": "Password", "name": "password", "inputType": "password" },
        { "id": "n6", "type": "checkbox",   "label": "Remember me", "name": "rememberMe" },
        { "id": "n7", "type": "button",     "label": "Sign in", "action": "auth:login", "validates": true, "style": { "size": "fill" } },
        { "id": "n8", "type": "link",       "label": "Forgot password?", "action": "auth:forgot-password" }
      ]
    }
  ]
}
```

## Built-in Elements

### Containers

| Type | Description |
|------|-------------|
| `page` | Root container. Always column-direction. |
| `stack` | Generic flex container with toggleable `direction` (`column` | `row`). Optional `wrap` for row-direction stacks. |
| `card` | `CoarCard` wrapper with optional `title` |
| `section` | Semantic section with optional `title` heading |
| `divider` | Visual separator (`CoarDivider`) |
| `spacer` | Empty space — `flex: 1` (fills available space) unless `size` is set |

### Typography

| Type | Props | Description |
|------|-------|-------------|
| `heading` | `text`, `level` (1–6) | H1–H6 heading |
| `paragraph` | `text` | Body text block |

### Inputs

| Type | Key props | Cocoar component |
|------|-----------|-----------------|
| `text-input` | `label`, `name`, `inputType`, `placeholder`, `validation` | `CoarTextInput` / `CoarPasswordInput` |
| `checkbox` | `label`, `name`, `validation` | `CoarCheckbox` |
| `select` | `label`, `name`, `options`, `placeholder` | `CoarSelect` |

All three support `name` (wires the value into `ActionValues`), `disabled`, and `validation`.

```ts
interface FieldValidation {
  required?:   boolean
  minLength?:  number     // text-input only
  maxLength?:  number     // text-input only
  pattern?:    string     // text-input only; regex source applied as full-string match
  matchField?: string     // value must equal this other named field's value (text-input only)
  message?:    string     // custom error message — overrides defaults
}
```

### Actions

| Type | Key props | Description |
|------|-----------|-------------|
| `button` | `label`, `action`, `validates`, `variant`, `size`, `icon` | `CoarButton` — calls the matching `actions` handler. Content-width by default; use `style.size: 'fill'` for a full-width button. |
| `link` | `label`, `action` | Inline text link. Content-width by default. |

When `validates: true` on a button, all named fields are validated before the action fires. The button is disabled while any field is invalid.

### Media

| Type | Props | Description |
|------|-------|-------------|
| `image` | `assetId`, `alt` | Resolved via `assetResolver` at render time. Raw URLs are not accepted. |

## Security boundary

The renderer enforces three rules **regardless of what the schema contains**:

1. **Allowed elements** — `config.allowedElements` is the hard boundary. Disallowed types are skipped silently (with one console warning per type).
2. **Actions** — buttons and links store an action `id`. Only handlers present in the `actions` prop fire — any other action ID is a silent no-op. Arbitrary JavaScript is never stored in the schema.
3. **Images** — `image` nodes store an `assetId` reference, never a raw URL. The renderer always goes through `assetResolver`. Tenants cannot reference external domains.

See the [Security Model](./#security-model) section on the overview page for the full discussion.

## Pairing with the builder

The same `config` should be passed to both `<CoarPageBuilder>` and `<CoarPageRenderer>`. The builder uses it as UI affordance (palette filter, action dropdown, picker hook); the renderer uses it as the security boundary. Putting the SAME object in both keeps "what tenants can author" and "what gets rendered" in sync.

See the [integration walkthrough](./#complete-idp-integration-walkthrough) for the full builder + renderer wiring example.

---

---
url: /components/document-viewer.md
---
# Document Viewer&#x20;

`@cocoar/vue-document-viewer` is a generic, source-agnostic document viewer for Vue 3. One component — [`<CoarDocumentViewer>`](./coar-document-viewer) — renders **PDFs**, **single images**, and **multi-page image galleries**, with shared toolbar chrome, side panels, and an annotation layer.

You pick the source kind with a small factory (`pdfSource(...)`, `imageSource(...)`, `imageGallerySource(...)`); the viewer dispatches internally. The toolbar greys out tools the active source doesn't support — e.g. search and outline are PDF-only — rather than hiding them, so users don't see UI moving around when they switch documents.

```ts
import {
  CoarDocumentViewer,
  imageSource,
  imageGallerySource,
} from '@cocoar/vue-document-viewer';
import { pdfSource } from '@cocoar/vue-document-viewer/pdf';
import '@cocoar/vue-document-viewer/styles';
```

`pdfjs-dist` is an **optional peer dependency**. PDF consumers import `pdfSource` from the `/pdf` subpath; image-only consumers never pay the pdfjs bundle cost.

## Three source factories

```ts
// PDF — pdfjs subpath
pdfSource({ url, headers?, withCredentials? })

// Single-page raster / vector image (JPG / PNG / SVG / WebP / AVIF / GIF / blob: / data:)
imageSource({ url })

// Multi-page image document — pages may mix orientations
imageGallerySource({ urls })
```

Each factory returns a frozen `DocumentSource`. Build it inside a `computed` so the viewer rebinds only when something actually changes — switching sources keeps the toolbar, panels, and viewport mounted; only the inner page renderer rebinds.

## Single image

Toolbar tools the source doesn't support stay visible but disabled — e.g. **Search**, **Previous/Next page**, and **Outline** are off for a single-page image. Their tooltips append the `notAvailableForSource` label so the user understands the state.

## Image gallery

Pages can mix orientations (landscape page 1, portrait page 2, wide page 3 above). Every page's intrinsic dimensions are read from its own image, so the viewer never letter-boxes or stretches. Sidebar thumbnails track the active page.

## PDF source

The PDF demo runs in the playground at [`localhost:5188/pdf-viewer`](http://localhost:5188/pdf-viewer) — it's omitted here because the pdfjs worker has to be configured by the consumer (one-line setup, below).

```vue
<script setup lang="ts">
import { computed } from 'vue';
import { CoarDocumentViewer } from '@cocoar/vue-document-viewer';
import { pdfSource } from '@cocoar/vue-document-viewer/pdf';
import '@cocoar/vue-document-viewer/styles';

const source = computed(() => pdfSource({
  url: '/api/files/contract.pdf',
  withCredentials: true,         // forward cookies / HTTP auth
  headers: { 'X-Tenant': 'acme' }, // arbitrary request headers
}));
</script>

<template>
  <CoarDocumentViewer
    :source="source"
    :show-thumbnails="true"
    :show-outline="true"
    :show-annotations-panel="true"
    :show-print-download="true"
  />
</template>
```

### Worker setup (PDF consumers only)

pdfjs needs a worker to parse the binary off the main thread. Wire it once at app bootstrap — Vite/webpack/Rollup all support the `?worker` query:

```ts
// main.ts
import * as pdfjs from 'pdfjs-dist';
import PdfWorker from 'pdfjs-dist/build/pdf.worker.min.mjs?worker';

pdfjs.GlobalWorkerOptions.workerPort = new PdfWorker();
```

If you skip this step, pdfjs will try to fetch the worker over the network and fall back to a slow inline mode — both viable, but not what you want in production.

## Source capabilities

Every source advertises what it can do. The toolbar reads these flags to enable/disable individual tools; consumers can inspect them too:

```ts
interface DocumentSourceCapabilities {
  multiPage: boolean;     // Prev / Next / page input
  textLayer: boolean;     // Text selection, Ctrl+C copy
  search: boolean;        // Search button
  outline: boolean;       // Outline (TOC) sidebar tab
  print: boolean;         // Print button
}
```

The factories pre-populate the right values: PDFs get all-true, images get a single-page no-text profile, galleries get the same with `multiPage: true`. Adding a future source kind (e.g. OCR'd images) is a matter of providing a new factory that flips the relevant flags.

::: tip Why disabled, not hidden?
Tools that vanish when the source changes make the toolbar layout shift — buttons jump positions, muscle memory breaks. Greying out keeps positions stable and surfaces the capability constraint to the user via tooltip.
:::

## Info panel

When the right-side annotations panel is open, a collapsible **Info** section at the top surfaces source metadata:

* Format string (`"PDF · v1.7"`, `"Image · PNG"`, `"Image gallery · SVG"`)
* Total page count
* Current page dimensions (live — updates as the user flips pages)
* PDF-only fields: title / author / subject / keywords / creator / producer / created / modified / PDF version (empty fields are skipped)
* File size in bytes (PDFs only — pdfjs exposes `contentLength`)

Disable with `:show-info-section="false"` if you want a minimal annotations-only panel.

## Architecture

```
<CoarDocumentViewer :source="…">
  useDocumentLoader(sourceRef)             ← internal dispatcher, watches source.kind
    usePdfDocumentAdapter(pdfSourceRef)
    useImageDocumentAdapter(imgSourceRef)
    useImageGalleryAdapter(gallerySourceRef)
        each publishes { status, pageProviders, info, error, retry, destroy }
  usePageRenderer({ pageProviders, … })    ← source-agnostic, owns canvas + textLayer DOM
  DocumentToolbar, DocumentSidebar, DocumentAnnotationPanel, DocumentSearchBar
```

The seam between formats is `PageProvider` — every page (PDF page proxy, image element, future kinds) materializes through the same interface (`render(canvas, opts)`, `cancel()`, optional `getTextLayer()`). The renderer never imports `pdfjs-dist`.

## What's next

| Page | Covers |
|------|--------|
| [CoarDocumentViewer](./coar-document-viewer) | Full props / emits / slots reference, labels, position memory |
| [Toolbar customization](./toolbar) | Order-driven `tools` array, separator pseudo-tool, section toggles |
| [Annotations](./annotations) | Modes, types, lifecycle events, schema, color picker |

---

---
url: /components/document-viewer/coar-document-viewer.md
---
# CoarDocumentViewer

The all-in-one viewer component. One required prop — `source` — plus a handful of toggles for chrome, panels, and the annotation surface.

```ts
import { CoarDocumentViewer } from '@cocoar/vue-document-viewer';
import '@cocoar/vue-document-viewer/styles';
```

For PDFs, also pull `pdfSource` from the [`/pdf` subpath](./#worker-setup-pdf-consumers-only) and wire the worker once at app bootstrap.

## Minimal usage

```vue
<script setup lang="ts">
import { computed } from 'vue';
import { CoarDocumentViewer, imageSource } from '@cocoar/vue-document-viewer';
import '@cocoar/vue-document-viewer/styles';

const source = computed(() => imageSource({ url: '/attachments/diagram.png' }));
</script>

<template>
  <CoarDocumentViewer :source="source" />
</template>
```

That's it. Toolbar on, sidebars and annotations panel off, default 'view' annotation mode. Wrap the viewer in a sized container — the component fills 100% of its parent.

## Props

### Source

| Prop | Type | Default | Notes |
|---|---|---|---|
| `source` | `DocumentSource` | *required* | Build via `pdfSource()`, `imageSource()`, or `imageGallerySource()`. Returns a frozen object — build it inside `computed` to avoid unnecessary rebinds. |

Switching the `source` keeps the surrounding chrome mounted; only the inner page renderer rebinds, so users see toolbar / panels stay still across document changes.

### Chrome toggles

| Prop | Type | Default | Notes |
|---|---|---|---|
| `showToolbar` | `boolean` | `true` | Top/side/bottom toolbar — see `toolbarPosition`. |
| `toolbarPosition` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Where the toolbar sits. Horizontal at top/bottom, vertical at sides. |
| `showThumbnails` | `boolean` | `false` | Left-rail Thumbnails tab. Works for every source (per-page mini canvas). |
| `showOutline` | `boolean` | `false` | Left-rail Outline (TOC) tab. PDF-only; auto-hides when the doc has no outline. |
| `showAnnotationsPanel` | `boolean` | `false` | Right-rail panel: Info section + annotation list with filter/sort/search. |
| `showInfoSection` | `boolean` | `true` | Top section of the annotations panel surfacing source metadata. Only active when the panel is open. |
| `showSearch` | `boolean` | `true` | Search input (button + bar). Disabled when the source can't search (e.g. images). |
| `showPrintDownload` | `boolean` | `false` | Print + Download buttons in the toolbar. |
| `showAnnotationModes` | `boolean` | `true` | The drawing-mode button group (marker / note / draw / text). |

Two convenience props — `showThumbnails || showOutline` controls the left-rail toggle button; `showAnnotationsPanel` controls the right-rail toggle. The user can collapse either rail from inside the viewer; these props gate whether the toggle is even present in the toolbar.

#### Panel open state (`v-model`)

By default, the left and right rails start closed and their open/closed state lives inside the component — fine for stand-alone viewers. If you embed the viewer inside a parent that mounts/unmounts it (e.g. a tab bar in a file explorer where the user switches between a Markdown file and a PDF and back), use `v-model` to hold the state on the parent so it **persists across remounts**.

| Prop / Event | Type | Notes |
|---|---|---|
| `:sidebar-open` + `@update:sidebar-open` (`v-model:sidebar-open`) | `boolean` | Left rail (thumbnails / outline). Default `false`. |
| `:annotations-panel-open` + `@update:annotations-panel-open` (`v-model:annotations-panel-open`) | `boolean` | Right rail (info section + annotations list). Default `false`. |

```vue
<script setup lang="ts">
import { ref } from 'vue';
const sidebarOpen = ref(false);
const panelOpen = ref(false);
</script>

<template>
  <CoarDocumentViewer
    :source="source"
    :show-thumbnails="true"
    :show-annotations-panel="true"
    v-model:sidebar-open="sidebarOpen"
    v-model:annotations-panel-open="panelOpen"
  />
</template>
```

Without `v-model`, the state is purely internal — same behavior as before, no breaking change.

### Position memory

```ts
interface CoarDocumentViewerPosition {
  page: number;                   // 0-based page index in view
  pageOffset: number;             // fractional scroll inside the page, 0..1
  zoom: number;                   // 1 = 100%
  rotation: 0 | 90 | 180 | 270;
}
```

Two compatible mechanisms:

| Prop / Event | Use when |
|---|---|
| `storageKey: string` | You want the viewer to persist position in `localStorage` automatically. Different keys per document (e.g. include the file ID) so each document remembers its own view. |
| `:position` + `@update:position` (`v-model:position`) | You own persistence (server, IndexedDB, your existing state manager). Two-way binding — the viewer reads on mount, writes on every change. |

Both mechanisms can coexist; when both are present, the bound `position` wins on mount.

### Toolbar layout

| Prop | Type | Default | Notes |
|---|---|---|---|
| `tools` | `CoarDocumentViewerTool[]` | `undefined` (= `COAR_DOCUMENT_VIEWER_ALL_TOOLS`) | Array drives BOTH the visible set AND the order. See [Toolbar customization](./toolbar). |

### Annotations

| Prop / Event | Type | Notes |
|---|---|---|
| `annotations` | `CoarPdfAnnotation[]` | Consumer-owned. The viewer never mutates this array. |
| `:annotation-mode` + `@update:annotationMode` (`v-model:annotation-mode`) | `'view' \| 'select' \| 'eraser' \| 'marker' \| 'comment' \| 'ink' \| 'freetext'` | The active pointer mode. `'view'` is read-only (existing annotations clickable, no new ones created). |
| `annotationColors` | `string[]` | Palette for the color picker. Defaults to a 7-color pastel + neon set. |
| `@annotation:create` | `(payload: CoarPdfAnnotationCreatePayload) => void` | Consumer assigns `id` + `createdAt` (+ optionally `createdBy`), pushes to `annotations`. |
| `@annotation:update` | `(payload: { id: string; patch: Partial<CoarPdfAnnotation> }) => void` | Consumer merges the patch into the matching annotation. |
| `@annotation:delete` | `(id: string) => void` | Consumer removes by id. |

See [Annotations](./annotations) for the full lifecycle, schema, and a worked example.

### Labels

```ts
interface CoarDocumentViewerLabels {
  // Loading / error overlays
  loading?: string;
  errorTitle?: string;
  errorRetry?: string;

  // Page navigation
  pageOf?: string;                  // "Page {current} of {total}"
  pageJumpAria?: string;
  prevPage?: string;
  nextPage?: string;

  // Zoom
  zoomIn?: string;
  zoomOut?: string;
  resetZoom?: string;
  zoomLevel?: string;
  fitWidth?: string;
  fitPage?: string;
  resetView?: string;
  pan?: string;

  // Rotation
  rotateCw?: string;
  rotateCcw?: string;

  // Search
  search?: string;
  searchNext?: string;
  searchPrev?: string;
  searchMatchOf?: string;           // "{current} of {total}"

  // Panels + sidebar tabs
  thumbnails?: string;
  outline?: string;
  annotationsPanel?: string;

  // Document actions
  print?: string;
  download?: string;

  // Annotation modes
  modeView?: string;
  modeSelect?: string;
  modeEraser?: string;
  modeMarker?: string;
  modeNote?: string;
  modeInk?: string;
  modeFreetext?: string;
  strokeWidth?: string;

  // Annotation panel
  noAnnotations?: string;
  noMatchingAnnotations?: string;
  searchAnnotations?: string;
  filterBy?: string;
  sortBy?: string;
  sortByPage?: string;
  sortChronological?: string;
  pagePrefix?: string;
  justNow?: string;
  moreActions?: string;
  annotationDelete?: string;
  annotationEditComment?: string;
  annotationColor?: string;

  // Capability tooltip suffix — appended when a tool isn't supported by the source.
  notAvailableForSource?: string;

  // Info section
  infoSection?: string;             // "Info"
  infoFormat?: string;
  infoPages?: string;
  infoPage?: string;                // "Page {n}"
  infoSize?: string;
  infoTitle?: string;
  infoAuthor?: string;
  infoSubject?: string;
  infoKeywords?: string;
  infoCreator?: string;
  infoProducer?: string;
  infoCreated?: string;
  infoModified?: string;
  infoPdfVersion?: string;
}
```

English defaults are baked in. Pass any subset to override individual strings — keys you omit fall back to the default. `{current}`, `{total}`, `{n}` placeholders are substituted at render time.

## Events

| Event | Payload | When |
|---|---|---|
| `update:position` | `CoarDocumentViewerPosition` | Page / scroll / zoom / rotation change. Used for `v-model:position`. |
| `update:annotationMode` | `CoarPdfAnnotationMode` | User picks a different mode in the toolbar. Used for `v-model:annotation-mode`. |
| `update:sidebarOpen` | `boolean` | User toggles the left rail (thumbnails / outline). Used for `v-model:sidebar-open`. |
| `update:annotationsPanelOpen` | `boolean` | User toggles the right rail (annotations panel). Used for `v-model:annotations-panel-open`. |
| `annotation:create` | `CoarPdfAnnotationCreatePayload` | New annotation drawn. Consumer assigns id + timestamp. |
| `annotation:update` | `{ id, patch }` | Existing annotation edited (color / comment / position). |
| `annotation:delete` | `string` (id) | Existing annotation removed (via panel menu or eraser tool). |
| `error` | `CoarDocumentViewerErrorEvent` | Source failed to load. `{ error: unknown, src?: string }`. |

## Slots

| Slot | Props | When |
|---|---|---|
| `loading` | *none* | Replaces the default `"Loading…"` text shown while the source is fetching/parsing. |
| `error` | `{ error: unknown; retry: () => void }` | Replaces the default error overlay. Call `retry()` to re-trigger the load. |

```vue
<CoarDocumentViewer :source="source">
  <template #loading>
    <CoarSpinner /> Fetching document…
  </template>
  <template #error="{ error, retry }">
    <div>
      <strong>{{ String(error) }}</strong>
      <CoarButton @click="retry">Try again</CoarButton>
    </div>
  </template>
</CoarDocumentViewer>
```

## Sizing

The viewer fills 100% of its parent and uses internal flexbox to allocate space across toolbar, panels, and the page area. Put it inside a sized container:

```vue
<div style="height: 80vh">
  <CoarDocumentViewer :source="source" />
</div>
```

Splitters between the columns are draggable — users can resize the left rail (thumbnails) and right rail (annotations panel) on the fly.

## Position memory example

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { CoarDocumentViewer, type CoarDocumentViewerPosition } from '@cocoar/vue-document-viewer';
import { pdfSource } from '@cocoar/vue-document-viewer/pdf';

const source = pdfSource({ url: '/files/manual.pdf' });

// v-model:position — server-side persistence
const position = ref<CoarDocumentViewerPosition>({
  page: 0, pageOffset: 0, zoom: 1, rotation: 0,
});
watchDebounced(position, savePositionToServer, { debounce: 300 });

// OR — storageKey for automatic localStorage persistence
</script>

<template>
  <CoarDocumentViewer
    :source="source"
    v-model:position="position"
    storage-key="manual.pdf"
  />
</template>
```

Use one OR the other in practice — both is fine, just pick the priority. When both are present, the bound `position` wins on mount; afterwards both stay in sync.

## Common configurations

### Read-only PDF viewer with thumbnails

```vue
<CoarDocumentViewer
  :source="source"
  :show-thumbnails="true"
  :show-outline="true"
  :show-print-download="true"
  :show-annotation-modes="false"
/>
```

### Annotation tool with persistence

```vue
<CoarDocumentViewer
  :source="source"
  :show-annotations-panel="true"
  v-model:annotation-mode="mode"
  :annotations="annotations"
  storage-key="contract-2024"
  @annotation:create="handleCreate"
  @annotation:update="handleUpdate"
  @annotation:delete="handleDelete"
/>
```

### Minimal embedded preview (no toolbar)

```vue
<CoarDocumentViewer :source="source" :show-toolbar="false" />
```

---

---
url: /components/document-viewer/toolbar.md
---
# Toolbar customization

The toolbar is **order-driven**: the `tools` prop is an array of tool identifiers in the order you want them to render. Want zoom buttons on the left and page navigation on the right? Just reorder the array. Want a custom layout with only the four buttons you actually need? Pass that subset.

When `tools` is omitted, the viewer falls back to `COAR_DOCUMENT_VIEWER_ALL_TOOLS` — the canonical 8-group layout with separators at the original group boundaries.

## Minimal toolbar

The canonical "nav + zoom" layout — page navigation, separator, zoom controls:

```ts
import type { CoarDocumentViewerTool } from '@cocoar/vue-document-viewer';

const MINIMAL_TOOLS: CoarDocumentViewerTool[] = [
  'prev-page',
  'page-input',
  'next-page',
  'separator',
  'zoom-out',
  'zoom-reset',
  'zoom-in',
];
```

```vue
<CoarDocumentViewer :source="source" :tools="MINIMAL_TOOLS" />
```

## The `'separator'` pseudo-tool

`'separator'` doesn't render an action — it renders a `CoarSidebarDivider` between groups. Place it anywhere in the array to visually break up clusters.

Three convenience behaviors save you from edge-case handling:

| Input | Output |
|---|---|
| Leading `'separator'` | Trimmed |
| Trailing `'separator'` | Trimmed |
| Consecutive `'separator'`s | Collapsed to one |

This matters because **section toggles** (e.g. `showSearch: false`) filter tools *before* the trim/collapse. So a `tools` array like `['prev-page', 'separator', 'search', 'separator', 'next-page']` with `showSearch: false` doesn't leave you two adjacent orphan separators — the collapse step turns it into `['prev-page', 'separator', 'next-page']` automatically.

## All available tools

The full `CoarDocumentViewerTool` union:

| Identifier | What it does | Default group |
|---|---|---|
| `sidebar-toggle` | Toggle the left rail (thumbnails / outline) | Panels |
| `annotations-panel` | Toggle the right rail | Panels |
| `prev-page` | Previous page | Navigation |
| `page-input` | "Page N of M" number input | Navigation |
| `next-page` | Next page | Navigation |
| `zoom-out` | Zoom out one step | Zoom |
| `zoom-reset` | Editable zoom-percent readout (click to reset to 100%) | Zoom |
| `zoom-in` | Zoom in one step | Zoom |
| `fit-width` | Fit page width to viewport | View |
| `fit-page` | Fit whole page to viewport | View |
| `reset-view` | Reset zoom + rotation | View |
| `rotate-ccw` | Rotate -90° | Rotation |
| `rotate-cw` | Rotate +90° | Rotation |
| `pan` | Hand tool — drag the page | Pointer |
| `select` | Select / move existing annotations | Pointer |
| `eraser` | Erase strokes from marker / ink annotations | Pointer |
| `marker` | Draw highlighter strokes | Drawing |
| `note` | Place comment pin | Drawing |
| `ink` | Free-hand ink strokes | Drawing |
| `freetext` | Place free-text box | Drawing |
| `search` | Open search bar | Actions |
| `print` | Print document | Actions |
| `download` | Download source file | Actions |
| `separator` | Visual divider between groups | *pseudo-tool* |

## Default layout

`COAR_DOCUMENT_VIEWER_ALL_TOOLS` — the canonical 8-group layout, importable so you can derive variants by filtering:

```ts
import { COAR_DOCUMENT_VIEWER_ALL_TOOLS } from '@cocoar/vue-document-viewer';

// Hide just the print + download buttons
const tools = COAR_DOCUMENT_VIEWER_ALL_TOOLS.filter(
  (t) => t !== 'print' && t !== 'download',
);
```

## Filtering layers

Three independent layers decide which buttons render and how:

```
                user's `tools` array (or COAR_DOCUMENT_VIEWER_ALL_TOOLS)
                                │
                                ▼
   ┌─────────────────────────────────────────────────────┐
   │  1. Section toggles strip whole categories          │
   │     showSearch:false       → drop 'search'          │
   │     showPrintDownload:false → drop 'print','download' │
   │     showAnnotationModes:false → drop drawing tools  │
   │     (no Thumbnails/Outline?) → drop 'sidebar-toggle'│
   │     (no AnnotationsPanel?)   → drop 'annotations-panel' │
   └─────────────────────────────────────────────────────┘
                                │
                                ▼
   ┌─────────────────────────────────────────────────────┐
   │  2. Separator normalization                         │
   │     trim leading / trailing → collapse consecutive  │
   └─────────────────────────────────────────────────────┘
                                │
                                ▼
   ┌─────────────────────────────────────────────────────┐
   │  3. Capability gating (per-tool, runtime)            │
   │     source.capabilities.search:false → 'search' disabled │
   │     source.capabilities.multiPage:false → page-nav disabled │
   │     source.capabilities.outline:false → outline tab hidden │
   │     (disabled tools STAY VISIBLE with a tooltip suffix) │
   └─────────────────────────────────────────────────────┘
                                │
                                ▼
                  Final rendered toolbar
```

Layers 1 and 2 happen in pure-function form (`computeEffectiveTools` in `internal/effective-tools.ts`) and remove items from the array. Layer 3 happens per-button at render time — it never removes anything, just toggles the `disabled` state and appends `notAvailableForSource` to the tooltip.

This is the **stable-position rule**: switching sources never makes buttons jump around, because layer 3 doesn't touch positions.

## Section toggles vs `tools` array

If you want to drop a whole category, either path works:

```ts
// A) Shorthand — section toggle
<CoarDocumentViewer :source="src" :show-print-download="false" />

// B) Explicit — omit from tools array
<CoarDocumentViewer
  :source="src"
  :tools="COAR_DOCUMENT_VIEWER_ALL_TOOLS.filter(t => t !== 'print' && t !== 'download')"
/>
```

Use the section toggle when you want to drop a category cleanly. Use `tools` when you need precise positional control — e.g. moving search to the start, or placing the page-input between zoom and rotation.

## Toolbar position

`toolbarPosition` controls where the toolbar sits relative to the page area:

```vue
<CoarDocumentViewer :source="src" toolbar-position="left" />
```

| Value | Layout |
|---|---|
| `'top'` (default) | Horizontal bar above the page area |
| `'bottom'` | Horizontal bar below the page area |
| `'left'` | Vertical rail to the left of the page area |
| `'right'` | Vertical rail to the right of the page area |

Vertical rails ('left' / 'right') still use the same `tools` array — buttons just stack vertically and the `'separator'` pseudo-tool renders as a horizontal divider instead of a vertical one.

---

---
url: /components/document-viewer/annotations.md
---
# Annotations

`CoarDocumentViewer` ships with a built-in annotation layer that supports four types — **marker** highlights, comment **notes**, free-hand **ink**, and **freetext** boxes. Annotations are **controlled**: the consumer owns the data, the viewer emits events, the consumer applies changes.

```ts
import {
  CoarDocumentViewer,
  type CoarPdfAnnotation,
  type CoarPdfAnnotationMode,
  type CoarPdfAnnotationCreatePayload,
  type CoarPdfAnnotationUpdatePayload,
} from '@cocoar/vue-document-viewer';
```

## Live demo

Pick a mode in the toolbar (marker / note / draw / text), then interact with the image. The consumer assigns `id` + `createdAt` on creation, merges patches on update, and removes on delete. Try **switch to Select**, then drag an existing annotation, or click the 3-dot menu in the right panel.

## Annotation types

Four discriminated-union types, all sharing a `BaseAnnotation` shape:

```ts
interface BaseAnnotation {
  id: string;
  type: 'marker' | 'comment' | 'ink' | 'freetext';
  pageIndex: number;       // 0-based
  color: string;           // CSS color
  createdAt: string;       // ISO timestamp
  createdBy?: string;      // Consumer-provided display string
  comment?: string;        // Every type may carry a side comment
}
```

### Marker (highlighter)

```ts
interface CoarPdfMarkerAnnotation extends BaseAnnotation {
  type: 'marker';
  strokes: CoarPdfPoint[][];  // SVG-style polyline list
  width: number;              // Stroke width in CSS px at zoom=1
}
```

Drawn like a felt-tip marker, rendered with `mix-blend-mode: multiply` so the underlying text reads through.

### Comment pin

```ts
interface CoarPdfCommentAnnotation extends BaseAnnotation {
  type: 'comment';
  anchor: CoarPdfPoint;       // Pin location in normalized page coords
  comment: string;            // REQUIRED for comment annotations
}
```

Drops a pin at the click point and opens a popover for the comment body. The comment text is mandatory — empty pins are never created.

### Ink (freehand)

```ts
interface CoarPdfInkAnnotation extends BaseAnnotation {
  type: 'ink';
  strokes: CoarPdfPoint[][];
  width: number;
}
```

Same wire shape as marker but rendered as opaque strokes (no blend mode, thinner default width).

### Freetext

```ts
interface CoarPdfFreetextAnnotation extends BaseAnnotation {
  type: 'freetext';
  rect: CoarPdfRect;          // Box geometry in normalized page coords
  text: string;               // The visible label
  fontSize: number;           // CSS px at zoom=1
}
```

User clicks to drop a text box; the textarea writes to `text` (not `comment`). Optional `comment` still works as a side note.

## Coordinate system

All coordinates are **page-relative and normalized to `[0..1]`**:

```ts
interface CoarPdfPoint { x: number; y: number; }
interface CoarPdfRect  { x: number; y: number; w: number; h: number; }
```

This means the same annotation renders correctly at any zoom level and rotation — the viewer multiplies by the current viewport at render time. Storage stays portable: an annotation drawn at 100 % zoom plays back identically at 250 %, on a different screen, or after a rotation.

## Lifecycle

The viewer never mutates the `annotations` array directly. Instead it emits three events that the consumer applies:

### Create

```ts
import { v4 as uuid } from 'uuid';

function onCreate(payload: CoarPdfAnnotationCreatePayload) {
  annotations.value = [
    ...annotations.value,
    {
      ...payload,
      id: uuid(),
      createdAt: new Date().toISOString(),
      createdBy: currentUser.displayName,
    } as CoarPdfAnnotation,
  ];
}
```

`CoarPdfAnnotationCreatePayload` is `CoarPdfAnnotation` with the consumer-owned fields stripped (`'id' | 'createdAt' | 'createdBy'`). The viewer fills in everything else — type, color, geometry, stroke data — based on the active mode and pointer input.

### Update

```ts
function onUpdate({ id, patch }: CoarPdfAnnotationUpdatePayload) {
  annotations.value = annotations.value.map((a) =>
    a.id === id ? ({ ...a, ...patch } as CoarPdfAnnotation) : a,
  );
}
```

Fired when the user edits an annotation through its popover (color, comment, freetext body) or drags it to a new position (anchor / rect / strokes). `patch` is a partial of the relevant annotation shape — apply with a plain spread.

### Delete

```ts
function onDelete(id: string) {
  annotations.value = annotations.value.filter((a) => a.id !== id);
}
```

Fired when the user picks "Delete" from the panel's 3-dot menu, or when the eraser tool removes the last stroke from a marker / ink annotation.

## Modes

```ts
type CoarPdfAnnotationMode =
  | 'view'        // Read-only — existing annotations clickable, no new ones
  | 'select'      // Existing annotations clickable AND draggable
  | 'eraser'      // Click a stroke on marker/ink to remove it
  | 'marker'      // Drawing
  | 'comment'     // Drawing — drops a pin
  | 'ink'         // Drawing
  | 'freetext';   // Drawing — drops a text box
```

Mode is two-way bound — the toolbar's mode buttons update it, but the consumer can also drive it from outside (e.g. a keyboard shortcut, a parent's "Start commenting" CTA):

```vue
<CoarDocumentViewer
  :source="src"
  v-model:annotation-mode="mode"
  :annotations="annotations"
/>
```

```ts
// Keyboard shortcut from anywhere
useEventListener(window, 'keydown', (e) => {
  if (e.key === 'm' && (e.ctrlKey || e.metaKey)) mode.value = 'marker';
});
```

## Color palette

The mode picker shows a color selector with seven defaults:

| Color | Hex |
|---|---|
| Yellow | `#fde68a` |
| Pink | `#fca5a5` |
| Green | `#86efac` |
| Blue | `#93c5fd` |
| Purple | `#c4b5fd` |
| Saturated yellow | `#facc15` |
| Hot pink | `#ec4899` |

Pass `:annotation-colors="[...]"` to override the entire palette. Each color is a CSS string — anything `rgb()`, `hsl()`, `#xxx`, `oklch()` etc. that the browser accepts works.

## Panel + filters

`:show-annotations-panel="true"` opens the right rail with:

* **Info section** at the top (source metadata — see [Overview](./)).
* **Annotation list** — every annotation, grouped by page or chronologically. Click an entry to select + scroll-to. 3-dot menu per entry: edit comment, change color, delete.
* **Filter chips** — toggle each type on/off (marker / note / ink / freetext).
* **Search input** — substring search over comments and freetext bodies.
* **Sort toggle** — By page / Chronological.

The list is read-only — every interaction goes through the same `annotation:update` / `annotation:delete` event pipeline as the in-page surface, so the consumer-owned state stays canonical.

## Worked example — collaborative review

```vue
<script setup lang="ts">
import { ref, computed } from 'vue';
import {
  CoarDocumentViewer,
  type CoarPdfAnnotation,
  type CoarPdfAnnotationMode,
  type CoarPdfAnnotationCreatePayload,
  type CoarPdfAnnotationUpdatePayload,
} from '@cocoar/vue-document-viewer';
import { pdfSource } from '@cocoar/vue-document-viewer/pdf';
import { v4 as uuid } from 'uuid';

const props = defineProps<{
  documentId: string;
  currentUser: { id: string; displayName: string };
}>();

const annotations = ref<CoarPdfAnnotation[]>([]);
const mode = ref<CoarPdfAnnotationMode>('view');
const source = computed(() =>
  pdfSource({ url: `/api/files/${props.documentId}/source.pdf`, withCredentials: true }),
);

// Initial load
onMounted(async () => {
  annotations.value = await api.listAnnotations(props.documentId);
});

async function onCreate(payload: CoarPdfAnnotationCreatePayload) {
  const next: CoarPdfAnnotation = {
    ...payload,
    id: uuid(),
    createdAt: new Date().toISOString(),
    createdBy: props.currentUser.displayName,
  } as CoarPdfAnnotation;
  // Optimistic insert; rollback on failure
  annotations.value = [...annotations.value, next];
  try { await api.createAnnotation(props.documentId, next); }
  catch (err) { annotations.value = annotations.value.filter(a => a.id !== next.id); throw err; }
}

async function onUpdate({ id, patch }: CoarPdfAnnotationUpdatePayload) {
  const before = annotations.value;
  annotations.value = annotations.value.map(a => a.id === id ? { ...a, ...patch } as CoarPdfAnnotation : a);
  try { await api.updateAnnotation(props.documentId, id, patch); }
  catch (err) { annotations.value = before; throw err; }
}

async function onDelete(id: string) {
  const before = annotations.value;
  annotations.value = annotations.value.filter(a => a.id !== id);
  try { await api.deleteAnnotation(props.documentId, id); }
  catch (err) { annotations.value = before; throw err; }
}
</script>

<template>
  <CoarDocumentViewer
    :source="source"
    v-model:annotation-mode="mode"
    :annotations="annotations"
    :show-annotations-panel="true"
    storage-key="`doc-${documentId}`"
    @annotation:create="onCreate"
    @annotation:update="onUpdate"
    @annotation:delete="onDelete"
  />
</template>
```

The controlled pattern makes optimistic updates + rollback trivial: snapshot `annotations.value`, apply locally, and revert on API failure.

## Persistence shape

Annotations are plain JSON — no `Date` objects, no class instances, no internal references. Store as-is:

```ts
// PostgreSQL JSONB column
CREATE TABLE annotations (
  id UUID PRIMARY KEY,
  document_id UUID NOT NULL REFERENCES documents,
  data JSONB NOT NULL                 -- one CoarPdfAnnotation
);
```

```ts
// MongoDB / Firestore — embed directly
{ documentId: "...", annotations: CoarPdfAnnotation[] }
```

Because coordinates are normalized, annotations migrate across documents only when the page geometry matches; they're fully portable across rendering environments (different screens, zoom levels, rotation).

## Tips

* **Always wrap `annotations` mutations in a fresh array** (`[...]`, `.map`, `.filter`) so Vue's reactivity sees the change.
* **Generate the id on create**, not before — the create event fires only after the user finishes the drawing gesture (releases the mouse / taps "Save"). Pre-creating ids causes orphan entries when the gesture is cancelled.
* **Touch interactions work the same as mouse** — drawing modes accept both. The viewer normalizes pointer events internally.
* **Eraser is destructive** — clicking a stroke on a marker/ink annotation deletes that stroke; deleting the last stroke fires `annotation:delete` for the whole annotation. There's no per-stroke undo built in; consumers wanting one should keep a history snapshot ring around their `annotations` array.

---

---
url: /components/file-explorer.md
---
# File Explorer&#x20;

`@cocoar/vue-file-explorer-core` is the **headless engine** for a VSCode-style file/asset explorer in Vue 3 — the **data + coordination**, not a finished UI. A single composable, `useFileExplorer({store})`, drives a pluggable `AssetStore<T>` backend and returns every ref + op a file explorer needs (tree + tab state machine, selection, async loading, blob-URL leases, dirty tracking, conflict resolution). It ships **no layout** — you compose the chrome with [`@cocoar/vue-ui`](/components/panel-layout) (`CoarPanelLayout`, `CoarSplitPane`, `CoarTree`, …). A batteries-included, layouted `<CoarFileExplorer>` component — under the bare `@cocoar/vue-file-explorer` name — is planned on top.

::: tip Mental model — engine, not UI
`useFileExplorer` is **headless**: it renders no editors, tabs, breadcrumbs, or layout — it returns reactive state + ops, and your view binds to `fe.*`. The composable IS the bus that wires the panels together: select in the tree → a tab opens → the editor and details panels react, all through one shared `fe.*` instance. For the **layout**, reach for the [panel-layout](/components/panel-layout) primitives; the demos below are worked examples to copy. A batteries-included `<CoarFileExplorer>` component is planned — it'll sit on exactly these pieces.
:::

```ts
import {
  useFileExplorer,
  createInMemoryAssetStore,
  type Asset,
} from '@cocoar/vue-file-explorer-core';
```

The required peer is [`@cocoar/vue-ui`](/components/tree) for `CoarTree` + `CoarTreeNodeLabel`. `@cocoar/vue-script-editor` is **optional** — only pulled in if you want the Monaco-typed `language` field on the file-meta resolver.

## Three building blocks

| Piece | Role | Doc |
|---|---|---|
| [`useFileExplorer({store})`](./use-file-explorer) | The composable. Tree state + tab state machine + async bookkeeping + every imperative op. | reference |
| [`AssetStore<T>`](./asset-store) | The data-plane contract a backend implements (HTTP, IndexedDB, in-memory, …). | contract |
| [`createInMemoryAssetStore`](./in-memory-store) | Reference implementation with reactive latency / failure / lazy / conflict knobs for demos and tests. | knobs |

## Full dispatch demo

A realistic shell — tree, tab bar (with preview/pinned), breadcrumb, and a dispatched editor area that swaps between `CoarScriptEditor` (Monaco) for code, `CoarMarkdownEditor` (Milkdown) for markdown, and `CoarDocumentViewer` for images. Click around, edit anything, **Ctrl+S** saves.

Click a file to **preview** it (italic title) — clicking another file replaces the preview tab. **Double-click** to pin (italic clears). Editing a preview tab auto-pins it the moment it goes dirty — the impossible "italic + unsaved" state never exists.

::: tip Persistent viewer config across file swaps
Open `logo.svg`, click the thumbnails toggle to open the left rail, then switch to `README.md` and back. The rail stays open. Same for any tool config you pass.

That's because in the demo, `viewerSidebarOpen` / `viewerAnnotationsPanelOpen` / `viewerTools` live as refs **outside** the editor `v-if` branch — they're consumer-owned state, just passed into `CoarDocumentViewer` via `v-model` (for the panel toggles) and `:tools` (for toolbar config). When you switch from `.md` (Milkdown) back to `.svg` (DocumentViewer), the viewer is freshly mounted but the props it sees on mount are the persisted values — so the panel comes up open, the same tools are configured. No additional API needed on `useFileExplorer` — the shell owns it.
:::

## Minimal shell

Same composable, no heavy editors — useful as a starting point or for plain-text use cases:

The composable returns refs (`rootNodes`, `selectedId`, `expanded`, `openTabs`, `activeTab`, `loadingNodes`, `savingNodes`, `breadcrumbPath`) and ops (`openFile`, `saveTab`, `closeTab`, `addFolder`, `addFiles`, `deleteNode`, `moveNode`, `rename`, `reorderTab`, …). Wire whichever you need into your shell.

::: tip Where's the `<CoarFileExplorer>` component?
Planned — and reserved under the bare `@cocoar/vue-file-explorer` name. It'll be built on these exact pieces: `useFileExplorer` + the [panel-layout](/components/panel-layout) primitives + `CoarTree`. The engine ships first because the **layout** is the part consumers most want to own (sidebar arrangement, tab bar styling, editor dispatch, context-menu shape); the hard-to-get-right bits (placeholder-then-fill open, optimistic rollback, blob-URL lifecycle, beforeunload warning, drag-to-reorder tabs) already live in the engine.
:::

## Details panel

The explorer hands you the **data** for a details / info panel; **where** it renders is your layout's call. `useFileExplorer` exposes **`selectedAsset`** (the selected node, resolved reactively from `selectedId`) and **`describeAsset(asset)`** (its framework-known property rows). Drop the panel below the tree, into a [`CoarPanelLayout`](/components/panel-layout) region — wherever.

`describeAsset` returns only what the framework can know from the `Asset` shape + resolved file-meta — **Name, Type, Language** (script files), **Extension**, and **Path**:

```ts
const fe = useFileExplorer({ store });
// fe.selectedAsset: Readonly<Ref<Asset<T> | null>>
// fe.describeAsset(asset) → [{ key, label, value }, …]
```

```vue
<dl v-if="fe.selectedAsset.value">
  <div v-for="p in fe.describeAsset(fe.selectedAsset.value)" :key="p.key">
    <dt>{{ p.label }}</dt><dd>{{ p.value }}</dd>
  </div>
</dl>
```

Domain fields (size, modified date, author, …) live in your generic `payload<T>` — the framework can't know them, so **append your own rows**: `[...fe.describeAsset(asset), ...myPayloadRows(asset)]`. Need full control? Skip `describeAsset` and build the panel straight off `selectedAsset`.

::: tip Resizable tree-over-details sidebar
Want the tree stacked above the details panel with a draggable divider (VS-Code style)? Nest a [`CoarSplitPane`](/components/panel-layout) in your sidebar — tree in `#first`, the `selectedAsset` / `describeAsset` panel in `#second`. See the [panel layout](/components/panel-layout) docs.
:::

## Lazy mode

Stores that implement `loadChildren(parentId)` opt into lazy loading. The composable detects the capability automatically — no flag needed.

`hasChildren` hints control which folders show a chevron before their kids load. `loadingNodes` exposes the per-row spinner state so consumers can swap icon → spinner during a fetch.

## Conflict policies

Uploads and creates run through a per-store conflict policy. Default `'rename'` mirrors Finder / VSCode auto-suffixing (`foo.txt` → `foo (2).txt`).

`move` and `rename` deliberately **bypass** the policy — those are explicit user intent, not file additions, so silently changing the requested name would be surprising.

## Sort modes

Sibling ordering lives on the composable (not the store), because filesystem backends can't persist per-entry order. Pick one of three built-in strategies or pass a comparator.

| Mode | Behavior |
|---|---|
| `'folders-first'` (default) | Folders alphabetical, then files alphabetical — VSCode / Windows Explorer pattern. |
| `'alphabetical'` | All entries mixed alphabetical — Finder pattern. |
| `'manual'` | Array order = visual order. Drop-between-siblings positions persist via `store.move(id, parentId, position)`. |
| `(a, b) => number` | Custom comparator (e.g. by extension, by mtime). |

In any non-manual mode the composable silently drops the `position` argument when forwarding to `store.move()` — the comparator decides the final position after the parent change. `api.reorderable: Ref<boolean>` is reactive, so a toolbar can flip drag modes at runtime.

## Architecture

```
useFileExplorer({store})
├── AssetStore<T>                           ← your backend
│     loadTree / loadChildren / loadContent
│     createFolder / createFile / uploadFile
│     save / rename / delete / move
├── tree state                              ← rootNodes, selectedId, expanded
├── tab state machine                       ← openTabs, activeTab, dirty, pin/preview
├── async state                             ← loadingNodes, savingNodes
├── blob-URL leases                         ← revoked on delete + unmount
├── beforeunload warning                    ← active while any tab is dirty
└── 3-stage file-meta fallback              ← asset.editor → getFileMeta → ext heuristic
```

The composable knows nothing about HTTP / IndexedDB / multipart — the `AssetStore<T>` contract is the seam. Swap implementations without touching the view.

## What's next

| Page | Covers |
|------|--------|
| [`useFileExplorer`](./use-file-explorer) | Options, return surface, tab state machine, navigation helpers, lifecycle |
| [`AssetStore<T>` contract](./asset-store) | Every method's signature + semantics, conflict pipeline, lazy opt-in, error funnel |
| [In-memory store](./in-memory-store) | `createInMemoryAssetStore` knobs — latency / failure / sort / lazy / conflict |

---

---
url: /components/file-explorer/use-file-explorer.md
---
# useFileExplorer

`useFileExplorer<T>({store, ...})` is the composable. It wires a configured [`AssetStore<T>`](./asset-store) into reactive tree + tab state, owns the async / dirty / blob-URL bookkeeping, and returns every ref and op a file-explorer shell needs.

```ts
import {
  useFileExplorer,
  type UseFileExplorerOptions,
  type UseFileExplorerReturn,
  type OpenTab,
} from '@cocoar/vue-file-explorer-core';
```

## Options

```ts
interface UseFileExplorerOptions<T = unknown> {
  store: AssetStore<T>;
  onError?: (op: AssetOp, err: unknown, ctx: AssetOpContext) => void;
  getFileMeta?: (asset: Asset<T>) => FileMeta | null;
  confirm?: (message: string) => boolean;
  initialExpandedIds?: readonly string[];
  sortMode?: MaybeRefOrGetter<SortMode<T>>;
}
```

| Option | Default | Notes |
|---|---|---|
| `store` | *required* | Anything implementing [`AssetStore<T>`](./asset-store). The single seam between view and backend. |
| `onError` | *no-op* | Single funnel for every store rejection. The composable has already rolled back by the time this fires. |
| `getFileMeta` | *none* | Stage-2 of the file-meta fallback chain. Returns `null` to fall through to the extension heuristic. |
| `confirm` | `window.confirm` | Used by `closeTab` / `closeOthers` / `closeToRight` / `closeAll` to confirm discarding dirty tabs. Override for custom dialogs. |
| `initialExpandedIds` | top-level folders (eager) / `[]` (lazy) | Folder ids to seed `expanded` with. Defaults to root folders in eager mode so the user sees content immediately; defaults to empty in lazy mode so the canonical click-to-expand UX appears. |
| `sortMode` | `'folders-first'` | Sibling ordering strategy. `MaybeRefOrGetter` so a toolbar can flip it live. See [sort modes](./#sort-modes). |

## Return surface

The return is organized into four groups: tree state, tab state, ops, navigation.

### Tree state

```ts
readonly assets: Readonly<Ref<readonly Asset<T>[]>>;
readonly rootNodes: Readonly<Ref<readonly Asset<T>[]>>;
selectedId: Ref<string | null>;
readonly selectedAsset: Readonly<Ref<Asset<T> | null>>;
expanded: Ref<Set<string>>;
readonly loading: Readonly<Ref<boolean>>;
readonly loadingNodes: Readonly<Ref<ReadonlySet<string>>>;
readonly savingNodes: Readonly<Ref<ReadonlySet<string>>>;
readonly reorderable: Readonly<Ref<boolean>>;
```

| Ref | Notes |
|---|---|
| `assets` | Flat reactive list — the store's underlying projection. Read-only from the consumer's perspective. |
| `rootNodes` | Already filtered + sorted children of `null`. Pass directly to `<CoarTree :nodes>`. |
| `selectedId` | Two-way. Single-click on a row sets this; a watcher then opens the file as a preview tab. |
| `selectedAsset` | Read-only. `selectedId` resolved to the `Asset` (or `null`). Pair with `describeAsset` for a [details panel](./#details-panel). |
| `expanded` | Two-way `Set<string>` of expanded folder ids. Lazy loading is driven by CoarTree's `loadChildren` hook (bind `:load-children="fe.loadChildren"`) — the tree fires the fetch on first expand. |
| `loading` | `true` during the **initial** `store.loadTree()` call only. Per-file content loads live on `loadingNodes`; per-folder lazy loads are owned by the tree (`isLoading` slot prop). Stays `false` for stores that surface their own reactive `_assets`. |
| `loadingNodes` | Per-id Set of files being `loadContent`-fetched. (Folder lazy-loads moved to CoarTree's per-row `isLoading` slot prop.) Bind to row-icon → spinner swap. |
| `savingNodes` | Per-id Set: any in-flight save / rename / delete / move. Same spinner channel as `loadingNodes`. |
| `reorderable` | `true` when `sortMode === 'manual'`. Reactive — read it in your CoarTree wiring to gate drop-between-siblings. |

### CoarTree wiring helpers

```ts
getId: (a: Asset<T>) => string;
getChildren: (a: Asset<T>) => readonly Asset<T>[] | undefined;
getLabel: (a: Asset<T>) => string;
isExpandable: (a: Asset<T>) => boolean;
loadChildren?: (node: Asset<T>) => Promise<void>; // lazy stores only — bind to <CoarTree :load-children>
```

These mirror `<CoarTree>`'s prop signatures so you can pass them straight through:

```vue
<CoarTree
  :nodes="fe.rootNodes.value"
  :get-id="fe.getId"
  :get-children="fe.getChildren"
  :get-label="fe.getLabel"
  :is-expandable="fe.isExpandable"
  :load-children="fe.loadChildren"
  v-model:expanded="fe.expanded.value"
  v-model:selected="fe.selectedId.value"
  draggable
  renamable
  @activate="fe.activateNode"
  @rename="({ node, newName }) => fe.rename(node.id, newName)"
  @node-move="fe.moveNode"
/>
```

`isExpandable` returns `false` for folders the store reports as `hasChildren: false` — keeps the chevron off known-empty folders in lazy mode.

For **lazy stores**, bind `:load-children="fe.loadChildren"` (`undefined` for eager stores, so the binding is a no-op there). CoarTree calls it on first expand of an unloaded folder and owns the loading state (`isLoading` slot prop), the error state (`hasError` + `@load-error`) and retry (`api.reloadChildren`); the composable just supplies the fetch body and caches loaded folders so re-expand never re-fetches. Render the spinner where you like from `isLoading` (e.g. swap the row icon) and pass `hide-loading-spinner` to drop the tree's built-in chevron spinner. See the [tree lazy-loading docs](/components/tree#lazy-loading-async-children). Lazy-load failures reach **both** `onError('loadChildren', …)` (log/toast) and the tree's `@load-error` / `hasError` (row UX) — pick one channel for user-facing messaging to avoid duplicates.

### Tab state

```ts
readonly openTabs: Readonly<Ref<readonly OpenTab[]>>;
activeId: Ref<string | null>;
readonly activeTab: Readonly<Ref<OpenTab | null>>;
readonly anyDirty: Readonly<Ref<boolean>>;
isDirty: (tab: OpenTab) => boolean;
setContent: (id: string, content: string) => void;

interface OpenTab {
  id: string;
  name: string;
  editor: FileEditor;
  language?: CoarScriptEditorLanguage;
  content: string;          // current editor buffer
  savedContent: string;     // last persisted — content !== savedContent ⇒ dirty
  pinned: boolean;          // false = preview (italic, replaced on next preview)
}
```

The tab state machine implements the VSCode pattern:

| Trigger | Result |
|---|---|
| Single-click on a file row | Push a **preview** tab (italic title). At most one preview exists at a time — opening another preview replaces it. |
| Double-click / Enter / "Open" menu | Open as **pinned**. Existing previews are upgraded in place. |
| User edits → `setContent` differs from `savedContent` | Auto-pin the tab. Eliminates the impossible "italic + dirty" state. |
| `closeTab` while dirty | Calls `options.confirm` ("Discard unsaved changes to '{name}'?"). |
| `closeTab` while `savingNodes.has(id)` | Bails — closing would orphan the in-flight save. |

### Imperative ops

```ts
// CRUD — optimistic; resolve when the backend confirms
addFolder(parentId: string | null, name: string): Promise<Asset<T> | null>;
addFiles(parentId: string | null, files: FileList | readonly File[]): Promise<void>;
deleteNode(asset: Asset<T>): Promise<void>;
move(id: string, newParentId: string | null, position?: number): Promise<void>;
moveNode(e: CoarTreeNodeMoveEvent<Asset<T>>): Promise<void>;
rename(id: string, newName: string): Promise<void>;
refresh(folderId?: string | null): Promise<void>;

// Tab ops
openFile(asset: Asset<T>, opts?: { pinned: boolean }): Promise<void>;
activateNode(asset: Asset<T>): void;          // dblclick / Enter — opens pinned
saveTab(id: string): Promise<boolean>;
saveActive(): Promise<void>;
closeTab(id: string): void;
closeOthers(keepId: string): void;
closeToRight(anchorId: string): void;
closeAll(): void;
pinTab(id: string): void;
unpinTab(id: string): void;
reorderTab(sourceId: string, targetId: string, position: 'before' | 'after'): void;
```

Notes on the trickier ones:

* **`addFolder`** is **optimistic**: a temp node is inserted immediately, then reconciled to the backend's real id on resolve (rolled back on error). Pairs with [`<CoarTree>`'s `startCreate`](../tree#inline-create) so the draft → real-node handoff has no flicker. (Stores that surface their own reactive `_assets` skip the temp node — their own mutation is the source.)
* **`addFiles`** is the OS-drop entry point. The composable derives content per file (text or `URL.createObjectURL` for PDF / image), calls `store.uploadFile()`, then `store.save(id, content)` **if the store has `save`**. The merged node is stamped with the target `parentId`, so a folder-filtered grid shows it immediately even if the store's returned asset omitted it. Blob URLs are tracked and revoked on delete + unmount.
* **`move`** is the plain programmatic move (optimistic + rollback) for sources that aren't a tree drag — a "move to folder" `<select>`, a grid card dropped on a folder row, an undo command. `newParentId: null` moves to the root; `position` (an index within the new parent's children) is honored only in `'manual'` sort mode. **`moveNode`** delegates to it.
* **`moveNode`** consumes `<CoarTree>`'s `CoarTreeNodeMoveEvent`. For `position: 'inside'`, it auto-expands the target folder. For `'before' / 'after'`, it forwards a computed index only when `reorderable.value`.
* **`openFile`** is the placeholder-then-fill flow. The placeholder tab is pushed + activated immediately; on `loadContent` rejection the placeholder rolls back so the user isn't stranded. **Browse-only stores** (no `loadContent`) make this a no-op — no editor tabs open, and the single-click-preview watcher stays quiet.
* **`activateNode`** is meant for `<CoarTree @activate>`. Files open pinned; folders are a no-op (CoarTree itself toggles expansion).
* **`reorderTab`** is for drag-to-reorder. No-op on self-drop or unknown ids; pinned status is preserved on the moved tab.
* **`refresh()`** re-runs `store.loadTree()` (or `store.loadChildren(folderId)` in lazy mode when given a folder id). Use it when upstream state can change out-of-band — a SignalR push from the backend, another tab uploading a file, a server-side retention sweep. No-op for stores that surface a reactive `_assets` directly: those are already live.

### Navigation

```ts
revealInTree(id: string, focusNode?: (id: string) => void): void;
readonly breadcrumbPath: Readonly<Ref<readonly string[]>>;
pathOf(id: string): string[];
fileMeta(asset: Asset<T>): FileMeta | null;
describeAsset(asset: Asset<T>): AssetProperty[]; // { key, label, value }
```

| Helper | Notes |
|---|---|
| `revealInTree` | Walks the parentId chain, expands every ancestor in one batch, sets `selectedId`, then calls `focusNode?.(id)` after Vue flushes. Pass the tree's `api.focusNode` if you have it. |
| `breadcrumbPath` | Name-path of the **active tab**. Drives the editor-area breadcrumb. |
| `pathOf(id)` | Name-path of any asset. Used for quick-open / recent-files matchers. |
| `fileMeta(asset)` | Runs the 3-stage fallback. Returns `null` for unrecognised binary types — caller skips with a warning. |
| `describeAsset(asset)` | Framework-known property rows (Name, Type, Language, Extension, Path) for a [details panel](./#details-panel). Append your own `payload`-derived rows. Pure helper also exported as `buildAssetProperties`. |

## Persistent viewer config across file swaps

When the consumer's shell mounts different editors via `v-if` based on `activeTab.editor`, each editor component is freshly mounted on every editor-type swap (e.g. `.md` → `.ts` → `.md` unmounts + remounts Monaco the second time). Any internal editor state — Monaco's scroll position, `CoarDocumentViewer`'s sidebar open / closed, Milkdown's toolbar collapse — **resets on remount** unless the consumer's shell holds that state as refs and passes them in.

The cleanest pattern: hold whatever you want to persist as refs **outside the `v-if` branch**, bind them via `v-model` or pass them via props.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { CoarDocumentViewer, type CoarDocumentViewerTool } from '@cocoar/vue-document-viewer';

// These live in the shell, not inside the v-if branch — they survive editor swaps.
const viewerSidebarOpen = ref(false);
const viewerAnnotationsPanelOpen = ref(false);
const viewerTools: CoarDocumentViewerTool[] = [
  'sidebar-toggle', 'annotations-panel', 'separator',
  'zoom-out', 'zoom-reset', 'zoom-in', 'separator',
  'fit-width', 'fit-page',
];
</script>

<template>
  <CoarDocumentViewer
    v-if="fe.activeTab.value?.editor === 'image' && imageSrc"
    :source="imageSrc"
    :tools="viewerTools"
    :show-thumbnails="true"
    :show-annotations-panel="true"
    v-model:sidebar-open="viewerSidebarOpen"
    v-model:annotations-panel-open="viewerAnnotationsPanelOpen"
  />
</template>
```

::: tip This is shell-level state, not composable-level
The composable deliberately knows nothing about editors — `useFileExplorer` doesn't render them or hold their config. That keeps it independent of any specific editor package, and lets every consumer's shell define its own dispatch logic (which editor for which file type, fall-through to plain text, custom editors for proprietary asset payload types, …). The trade-off: editor persistence is a shell concern. The pattern above is the canonical way to handle it.
:::

This works for every editor: hold a Monaco view-state ref outside the `v-if` and restore it in `onMounted`; hold a Milkdown collapsed-toolbar boolean outside and pass it via prop; hold the position memory ref outside and bind it to `v-model:position`. The composable doesn't care — its job is the tree + tab state, not the editor's internals.

## Lifecycle

* **Mount — the tree loads itself.** `useFileExplorer` calls `store.loadTree()` automatically on mount (it kicks off the fetch synchronously during setup; `loading` is your "populating" signal). **You don't need a manual `fe.refresh()` in `onMounted`** — that would be a redundant second fetch. Reserve `refresh()` for out-of-band changes (server push, another tab mutating, retention sweep). Stores that surface their own reactive `_assets` (the in-memory impl) are live from creation, so the auto-load is a no-op for them.
* **Lazy children** — Lazy loading is driven by CoarTree's `loadChildren` hook (bind `:load-children="fe.loadChildren"`): the tree fires the fetch on first expand and on mount for any seeded `initialExpandedIds` (cascading as parents publish). The composable supplies only the fetch body and caches loaded folders so re-expand never re-fetches.
* **Eager open** — Single-click `selectedId` change is watched; file selections fire `openFile(file, { pinned: false })`.
* **Unmount** — `onScopeDispose` removes the `beforeunload` listener and revokes every blob URL the composable owns. Consumer doesn't need to clean up.
* **`beforeunload`** — Active while `anyDirty.value` is true. Browser shows its native "leave site?" prompt.

## Example consumer shell

A minimal shell — tree + breadcrumb + a single-tab editor area — to show what the composable's surface looks like in practice:

```vue
<script setup lang="ts">
import {
  createInMemoryAssetStore,
  useFileExplorer,
  type Asset,
} from '@cocoar/vue-file-explorer-core';
import { CoarTree, CoarTreeNodeLabel, CoarBreadcrumb, CoarBreadcrumbItem } from '@cocoar/vue-ui';

const seed: Asset[] = [
  { id: 's', name: 'src', kind: 'folder', parentId: null },
  { id: 'u', name: 'utils.ts', kind: 'file', parentId: 's' },
];
const store = createInMemoryAssetStore({
  initialTree: seed,
  initialContent: { u: 'export const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));' },
});
const fe = useFileExplorer({
  store,
  onError: (op, err) => console.warn(`[file-explorer] ${op}:`, err),
});
</script>

<template>
  <div class="shell">
    <aside>
      <CoarTree
        :nodes="fe.rootNodes.value"
        :get-id="fe.getId"
        :get-children="fe.getChildren"
        :get-label="fe.getLabel"
        :is-expandable="fe.isExpandable"
        :load-children="fe.loadChildren"
        v-model:expanded="fe.expanded.value"
        v-model:selected="fe.selectedId.value"
        renamable
        @activate="fe.activateNode"
        @rename="({ node, newName }) => fe.rename(node.id, newName)"
      >
        <template #default="{ node }">
          <CoarTreeNodeLabel :label="node.name" />
        </template>
      </CoarTree>
    </aside>
    <main>
      <CoarBreadcrumb v-if="fe.activeTab.value">
        <CoarBreadcrumbItem v-for="seg in fe.breadcrumbPath.value" :key="seg">
          {{ seg }}
        </CoarBreadcrumbItem>
      </CoarBreadcrumb>
      <textarea
        v-if="fe.activeTab.value"
        :value="fe.activeTab.value.content"
        @input="e => fe.setContent(fe.activeTab.value!.id, (e.target as HTMLTextAreaElement).value)"
      />
    </main>
  </div>
</template>
```

The full POC (`apps/playground/src/views/FileExplorerPocView.vue` — ~1280 LoC) wires every feature: tab bar with drag-to-reorder, context menus, `Ctrl+P` quick-open, simulator panel for latency / failure / sort / conflict, editor dispatch across Monaco / Milkdown / `CoarDocumentViewer`, OS file drop, reveal-in-tree. Treat it as the worked reference.

---

---
url: /components/file-explorer/asset-store.md
---
# AssetStore\<T> contract

`AssetStore<T>` is the data-plane interface that decouples the file-explorer UX from any specific backend. Implement these methods over HTTP, IndexedDB, S3, the OPFS, an in-memory `ref` — the composable doesn't care. `createAssetStore(config)` returns a typed store from a flat config struct; this is the recommended factory because it gives future cross-cutting wrappers (request dedup, retry, telemetry) a place to land.

```ts
import {
  createAssetStore,
  type AssetStore,
  type AssetStoreConfig,
  type Asset,
} from '@cocoar/vue-file-explorer-core';
```

## The shape

```ts
interface AssetStore<T = unknown> {
  // read
  loadTree(): Promise<Asset<T>[]>;
  loadChildren?(parentId: string): Promise<Asset<T>[]>;   // optional — opts into lazy mode
  loadContent?(id: string): Promise<string | Blob>;       // optional — omit for browse-only

  // write
  createFolder(parentId: string | null, name: string): Promise<Asset<T>>;
  createFile?(parentId: string | null, name: string): Promise<Asset<T>>; // optional — composable never calls it
  uploadFile(parentId: string | null, file: File): Promise<Asset<T>>;
  save?(id: string, content: string | Blob): Promise<void>;  // optional — omit for browse-only
  rename(id: string, newName: string): Promise<void>;
  delete(id: string): Promise<void>;
  move(id: string, newParentId: string | null, position?: number): Promise<void>;
}
```

::: tip Browse-only stores
`loadContent`, `save` and `createFile` are **optional**. A consumer that only browses + edits metadata (e.g. an image library) can omit all three: the composable then skips the post-upload `save` (no spurious "saving not supported" error), treats `openFile` as a no-op (no editor tabs), and `saveTab` reports failure cleanly. `createAssetStore` attaches optional methods only when you supply them, so `'save' in store`-style capability probes stay reliable.
:::

::: tip Throw on failure
The composable funnels every store rejection through `onError(op, err, ctx)` and rolls back the optimistic local mutation before the callback fires. Throw — don't return a tagged error object. The composable interprets a resolved promise as success.
:::

## The asset shape

```ts
interface Asset<T = unknown> {
  id: string;                  // stable across mutations — used for tree identity
  name: string;
  kind: 'folder' | 'file';
  parentId: string | null;     // null = root; flat structure, NOT nested children[]
  hasChildren?: boolean;       // lazy hint — set on folders in loadTree() / loadChildren()
  editor?: FileEditor;         // optional explicit override (wins the 3-stage fallback)
  language?: CoarScriptEditorLanguage;
  payload?: T;                 // your domain data — MIME, size, owner, etc.
}
```

The hierarchy is flat with a `parentId` link, **not** nested with embedded `children[]`. That's deliberate: backends can return root + descendants in any order, the composable filters at render time, and mutations (move / delete / rename) operate on a single object instead of walking and re-stitching trees.

## Reading

### `loadTree(): Promise<Asset<T>[]>`

**Called once on mount** by `useFileExplorer`. The composable holds the returned array as its internal projection and patches it after each successful CRUD op (`createFolder`, `createFile`, `uploadFile`, `delete`, `rename`, `move`). Call [`api.refresh()`](./use-file-explorer#imperative-ops) to re-fetch when upstream state changes out-of-band.

Two contracts depending on whether `loadChildren` is present:

| `loadChildren` | What `loadTree` returns |
|---|---|
| absent | The **full hierarchy** — every asset the user can reach. Eager mode. |
| present | Just **root-level** entries. Mark folders with `hasChildren: true` if they have children that aren't yet loaded. Lazy mode. |

Folders with `hasChildren: false` (explicit) hide the chevron and are non-expandable. Leave it `undefined` to treat every folder as potentially-expandable.

### `loadChildren?(parentId): Promise<Asset<T>[]>`

Implement this to opt into lazy loading. Called on first expand of each folder. Subsequent expansions of the same folder don't re-call — the composable caches the loaded set per session.

Return one level of children. The composable merges them into the projection so siblings render in the correct sort order.

### `loadContent(id): Promise<string | Blob>`

Called when a file is opened in a tab. Return type depends on the editor — picked via the 3-stage fallback `asset.editor → config.getFileMeta(asset) → defaultFileMetaFromName(asset.name)`:

| Editor | Expected content |
|---|---|
| `'script'` | `string` — Monaco grammar is picked from `language`. |
| `'markdown'` | `string` — Milkdown WYSIWYG content. |
| `'pdf'` | `string` (URL) or `Blob` — handed to `pdfSource()`. |
| `'image'` | `string` (URL) or `Blob` — handed to `imageSource()`. |

The composable caches loaded content per tab; reopening a closed file re-calls `loadContent` (caches are tab-scoped, not session-scoped).

::: warning Placeholder-then-fill
A tab is pushed + activated **immediately** when the user clicks a file; `loadContent` runs concurrently and the editor only mounts when `loadingNodes.has(activeId)` flips false. A rejection rolls the placeholder back so the user isn't stranded on an empty editor for a file that never loaded.
:::

## Writing

All write ops are optimistic — the composable mutates local state synchronously, awaits the store, and rolls back on rejection. Each method emits a `savingNodes` entry while in flight so the row icon can swap to a spinner.

### `createFolder(parentId, name)` · `createFile(parentId, name)`

Create an empty folder / file under `parentId` (`null` = root). Returns the persisted asset with its stable id assigned. Name collisions run through the conflict pipeline (see below).

### `uploadFile(parentId, file)`

Distinct from `createFile` so backends can pick multipart / signed-URL transports. **The store creates the entry only** — the composable owns the byte → string/Blob conversion (it knows the editor and when to use `URL.createObjectURL`) and follows up with `save(id, content)`. Keeps the store framework-agnostic over blob-URL leases.

### `save(id, content)`

Persist new file content. Called on `Ctrl+S` (via `saveTab` / `saveActive`) and after `uploadFile`. The composable blocks tab close while a save is in flight (`closeTab` bails early if `savingNodes.has(id)`).

### `rename(id, newName)`

Rename in-place. Throws on sibling-name collision — `rename` deliberately **bypasses** the conflict policy because the user just typed a name and silently changing it would be surprising.

### `delete(id)`

Recursive — folder deletes cascade. The composable closes any open tab for the deleted asset (or any descendant) and revokes blob URLs it owns for those assets.

### `move(id, newParentId, position?)`

Reparent. `position` is the destination index inside the new parent's children; `undefined` means append. `newParentId === null` moves to root.

The composable only passes `position` when `sortMode === 'manual'` — in non-manual modes the comparator decides where the moved node lands, so `position` is silently dropped. Implementations should still accept the optional arg for forwards compatibility.

## Conflict policy

Create + upload run through a conflict policy on sibling-name collision. The policy is configured on the store (see [`createInMemoryAssetStore`'s `onConflict` knob](./in-memory-store#onconflict)) and resolves to one of:

```ts
type ConflictResolution =
  | { action: 'overwrite' }
  | { action: 'rename'; newName: string }
  | { action: 'cancel' };
```

Built-in policies:

| Policy | Behavior |
|---|---|
| `'rename'` (default) | Auto-suffix: `foo.txt` → `foo (2).txt` → `foo (3).txt`. Matches Finder / VSCode. |
| `'overwrite'` | Delete the existing entry (recursively) and proceed with the requested name. |
| `'prompt'` | `window.prompt` for an alternative name, default to the auto-suggestion. Cancel → throws. |
| `'error'` | Never resolves — always throws the conflict error. |
| `(info) => ConflictResolution \| Promise<ConflictResolution>` | Custom resolver. Async OK. |

The function form receives a `ConflictInfo<T>`:

```ts
interface ConflictInfo<T = unknown> {
  existing: Asset<T>;
  incoming: { name: string; kind: 'folder' | 'file' };
  parentId: string | null;
  suggestedRename: string;       // 'foo (2).txt'
}
```

::: info Policy runs BEFORE latency
Resolution runs synchronously (relative to the store's own simulated latency in the in-memory impl), so a `'prompt'` dialog isn't blocked behind an artificial 1-second wait.
:::

## Error funnel

All store rejections funnel through one consumer-supplied callback:

```ts
type AssetOp =
  | 'loadTree' | 'loadChildren' | 'loadContent'
  | 'createFolder' | 'createFile' | 'uploadFile'
  | 'save' | 'rename' | 'delete' | 'move';

interface AssetOpContext {
  id?: string;                   // affected asset id
  parentId?: string | null;      // for create / move
  name?: string;                 // for create / rename
  file?: File;                   // for uploadFile
}

onError?: (op: AssetOp, error: unknown, ctx: AssetOpContext) => void;
```

By the time `onError` fires the composable has already rolled back the optimistic mutation (e.g. a failed `loadContent` removes the placeholder tab, a failed `uploadFile` skips the follow-up `save`). The callback's job is presentation — toast, dialog, inline banner. No return value.

## File-meta resolution

The store can supply a `getFileMeta(asset)` override that runs in the middle of a 3-stage fallback chain:

```ts
getFileMeta?: (asset: Asset<T>) => FileMeta | null;

interface FileMeta {
  editor: 'script' | 'markdown' | 'pdf' | 'image';
  language?: CoarScriptEditorLanguage;     // only meaningful when editor === 'script'
}
```

| Stage | Source | Use when |
|---|---|---|
| 1 | `asset.editor` (+ `asset.language`) on the asset itself | The backend knows the editor authoritatively (e.g. a typed asset DB). |
| 2 | `config.getFileMeta(asset)` | The editor choice depends on something other than the filename — MIME, a `type` field, user preferences. Return `null` to fall through. |
| 3 | `defaultFileMetaFromName(asset.name)` | Extension heuristic — handles ~40 Monaco grammars + markdown + pdf + common image formats. |

`resolveFileMeta(asset, {getFileMeta})` is exported if you need to run the same fallback outside the composable.

## Wiring a real backend

```ts
import { createAssetStore, type Asset } from '@cocoar/vue-file-explorer-core';

interface MyAsset { mimeType: string; size: number }

const store = createAssetStore<MyAsset>({
  async loadTree() {
    const res = await fetch('/api/assets');
    return await res.json() as Asset<MyAsset>[];
  },
  async loadContent(id) {
    return await fetch(`/api/assets/${id}/content`).then(r => r.text());
  },
  async createFolder(parentId, name) {
    return await api.post('/api/folders', { parentId, name });
  },
  async createFile(parentId, name) {
    return await api.post('/api/files', { parentId, name });
  },
  async uploadFile(parentId, file) {
    const body = new FormData();
    body.set('parentId', parentId ?? '');
    body.set('file', file);
    return await api.post('/api/files/upload', body);
  },
  async save(id, content) { await api.put(`/api/files/${id}`, content); },
  async rename(id, newName) { await api.patch(`/api/assets/${id}`, { name: newName }); },
  async delete(id) { await api.delete(`/api/assets/${id}`); },
  async move(id, parentId, position) {
    await api.patch(`/api/assets/${id}`, { parentId, position });
  },

  // optional — opt into lazy loading
  async loadChildren(parentId) {
    return await fetch(`/api/assets?parent=${parentId}`).then(r => r.json());
  },

  onError: (op, err, ctx) => toast.error(`${op} failed: ${(err as Error).message}`),

  getFileMeta: (asset) =>
    asset.payload?.mimeType === 'application/pdf'
      ? { editor: 'pdf' }
      : null,
});
```

That's the entire seam. Hand `store` to `useFileExplorer({store})` and the UX is identical to the in-memory demo — lazy / sort / conflict behaviors are all driven from the composable + store config.

## Reacting to out-of-band updates

For backends with server push (WebSocket / SignalR / SSE) or multi-tab consistency requirements, you have two patterns. Pick whichever fits your store's data flow.

### Pattern A — call `api.refresh()` on the signal

The pragmatic default. Subscribe to your push channel in the consumer; call `api.refresh()` to re-pull the tree (or `api.refresh(folderId)` for one branch in lazy mode). Open tabs + selection + expansion state survive — only the underlying asset list re-loads.

```ts
import { onMounted, onUnmounted } from 'vue';
import { useFileExplorer } from '@cocoar/vue-file-explorer-core';

const fe = useFileExplorer({ store: myHttpStore });

let unsub: (() => void) | undefined;
onMounted(() => {
  unsub = signalrClient.on('assets-changed', (msg) => {
    if (msg.folderId) void fe.refresh(msg.folderId);
    else void fe.refresh();
  });
});
onUnmounted(() => unsub?.());
```

### Pattern B — surface a reactive `_assets` ref directly

When your store is already backed by a reactive source (a Pinia store fed by SignalR, an `IndexedDB` query reactive ref, a derived `computed`), expose it as `_assets: Ref<Asset<T>[]>` on the store object. The composable picks it up and skips its internal projection entirely — every upstream mutation reflects in the tree on the next tick, no `refresh()` call required.

```ts
import { computed, type Ref } from 'vue';
import {
  type Asset,
  type AssetStore,
  useFileExplorer,
} from '@cocoar/vue-file-explorer-core';
import { useKnowledgeAssetStore } from '@/composables/useKnowledgeAssetStore';

interface MyAsset { mimeType: string }

function createReactiveHttpStore(): AssetStore<MyAsset> & { _assets: Ref<Asset<MyAsset>[]> } {
  const pinia = useKnowledgeAssetStore();

  return {
    // Reactive escape hatch — composable reads from here, no `loadTree()` ever.
    _assets: computed(() => pinia.assets) as unknown as Ref<Asset<MyAsset>[]>,

    // `loadTree` is still required by the type; it can be a no-op or
    // trigger an initial pinia.refresh() if the consumer hasn't already.
    async loadTree() {
      await pinia.refreshIfStale();
      return pinia.assets;
    },

    async loadContent(id) { return await pinia.loadContent(id); },
    async createFolder(parentId, name) { return await pinia.createFolder(parentId, name); },
    async createFile(parentId, name) { return await pinia.createFile(parentId, name); },
    async uploadFile(parentId, file) { return await pinia.uploadFile(parentId, file); },
    async save(id, content) { await pinia.save(id, content); },
    async rename(id, newName) { await pinia.rename(id, newName); },
    async delete(id) { await pinia.delete(id); },
    async move(id, parentId, position) { await pinia.move(id, parentId, position); },
  };
}

const fe = useFileExplorer({ store: createReactiveHttpStore() });
```

::: info When to pick which pattern
**A** is the right default — works with any `AssetStore<T>`, no extra machinery. Reach for **B** when you're already pushing reactivity through the layers (Pinia / live-query stores) and want zero round-trips between push and tree update. `_assets` is also how [`createInMemoryAssetStore`](./in-memory-store) opts into instant reactivity for its mutations — same mechanism, different motivation.
:::

---

---
url: /components/file-explorer/in-memory-store.md
---
# In-memory store

`createInMemoryAssetStore()` is the reference [`AssetStore<T>`](./asset-store) implementation. It's a browser-only, fully-reactive backend backed by a `ref<Asset<T>[]>` plus an `id → content` map. Reach for it for:

* demos + documentation pages
* unit / E2E tests that need a deterministic backend
* prototyping a consumer shell before the real HTTP backend exists
* **exercising your UX under degraded conditions** — the latency / failure / lazy / conflict knobs are reactive, so a toolbar can dial them at runtime

```ts
import { createInMemoryAssetStore } from '@cocoar/vue-file-explorer-core';
```

## Quick start

```ts
const store = createInMemoryAssetStore({
  initialTree: [
    { id: 's', name: 'src', kind: 'folder', parentId: null },
    { id: 'u', name: 'utils.ts', kind: 'file', parentId: 's' },
  ],
  initialContent: { u: 'export const clamp = ...' },
});
```

That's all you need for a working in-memory file system. Hand `store` to [`useFileExplorer({store})`](./use-file-explorer) and the explorer is fully functional — every CRUD op mutates the underlying ref, content is read out of the map.

## Options

```ts
interface InMemoryAssetStoreOptions<T = unknown> {
  initialTree?: readonly Asset<T>[];
  initialContent?: Readonly<Record<string, string | Blob>>;
  latencyMs?: MaybeRefOrGetter<number>;
  failureRate?: MaybeRefOrGetter<number>;
  idFactory?: () => string;
  onConflict?: MaybeRefOrGetter<ConflictPolicy<T>>;
  lazy?: boolean;
}
```

### `initialTree` · `initialContent`

Seed data. `initialTree` is a flat list of `Asset<T>` with `parentId` links; `initialContent` is an `{ [id]: string | Blob }` map keyed by asset id. Both default empty.

### `latencyMs`

Artificial delay (ms) added to every operation. **Reactive** — pass a `Ref<number>` or getter and the simulator picks up changes per call:

```ts
const latency = ref(0);
const store = createInMemoryAssetStore({ latencyMs: latency });
// later: latency.value = 1000  → every subsequent op waits 1s
```

Use it to make loading states visible during development. `loadTree` latency exposes the global `loading` ref; `loadContent` latency exposes the per-tab placeholder + spinner overlay; `loadChildren` latency exposes the row-icon spinner on lazy expand.

Default `0`.

### `failureRate`

Probability (0..1) that any operation rejects with `[InMemoryAssetStore] simulated failure in {op}`. Reactive, like `latencyMs`. Use it to exercise the `onError` path — toast styling, rollback correctness, retry UX.

Default `0`.

::: tip Combine latency + failure
The most useful simulator config is `latencyMs: 800, failureRate: 0.15`. Long enough to see every spinner; failures often enough to verify rollback without making the demo unusable.
:::

### `idFactory`

Override the id generator. Default `crypto.randomUUID()`. Pass a counter for stable ids in tests:

```ts
let n = 0;
const store = createInMemoryAssetStore({ idFactory: () => `asset-${++n}` });
```

### `onConflict`

Conflict policy applied to `createFolder` / `createFile` / `uploadFile` on sibling-name collision. **Reactive** — flip live from a toolbar.

```ts
type ConflictPolicy<T = unknown> =
  | 'rename'                                  // default — auto-suffix
  | 'overwrite'                               // delete existing, then create
  | 'prompt'                                  // window.prompt for a new name
  | 'error'                                   // always throw
  | ((info: ConflictInfo<T>) => ConflictResolution | Promise<ConflictResolution>);
```

`move` and `rename` deliberately bypass the policy — those are explicit user intent. See [conflict policy](./asset-store#conflict-policy) for the full semantics.

Default `'rename'`.

### `lazy`

Opt into lazy mode. When `true`:

* `loadTree()` returns **only root-level** entries (still enriched with `hasChildren: boolean`).
* `loadChildren(parentId)` is exposed on the store. The composable detects the method and switches to lazy behavior automatically.
* The store's published-asset projection is gated by a `_publishedIds` Set — only loaded subtrees are visible to the composable. The complete dataset still lives in the store's internal bookkeeping for move / delete / cycle-guard.

Default `false`.

```ts
const store = createInMemoryAssetStore({
  initialTree: bigSeed,
  lazy: true,
  latencyMs: 600,           // make the lazy spinners visible
});
```

## Inspection escape hatches

`createInMemoryAssetStore` returns an `InMemoryAssetStore<T>` (extends `AssetStore<T>`) with two extra read-only properties for tests and devtools:

```ts
interface InMemoryAssetStore<T = unknown> extends AssetStore<T> {
  readonly _assets: Ref<Asset<T>[]> | ComputedRef<Asset<T>[]>;
  readonly _contents: Map<string, string | Blob>;
}
```

| Property | Notes |
|---|---|
| `_assets` | Reactive projection. Eager: equals the full data set. Lazy: equals only the published subset. The composable reads from this for its tree projection. |
| `_contents` | Raw `id → content` map. Mutate at your own risk — bypasses the async API and ignores subscribers. Useful for test setup / snapshots. |

The underscore prefix marks them as non-portable. A real backend's store won't have these — write your tests against `useFileExplorer`'s public refs (`assets`, `openTabs`, etc.) if you want them to transfer to production code.

## Runtime simulator pattern

The four reactive knobs (`latencyMs`, `failureRate`, `onConflict`, plus `sortMode` on the composable) are designed to be wired to UI controls. The pattern looks like this:

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { CoarSelect, CoarSegmentedControl } from '@cocoar/vue-ui';
import {
  createInMemoryAssetStore,
  useFileExplorer,
  type ConflictPolicy,
  type SortMode,
} from '@cocoar/vue-file-explorer-core';

const latency = ref<number>(0);
const failure = ref<number>(0);
const conflict = ref<ConflictPolicy>('rename');
const sortMode = ref<SortMode>('folders-first');

const store = createInMemoryAssetStore({
  initialTree,
  initialContent,
  latencyMs: latency,
  failureRate: failure,
  onConflict: conflict,
});

const fe = useFileExplorer({ store, sortMode });
</script>
```

Every knob flips live — no store recreation, no state loss. The playground POC's simulator panel persists each setting to `localStorage` so a refresh keeps the configured scenario; `lazy` is the only construction-time switch (changing it requires recreating the store, so the POC persists the flag and reloads the page).

## Why ship a reference impl

The composable's contract is non-trivial — placeholder-then-fill open, optimistic rollback, conflict pipeline, blob-URL leases, lazy capability probing. Shipping a fully-working in-memory implementation makes the contract concrete:

* documentation pages get **real, interactive demos** without a backend
* consumers can study `create-asset-store.ts` to see exactly what their HTTP store needs to do
* tests run against the same code paths the demo does — no mock divergence

When the in-memory store and a real HTTP backend behave identically from the composable's perspective, you know the `AssetStore<T>` seam is doing its job.

---

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