---
url: /guide/getting-started.md
description: >-
  Set up @cocoar/vue-ui in a Vue 3 project: install, import fonts and styles,
  use components, toggle dark mode, and register the overlay plugin.
---

# 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
description: >-
  Error handling patterns in Cocoar UI: graceful fallbacks, overlay Promise
  rejections, error toasts, and handling failures in application code.
---

# 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
description: >-
  Theme Cocoar with CSS custom properties: set five oklch base colors and all
  shade scales for light and dark mode recalculate automatically.
---

# 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/migration.md
description: >-
  Migration guide for Cocoar UI 2.11: date/time pickers move onto CoarFormField,
  the clear button becomes opt-in, and two CSS tokens are renamed.
---

# Migrating to 2.11

The 2.11 release unifies the whole input family onto one internal shell
(`CoarInputFrame`) and a single field-padding token. **Visually almost nothing
changes** — padding and sizing values were preserved — and the public props and
slots of the text / number / password / select family are unchanged.

For most apps the migration is **one search-and-replace or nothing at all**. The
checklist below is ordered by how likely it is to affect you.

## TL;DR

| If you… | …then you need to |
| --- | --- |
| Use the **date / time pickers** with a `label`, `hint`, or `error="message"` | Wrap them in [`CoarFormField`](/components/form-field) (see below) — a consistency fix that brings them in line with every other input. **The only real code change.** |
| Rely on the **auto clear ✕** on text / number / password / date inputs | Add the `clearable` prop where you want it. |
| **Override `--coar-input-padding-x`** in your own CSS | Rename it to `--coar-field-padding-x`. |
| **Use `--coar-spacing-2xs` / `-xxl` / `-xxxl`** in your own CSS | Switch `2xs → xxs`; pick another step for `xxl` / `xxxl`. |
| None of the above | **Nothing — you're done.** |

***

## 1. Date & time pickers move onto `CoarFormField`

This is really a **consistency fix**, not a feature removal. The date/time
pickers were the only inputs that rendered their *own* label and below-field
message instead of delegating to [`CoarFormField`](/components/form-field) like
every other field — an oversight from when they were first built. They now follow
the same pattern as the rest of the family, which also **fixes** a latent bug
where a `CoarFormField`-wrapped picker didn't pick up the error border.

Concretely: `CoarPlainDatePicker`, `CoarPlainDateTimePicker` and
`CoarZonedDateTimePicker` no longer render their own label, required asterisk, or
below-field hint/error message, and they no longer take `label` / `hint` props.
Their `error` prop is now a **`boolean`** (it flips the red border + `aria-invalid`),
matching `CoarTextInput` and the rest of the field family.

Wrap them in [`CoarFormField`](/components/form-field) — exactly like every other
input — to get the label, the required `*`, validation messages and the inline
status icon.

**Before:**

```vue
<CoarPlainDatePicker
  v-model="date"
  label="Start date"
  hint="When the project kicks off"
  :error="errorMessage"
  required
/>
```

**After:**

```vue
<CoarFormField
  label="Start date"
  hint="When the project kicks off"
  :error="errorMessage"
  required
>
  <CoarPlainDatePicker v-model="date" :error="!!errorMessage" />
</CoarFormField>
```

Notes:

* `error` on the **picker** is now a boolean — pass `!!errorMessage` (or any
  boolean). The human-readable message lives on `CoarFormField`.
* New `id` prop on each picker (explicit input id; otherwise taken from the
  wrapping `CoarFormField`, otherwise auto-generated) for parity with the other
  inputs.

## 2. `clearable` is now opt-in (defaults to `false`)

`CoarTextInput`, `CoarPasswordInput`, `CoarNumberInput` and the three date/time
pickers previously defaulted `clearable` to `true`. They now default to `false`,
in line with the library rule that **every boolean prop defaults `false`** (and
matching `CoarSelect` / `CoarMultiSelect`, which were already `false`).

Nothing errors — the inline clear ✕ simply no longer appears unless you ask for it.

**Before** (✕ shown automatically):

```vue
<CoarTextInput v-model="name" />
```

**After** (add `clearable` where you want the ✕):

```vue
<CoarTextInput v-model="name" clearable />
```

`@cocoar/vue-data-grid` is unaffected — its cell editors already pass `clearable`
explicitly.

## 3. Renamed / removed CSS tokens

These only affect you if you **override Cocoar design tokens** in your own
stylesheet. If you consume the components as-is, skip this section.

### Renamed

| Old | New |
| --- | --- |
| `--coar-input-padding-x` | `--coar-field-padding-x` |

`--coar-field-padding-x` (`12px`) is the single source of truth for form-field
horizontal padding. It is intentionally **off** the spacing scale and decoupled
from it, so tuning `--coar-spacing-*` no longer moves field padding. Each control
size scales it by `--coar-component-{xs,s,m,l}-scale`.

### Removed

| Removed | Use instead |
| --- | --- |
| `--coar-spacing-2xs` (was a duplicate of `xxs`, both `2px`) | `--coar-spacing-xxs` |
| `--coar-spacing-xxl` (`48px`, unused in the library) | a remaining step, e.g. `--coar-spacing-xl` (`32px`) |
| `--coar-spacing-xxxl` (`64px`, unused in the library) | a remaining step |

The spacing scale is now: `3xs 1 · xxs 2 · xs 4 · s 8 · m 16 · l 24 · xl 32`.

***

## What did **not** change

* **Public props & slots** of `CoarTextInput`, `CoarPasswordInput`,
  `CoarNumberInput`, `CoarSelect`, `CoarMultiSelect`, `CoarTagSelect` — including
  the `prefix` / `suffix` / `leading` / `trailing` slots. The move onto the
  internal `CoarInputFrame` shell is invisible to consumers.
* **Visual output** — padding, radius and sizing values were preserved. Fields
  may differ by a sub-pixel at most; nothing reflows.
* **Toggle, listbox and segmented controls** — `CoarCheckbox`, `CoarSwitch`,
  `CoarRadioGroup`, `CoarListbox`, `CoarDualListbox`, `CoarSegmentedControl` got
  token-consistency polish only, no API change. (`CoarSwitch` and
  `CoarRadioGroup` additionally **gain** an `xs` size — additive.)

---

---
url: /guide/migration-page-builder-3.md
description: >-
  Migration guide for @cocoar/vue-page-builder 3.0: four PageConfig concepts
  removed, several names disambiguated, and documents migrated to schemaVersion
  6.
---

# Migrating Page Builder to 3.0

This release is confined to `@cocoar/vue-page-builder`. Every other package is
untouched.

::: warning The package is back under Preview
Page Builder shipped as GA in 2.17. That was an oversight — the authoring model
is still moving, as this release shows. From 3.0 it carries the **Preview**
badge again: expect the public API, `PageConfig` and the document schema to keep
changing in minor releases, and pin a version if you depend on them. Documents
stay safe either way — every schema change ships a migration that runs on
ingest.
:::

It removes four `PageConfig` concepts and renames several more. The removals all
answer the same question — *who does this protect, from whom?* — and the renames
all fix one word covering two things. The reasoning behind each is on the
[Authoring contract](/components/page-builder/authoring-contract) page.

**Your documents migrate themselves.** One document field changed
(`repeat.props.source`), and it is renamed on ingest like every earlier schema
migration. Nothing to do by hand.

## TL;DR

| If your `PageConfig` sets… | …then |
| --- | --- |
| `fields` | Rename to **`dataContract`**. |
| `elements` | Rename to **`elementTypes`**. |
| `availableStates` | Remove. Pass the state through `runtimeContext` and declare the field's `allowedValues` — see [§3](#_3-view-state-becomes-ordinary-context). |
| `previewFixtures` | Remove. Bind your own sample to `previewContext` — see [§4](#_4-preview-fixtures-become-host-chrome). |
| `stylePresets` | Remove. Styling is `NodeStyle`, `CoarTheme` and `visual-markup` — see [§1](#_1-style-presets-are-gone). |
| `requiredNodes` | Remove. Enforce it in your publication endpoint — see [§2](#_2-required-nodes-are-gone). |
| None of these | Check the [rename table](#_6-renamed-api) — you may still import a renamed symbol. |

***

## 1. Style presets are gone

Removed: `config.stylePresets`, `node.stylePreset`, the `PageStylePreset` type,
`findStylePreset()` and `isSafeStylePreset()`.

They let a host register named CSS classes for the author to pick by id. The
justification was that a page author must not put CSS into a page they do not
own — but a page author *does* own the realm their page renders in, so the
restriction protected nobody. The feature was also never finished: the Editor
canvas never applied the class, so picking a preset changed nothing until you
switched to the Preview tab.

**What to use instead.** Styling has three channels and always did:

| Want | Use |
| --- | --- |
| Per-node appearance | `NodeStyle` — surface, typography, layout, box |
| Brand colours, radii, fonts | `CoarTheme` via `CoarThemeScope` / `previewTheme` |
| Free-form decoration | The `visual-markup` element (sealed iframe, free CSS) |

A leftover `stylePreset` key in a stored document is **reported as an authoring
warning, never stripped**. The renderer ignores it and emits no class from it.

## 2. Required nodes are gone

Removed: `config.requiredNodes` (with `lockVisibility`, `lockStyle`, `parentId`
and `maxIndex`).

It pinned a node as present, placed and visually untouchable. Besides the
ownership argument above, it did not work: a node carrying both locks still
disappeared when the container **above** it was hidden, and
`validatePageDocument()` reported the document as valid.

**What to use instead.** Enforce it where activation happens. Your publish
endpoint already validates the document before a revision goes live; a check
there cannot be bypassed from the browser, which was never true of the config
flag.

```ts
// in the publish endpoint, on the document about to become active
if (!containsVisibleNode(document, 'legal-notice')) {
  return reject('The legal notice must stay on the page.');
}
```

The builder no longer withholds delete, move or the drag grip from any node.

## 3. View state becomes ordinary context

Removed: `config.availableStates`, `<CoarPageRenderer>`'s `viewState` prop,
`<CoarPageBuilder>`'s `previewState` prop, `visibleWhen.source: 'state'`, and
`page.viewState` in the code scope.

The host's "which screen is this right now" was a second mechanism for something
`runtimeContext` already carried. Note that **Page State is untouched**:
`definePageState`, `page.state` and `source: 'state'` *bindings* all keep working
— they mean the page author's own shared data, and losing the name collision is
part of the point.

**Before**

```ts
const config: PageConfig = {
  availableStates: [{ id: 'prompt', label: 'Prompt' }, { id: 'expired', label: 'Expired' }],
};
```

```vue
<CoarPageRenderer :schema :config :view-state="viewState" />
```

**After**

```ts
const config: PageConfig = {
  contextFields: [
    { path: 'runtime.viewState', type: 'string', allowedValues: ['prompt', 'expired'] },
  ],
};
```

```vue
<CoarPageRenderer :schema :config :runtime-context="{ runtime: { viewState } }" />
```

`allowedValues` is new: a context field that declares it gets a **dropdown** in
the condition editor instead of a free-text box — which is what
`availableStates` used to provide, now available to every enumerable field.

Documents using `visibleWhen: { source: 'state', … }` must move to
`{ source: 'context', path: 'runtime.viewState', operator: 'equals', value: … }`,
or express the condition in Element Code.

## 4. Preview fixtures become host chrome

Removed: `config.previewFixtures` and the `PagePreviewFixture` type.

A fixture was a named bundle of `{ context, state, locale, viewport }` plus a
dropdown in the builder toolbar — but the host already owns `previewContext` and
`previewLocale`. The only thing the config added was the builder drawing the
picker, and the host is the one who knows what "empty" or "50 items" means for
its own data.

```vue
<!-- your own picker, bound to the props you already pass -->
<select v-model="sample">…</select>
<CoarPageBuilder v-model="schema" :config :preview-context="samples[sample]" :preview-locale="locale" />
```

The preview now runs when the host supplies the inputs its own `config`
declares (`contextFields`, `locales`), and otherwise says so rather than
rendering against invented data.

## 5. Auth presets are gone

Removed: `createAuthPageConfig()` and `createAuthPageDocument()`.

The package ships nothing auth-specific. An IDP owns its own `PageConfig` and
starting documents; `apps/playground/src/views/auth-customization/` in this
repository is a worked example of all four slots.

## 6. Renamed API

Mechanical, and a search-and-replace covers all of them.

| Before | After |
| --- | --- |
| `config.fields` | `config.dataContract` |
| `config.elements` | `config.elementTypes` |
| `PAGE_ELEMENTS_KEY` | `PAGE_ELEMENT_TYPES_KEY` |
| `useSchemaValidation()` | `useAuthoringFindings()` — returns `{ findings, byNodeId }`, not `{ issues, … }` |
| `ValidationIssue` | `AuthoringFinding` |
| `IssueSeverity` | `FindingSeverity` |
| `@validation` event | `@findings` |
| `PageVisualFont.source` | `PageVisualFont.src` |
| `repeat.props.source` | `repeat.props.contextPath` *(auto-migrated)* |

Each pair existed because one word covered two things: `fields` was both the DTO
contract and the live values, `elements` was both the type registry and this
page's nodes, `validation` covered field rules, the activation contract **and**
the builder's authoring hints, and `source` was an enum, a context path and a
data URL at once. `binding.source` keeps the name — it is the dominant meaning.

## 7. Documents move to `schemaVersion: 6`

The only document change is the repeat rename, applied by
`migrateRepeatContextPath` on the same ingest path as every earlier migration —
identity-preserving, idempotent, and skipped when the new key is already there.
It runs on `v-model` assignment, on the initial value and on the JSON tab's
Apply, so a stored v5 document opens and renders unchanged.

Persist the version as-is; a document saved by 3.0 comes back stamped `6`.

## Also worth knowing

Not breaking, but new in the same release:

* **`@findings`** mirrors the builder's authoring findings to the host, so a
  save button can grey out on errors. `useAuthoringFindings()` is exported for
  the same check outside a mounted builder.
* **`previewInitialValues`** starts the embedded preview from host values,
  merged over the authored `defaultValue`s — the edit-form case, and the case
  where a default is computed per tenant.
* **The page is exactly its host container.** Size values on the page root are
  dropped and the root offers no size fields; the container owns the box. Its
  contract is that the container must have a determinable height — for `body`,
  `html, body { height: 100% }`. A document that set a root size is told so.
* **Quick Properties resolve per breakpoint.** They showed the base value while
  the canvas rendered the resolved one; an inherited value now also names the
  override it came from.

---

---
url: /guide/changelog.md
description: >-
  Full version history of the Cocoar Design System packages, listing added
  features, changes, and fixes for each release.
---

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

***

## 3.0.0

**Page Builder: a complete authoring platform, fewer concepts, unambiguous names
— and back under Preview.** A major confined to `@cocoar/vue-page-builder` and
its immediate neighbours. Nothing has been published since 2.19, so this release
carries both the customer-authoring platform (isolated scripting, runtime
bindings, reusable compositions) and the consolidation that followed it: four
`PageConfig` concepts removed because they restricted a page author inside a
realm they own or duplicated something the host already passed, plus several
names disambiguated where one word covered two things.

The package shipped as GA in 2.17 by oversight; it now carries the Preview badge
until the authoring model settles, so expect the public API, `PageConfig` and the
document schema to keep moving in minor releases. Documents stay safe: every
schema change ships a migration that runs on ingest. See
[Migrating Page Builder to 3.0](https://docs.cocoar.dev/cocoar-ui-vue/guide/migration-page-builder-3).

### Added

* **`@cocoar/vue-page-builder` — isolated browser scripting.** Page State, Page Root Code, per-element compute/action code and async host calls run in one SES-hardened Web Worker session per rendered page. Tenant code has no ambient DOM, `window`, `fetch` or filesystem access; a host exposes explicit, structured-clone-safe capability facades with `definePageRuntimeHost()` and grants them per page and runtime definition. Reactive dependency tracking recalculates only definitions affected by changed fields, state, repeater context, viewport or host resources. Constrained Monaco templates keep function signatures and element identity locked while exposing element-specific IntelliSense.
* **`@cocoar/vue-page-builder` — generic runtime bindings and authored state.** Supported properties, action arguments and visibility rules can read allow-listed host context, Page State, named form fields/selections, repeater item/index or sandbox expressions. The page owns its initial mutable state; element code may use ordinary local variables without persisting them. The code path computes immutable property snapshots before applying the final result, so repeated assignments do not cause repeated DOM writes.
* **`@cocoar/vue-page-builder` — reusable, versioned compositions.** `PageCompositionRepository` is the host-owned persistence boundary for immutable subtree definitions. Repository summaries appear in a searchable **Compositions** library and can be dragged through the normal Tree/Canvas drop pipeline. Instances materialize as ordinary nodes, pin an exact version, support explicit version changes, update-to-latest, detach and host navigation through `open-composition`, and retain nested origin chains. `compilePageCompositions()` strips authoring metadata, so runtime documents need neither a repository nor a wrapper element. Separate Pages/Compositions applications use `composition-management="consume"`; compact tools may use inline definition management.
* **`@cocoar/vue-page-builder` — general action arguments.** Every action-capable registry element shares optional `actionValues`, `actionValueField` and `actionValue` properties. JSON-safe static values and per-key dynamic bindings reach the handler with deterministic precedence: form values, then `actionValues`, then the legacy dynamic `actionValue`. Buttons, links and consumer elements therefore use one action contract.
* **`@cocoar/vue-page-builder` — repeaters, selections and feedback zones.** The generic `repeat` element renders an allow-listed host array, exposes current item/index to descendants and can publish selected-key arrays under a configured name. The generic `feedback` element places form errors, status, loading or authored messages inside the visual layout. These primitives replace proprietary Auth provider/scope elements.
* **`@cocoar/vue-page-builder` — sandboxed visual markup.** The optional `visual-markup` element renders a bounded declarative document with host-owned values, font registrations and navigation/action policy; arbitrary HTML, DOM scripts and page-global CSS are not accepted.
* **`@cocoar/vue-page-builder` — responsive styling, translations and application theming.** Documents author mobile-first styles plus Phone, Tablet and Desktop overrides, safe modern viewport units (including `dvh`, `svh` and `lvh`), breakpoint visibility and centralized key-based translations. `CoarThemeScope` and the Builder's `previewTheme` apply the resolved application brand to runtime and canvas without restyling the administration chrome.
* **`@findings` event and exported `useAuthoringFindings()`.** The builder's authoring findings reach the host, so a save button can grey out on errors or a host can render its own issue list. Outside a mounted builder, the composable answers the same question.
* **`previewInitialValues`.** The embedded preview starts from host values, merged over the authored `defaultValue`s exactly as at runtime — the edit-form case, and the case where a default is computed per tenant.
* **`PageContextField.allowedValues`.** A context field with a closed value set is authored with a dropdown in the condition editor, which is what makes a host state, tier or status authorable without a second mechanism for it.
* **Authoring contract documentation.** Every field of the node grammar, the surface that writes it, every named exception with its cost, and the open gaps.

### Changed

* **`@cocoar/vue-page-builder` — editor layout and authoring flow.** Outline and compact Properties now share the resizable left inspector, the Canvas stays central, and a searchable, independently collapsible element library sits on the right. Contract **Fields** appear first, followed by Containers, Elements and Compositions. Common properties remain quick controls; Page/Element Code is the authoritative escape hatch for the complete registered property surface.
* **`@cocoar/vue-page-builder` — localization uses stable keys.** Localizable element properties reference a page translation catalogue edited in one Translations tab. Legacy embedded localized objects remain readable, while the properties inspector no longer displays them as `[object Object]`.
* **`@cocoar/vue-script-editor` — constrained authoring is visually quieter and more usable.** Locked scaffolding markers can be hidden, protected lines are deemphasized without a dominant background, editor sizing is stable, and PageBuilder code dialogs use a wide viewport-relative layout.
* **`@cocoar/vue-ui` — scoped application themes.** New `CoarThemeScope` applies typed theme primitives and light/dark/auto mode to a subtree, enabling an embedded preview and the production page to share the same brand contract.
* **`config.fields` → `config.dataContract`.** `fields` named both the DTO contract and the live values (`page.fields`). The contract takes the new name; the values keep the one that reads correctly in code.
* **`config.elements` → `config.elementTypes`, `PAGE_ELEMENTS_KEY` → `PAGE_ELEMENT_TYPES_KEY`.** The registry says which element *kinds* exist; `page.elements` is this page's nodes.
* **`useSchemaValidation()` → `useAuthoringFindings()`** (returning `{ findings, byNodeId }`), **`ValidationIssue` → `AuthoringFinding`**, **`IssueSeverity` → `FindingSeverity`**, **`@validation` → `@findings`**. "Validation" covered a node's field rules, the activation contract and the builder's authoring hints; the first two keep the word.
* **`repeat.props.source` → `props.contextPath`** and **`PageVisualFont.source` → `src`.** `source` was an enum, a context path and a data URL at once. `binding.source` keeps it.
* **Schema v6.** The repeat rename is applied by `migrateRepeatContextPath` on every ingest path — identity-preserving, idempotent, skipped when the new key is present. Stored documents open and render unchanged.
* **The page is exactly its host container.** Size values on the page root are dropped and the root offers no size fields; the host container owns the box and must have a determinable height. A document that set a root size is told so.
* **Quick Properties resolve per breakpoint.** They showed the base value while the canvas rendered the resolved one. An inherited value now also names the override it came from.

### Removed

* **`config.stylePresets`, `node.stylePreset`, `PageStylePreset`, `findStylePreset()`, `isSafeStylePreset()`.** Host-registered CSS classes the author picked by id. A page author owns the realm their page renders in, so the restriction protected nobody — and the Editor canvas never applied the class, so picking a preset changed nothing until you switched to the Preview tab. Styling remains `NodeStyle`, `CoarTheme` and the `visual-markup` element. A leftover `stylePreset` key is reported as an authoring warning, never stripped.
* **`config.requiredNodes`** (with `lockVisibility`, `lockStyle`, `parentId`, `maxIndex`). Besides the same ownership argument, it did not hold: a node carrying both locks still vanished when the container above it was hidden, with `validatePageDocument()` reporting the document as valid. Guarantees of this kind belong in the publication endpoint, where they cannot be bypassed from the browser.
* **`config.availableStates`, `<CoarPageRenderer>`'s `viewState`, `<CoarPageBuilder>`'s `previewState`, `visibleWhen.source: 'state'`, `page.viewState`.** The host's view state was a second mechanism for something `runtimeContext` already carried — and `source: 'state'` meant Page State in a binding but view state in a condition. Page State (`definePageState`, `page.state`, `source: 'state'` bindings) is untouched and now unambiguous.
* **`config.previewFixtures` and `PagePreviewFixture`.** A fixture bundled `{ context, state, locale, viewport }` plus a builder-drawn dropdown, but the host already owns `previewContext` and `previewLocale`. The preview now runs when the host supplies the inputs its own config declares, and says so when it cannot.
* **`createAuthPageConfig()` and `createAuthPageDocument()`.** The package ships nothing auth-specific; an IDP owns its own config and starting documents.

### Fixed

* **`@cocoar/vue-page-builder` — packaged Worker execution in real Vite consumers.** The runtime Worker is emitted through a dedicated package subpath, remains outside Vite dependency pre-bundling where required, resolves correctly below non-root base paths and works in development optimization and production builds. Release CI now installs the packed PageBuilder and its peers into a separate Vite consumer before publishing; the packed-consumer matrix covers Linux and Windows.
* **`@cocoar/vue-page-builder` — Auth integration correctness.** Runtime actions receive current form values plus explicit arguments, validation/errors/loading render in authored locations, conditional controls react without polling every expression, modern viewport lengths survive CSS sanitization, and generic external-provider/consent collections work without consumer-only element implementations.
* **Monaco JSON diagnostics are documented at the consumer boundary.** PageBuilder uses JavaScript and JSON language services; Vite hosts must route `json` to Monaco's `JsonWorker`. Routing it to the generic editor worker caused `Missing requestHandler or method: doValidation`, `findDocumentColors` and `getFoldingRanges` messages even though the sandbox itself was healthy.
* **`@cocoar/vue-page-builder` — the page root is a border box.** "The page is exactly its host container" only held while the page had no padding of its own: `.pb-page` was content-box, so an authored padding was added to `width: 100%` and the page came out wider than the container it fills. Invisible until the host is narrow, and then a horizontal scrollbar on a login page at 320px.

***

## 2.19.0

This release brings the Vue calendar's view hierarchy and interaction model in line with the newer Cocoar iOS calendar while keeping the web package deliberately presentation-agnostic. The flat `CalendarBuilder` remains the single integration surface: applications choose their own create/edit UI, persistence and recurring-series scope flows through callbacks and occurrence provenance.

### Added

* **`@cocoar/vue-calendar` — iOS-style Year / Month / Day / Agenda hierarchy.** New public `CoarYearView`, `CoarContinuousMonthView` and `CoarMonthListView` components join the existing time-grid and agenda surfaces. The shell groups Compact, Stacked, Details and List under Month, groups One day and Multi-day under Day, and retains fixed Week and Work week views as useful web additions. The old `legacyMonth` idea is intentionally absent.
* **Continuously scrolling Month.** Month sections render only their required four to six weeks, materialize and preload adjacent months, preserve the active month while density changes, and extend in either direction without an unbounded DOM. Compact, Stacked and Details use content-aware row heights; Month List places the selected-day list below the mini calendar in narrow containers and beside it when space allows.
* **Responsive Multi-day view.** New fluent setters `dayMode('single' | 'multiDay')`, `dayColumnCount(...)` and `dayColumnMinWidth(...)` derive one to seven complete day columns from the calendar's actual container width. `api.setDayMode(...)` and `api.setMonthDensity(...)` provide the imperative counterparts.
* **Calendar presentation controls.** `monthDensity(...)` selects Compact / Stacked / Details, `shadeWeekends(...)` controls the weekend tint, event metadata can render assignee avatars, and event foreground contrast is selected from the event colour. The default view set now follows the iOS hierarchy; Timeline remains opt-in.
* **Public layout helpers.** `responsiveDayColumnCount`, `contentAwareCascadeFrames` and `eventTextColor` are exported from the core subpath for consumers building compatible custom surfaces.

### Changed

* **Create and edit stay host-owned.** `onDateClick`, `onTimeClick`, `onEventClick`, `onEventDoubleClick`, hover handlers and the native DOM anchor form the complete Fluent API integration seam. The library does not force a modal or overlay, so consumers can choose a popover, dialog, side panel or routed editor. Recurring occurrences retain series id, recurrence id and source provenance for This occurrence / This and following / Entire series persistence flows.
* **Month and time-grid overlaps follow the available content.** Same-day items no longer disappear after two entries in Details mode; every item remains reachable. Timed overlaps use content-aware cascading and width allocation, while responsive headers and view controls wrap against the calendar container instead of overflowing narrow host layouts.
* **Month-cell drops preserve timed-event intent.** Dropping a timed event onto a month date moves it by the display-date delta while retaining its local time, duration and per-endpoint source zones.

### Fixed

* **Selected-day hover contrast and shape.** Month List and Agenda keep the selected day on its accent background while hovering, so the white label remains readable. The Year view applies the same rule to its current-day marker. Month List now also derives its day-cell radius from the Cocoar button-radius token instead of using an out-of-scale hardcoded radius.
* **Continuous-month separators and today marker.** Every month begins with a consistent top separator even when the previous section has no rendered day above it, and the current-day marker is no longer clipped at the section edge.
* **Subpath declaration packaging.** The `recurrence` and `recurrence-rrule-temporal` exports now point at the declaration files Vite actually emits, so TypeScript consumers resolve both subpaths from the packed npm artifact.

## 2.18.0

### Added

* **`@cocoar/vue-ui` — `CoarNotice` for compact status messages and application banners.** The new component supports `info`, `success`, `warning`, `error`, `neutral` and `accent` variants with matching default icons, plus `placement="inline" | "banner"`. Inline notices render as compact bordered callouts; banners sit flush below an application header without making themselves sticky. Optional `label`, icon override, single-line inline `truncate`, long-form `#details` popover and right-aligned `#cta` slot cover short operational messages without turning the entire notice into a link. Banners always wrap, and actions remain independently interactive. New documentation compares `CoarNotice` with the richer, page-content-oriented `CoarNote`.
* **`@cocoar/vue-ui` — `CoarCheckboxGroup` with real collection models.** Child `CoarCheckbox value="…"` controls can now project into either an ordered `string[]` or an explicit `Record<string, boolean>` via `v-model`; `modelType` selects the empty-model shape and otherwise follows the supplied model. Array output follows checkbox registration order, object output includes every registered key with a true/false value, and external model changes update the children. The group owns `name`, orientation, size, disabled and error state, provides `role="group"` semantics, and integrates with `CoarFormField` labels and messages.
* **Semantic `subtlest` status backgrounds.** Success, error, warning and info now expose `--coar-background-semantic-*-subtlest` tokens for lightweight status surfaces in light, dark and theme-less modes. The theme editor exposes the new tokens as first-class semantic overrides.

### Changed

* **`@cocoar/vue-ui` — `CoarFormField` controls label layout consistently.** New `layout="stacked" | "inline"` and `labelPosition="before" | "after"` props support all four combinations for every child control. The label and status indicator move as one cluster, while the status popover trigger remains outside the native `<label>` so opening help never toggles a checkbox. Form-field context now exposes `labelId`; unlabeled `CoarCheckbox` and `CoarSwitch` controls adopt the field input id so an external form-field label is associated correctly.
* **Checkbox rows use compact control-native density.** Standalone and grouped checkboxes no longer reserve text-input height. Size-specific touch rows remain usable while consecutive checkboxes sit closer together; labels use natural line height and wrap with the box aligned to the first text line. `CoarCheckbox` keeps its existing standalone `label` API.

### Fixed

* **Info semantic text remains legible on subtle surfaces.** `--coar-text-semantic-info-bold` now resolves to a dark slate in light mode and a light slate in dark mode instead of white/dark inverted values that disappeared against low-emphasis info backgrounds.
* **Form-field label and status alignment.** The status icon is optically aligned with the label baseline in both stacked and inline layouts.

## 2.17.1

### Fixed

* **`@cocoar/vue-page-builder` — the palette splits Inputs from Elements, and `hideElementPicker` hides only the Inputs.** The free offering now has three groups — **Containers**, **Inputs** (value elements: text/password/number inputs, checkboxes, selects, …) and **Elements** (content and actions: headings, paragraphs, notes, buttons, links, images), split registry-derived by value-spec presence (consumer elements sort themselves). Fields-only authoring (`config.hideElementPicker`) now removes only the **Inputs** group (palette + the input entries of the outline's add-child menu) — exactly what the field contract replaces; containers and content/action elements stay, because a contract-authored form still needs layout, headings and a submit button. Empty palette/menu groups (e.g. everything excluded via `allowedElements`) are no longer rendered as bare labels. New i18n key `coar.pageBuilder.palette.inputs`.

## 2.17.0

**Page Builder goes GA — on an open element registry.** `@cocoar/vue-page-builder` sheds its Preview badge after a full readiness audit (correctness & data-safety fixes, npm packaging, touch-first pointer drag & drop, builder table-stakes, i18n, 8 new element types) **and** a pre-GA rework onto a consumer-facing **element registry**: built-ins and consumer elements now ride one contract and one unified wire format. Register a component via `config.elements` and it becomes a first-class element — palette entry, canvas preview, props panel, runtime rendering and form-value participation included. On top of the registry sits a config-level **field contract** (`config.fields`): pages usually project a DTO, so field binding becomes DTO-driven picking — compatible-field selects, a draggable Fields palette group, and one-click representation switching. A production **submit lifecycle** rounds it off: async actions with busy state and a form-level error channel, Enter-to-submit, a built-in email check, a host form API (`update:values` / `isDirty` / `reset`), conditional visibility (`visibleWhen`) and API-backed option lists (`optionsSource`). The wire format changes (schema v2, see Breaking) — pre-v2 documents are migrated transparently on every ingest path.

### Breaking

* **`@cocoar/vue-page-builder` — schema v2: element props move into a `props` bag.** The unified node grammar is `{ id, type, props: { …element fields }, style?, name?, defaultValue?, validation?, children? }` — `type` is an open registry key, everything element-specific lives in `props`, the host vocabulary (`id`, `style`, the value-model trio, `children`) stays at node level, and the `page` root carries `schemaVersion: 2`. **v1 documents keep working**: a self-detecting, idempotent migration (`migrateV1PropsBag`, exported) runs inside `normalizePageSchema` *and* on the fly in the renderer, so existing JSON loads, renders and submits identically — but anything *you* persist or generate from now on is v2, and code that reads node fields directly must switch `node.text` → `node.props.text` etc.
* **`@cocoar/vue-page-builder` — type surface follows the format.** Built-in node interfaces (`HeadingNode`, `TextInputNode`, …) are now bag-shaped aliases over the new `ElementNode<K, P>`; the `PageNode` union gains an **open** `ElementNode` member (so exhaustive `switch`es over it no longer narrow — dispatch goes through the registry), `ElementType` stays the closed built-in set, `allowedElements` accepts consumer keys (`(ElementType | string)[]`), and `FieldValidation` is uniform at node level. Inspector components patch element fields *through the bag* — `patch({ props: { … } })` merges one level deep with delete-on-empty semantics per bag key, while host fields stay node-level.
* **`@cocoar/vue-page-builder` — GA behaviour contract (changed within the Preview period).** Validating buttons are no longer disabled-until-valid: an invalid click marks all fields touched, **reveals every error**, focuses the first invalid control, and aborts the action (buttons only disable while a trigger is genuinely in flight — an async `onValidate` or an async action — as a double-submit guard). `onValidate` is genuinely async and runs at **submit time** after the declarative rules, its result mapping to per-field errors. `validation.pattern` is anchored to the documented full-string semantics and compiled crash-safe (an invalid tenant regex no longer crashes the page). Node ids are crypto UUIDs (no more session-counter ids).
* **`@cocoar/vue-page-builder` — new peer dependency `@cocoar/vue-localization`.** All builder chrome and the renderer's validation messages resolve through `t('coar.pageBuilder.*', …, englishFallback)` — English-only apps need no i18n setup, but the peer must be installed.

### Added

* **`@cocoar/vue-page-builder` — consumer-facing element registry.** `definePageElement<P>({ renderer, value?, container?, inline?, normalizeProps?, builder? })` packages everything the renderer *and* the builder need to know about one element type; built-ins are pre-registered on the same contract. Registrations merge **additively** over the built-ins via `config.elements` (per instance) or the app-wide `PAGE_ELEMENTS_KEY` provide (config wins; shadowing a built-in key warns in DEV; key grammar `^[a-z][a-z0-9-]*$`, vendor prefix recommended — `acme-rating`). One registration serves palette + add-menu (label/icon/group), canvas (a `preview` component, or a neutral icon+label chip), props panel (`inspector` receives `{ node, patch }`), authoring diagnostics (`lint`), and the runtime renderer. The **value model is registry-driven**: a definition with a `value` spec plus a `node.name` makes the element a managed field — defaults seeding (`defaultValue`), `required` gating (`isEmpty`), custom `validate` hooks (run crash-guarded after the declarative rules), and inclusion in action payloads. New public API: `definePageElement`, `usePageElement()` (the curated element runtime context: `getValue`/`setValue`/`getError`/`markTouched`/`triggerAction`/`isValidating`/`isSubmitting`/`pendingAction`/`formError`/`resolveAsset`/`config`), `mergeElementRegistries`, `PAGE_ELEMENTS_KEY`, `ELEMENT_KEY_PATTERN`, the contract types (`PageElementDefinition`, `PageElementBuilderDefinition`, `PageElementRegistry`, `ElementValueSpec`, `ElementLintIssue`, `I18nText`, `ElementNode`, `ElementProps`), and the shared `OptionsEditor` for consumer inspectors. Host-owned **Field section** in the props panel (name / required / default value, with an optional per-definition `defaultValueInput` editor) — consumer elements get the full field UX for free. `normalizePageSchema(value, { elements })` is registry-aware: registered types count as known and each definition's `normalizeProps` runs as a crash-guarded ingest-healing pass over the props bag.
* **`@cocoar/vue-page-builder` — lossless degradation for unknown element types.** A node whose `type` isn't registered is *kept*: builder validation flags it as a warning (not an error), the canvas shows a distinct blocked treatment, the JSON tab still round-trips it (Apply now rejects only on structural **errors** — `NormalizeIssue` gained `severity: 'error' | 'warning'`), and the runtime renderer skips it with a one-time warning. Unregistered valued nodes are excluded from the value model, so they can never veto submission.
* **`@cocoar/vue-page-builder` — 8 new element types**: `number-input`, `switch`, `radio-group`, `multi-select`, `otp-input` (required = complete code), `date-input` / `datetime-input` (ISO-string wire values, converted to/from Temporal at the picker boundary, crash-safe parse), and `note`; `text-input` gains `rows` (multiline textarea). Every form/content primitive of `@cocoar/vue-ui` is now a first-class element. Option-based inputs share a value/label options editor with add/remove/reorder.
* **`@cocoar/vue-page-builder` — `password-input` as a standalone element.** Masked passwords are no longer a `text-input` variant: `password-input` is its own registered element (renders a masked `CoarPasswordInput`; props `label` / `placeholder` / `disabled`; the host-enforced string rules `minLength` / `maxLength` / `pattern` apply), directly pickable in the palette and as a representation for `string` contract fields. `text-input`'s `inputType` narrows to `text | email | url` — **legacy documents keep working**: `text-input` nodes with `inputType: 'password'` migrate to `password-input` transparently on every ingest path (builder/`normalizePageSchema` persistently, the renderer on the fly), chained after the v1 props-bag migration.
* **`@cocoar/vue-page-builder` — field contract: DTO-driven field binding.** Pages are usually projections of a DTO — the fields and their types are known up front, and authors should pick from them instead of inventing names. New `PageConfig.fields: PageFieldSpec[]` (`{ name, valueType, label?, required?, defaultElement? }`) + `allowCustomFields` (default `false`). With a contract, the props panel's **Field name** becomes a select over the fields the selected element can edit (clear = unbind; out-of-contract bindings stay visible as `(custom)`); binding carries the contract label along (never overwriting an author's label) and sets `validation.required` for contract-required fields. Compatibility is **registry-driven**: `ElementValueSpec.types: PageValueType[]` declares which value types an element can edit (open token union — `string` / `number` / `boolean` / `string[]` / `date` / `datetime` plus consumer tokens; omitted = unconstrained), so a consumer rating declaring `number` becomes a representation for number fields; its sibling `ElementValueSpec.textRules` opts string elements into the host-enforced string rules (set by `text-input` / `password-input`). The palette gains a **Fields** group — one draggable card per contract field (type icon, `*` for required, greyed once bound); dropping one creates the field's default element (`field.defaultElement`, else the first compatible value element) pre-bound. The Field section gains an **Element** select — the representation switch: the new builder op `convertTo(path, type)` swaps a node onto another element that can edit the same value type, keeping `id` (selection follows), `name`, `defaultValue`, `validation`, `style` and the label while the rest of the props bag restarts from the target's defaults (one undoable step). Contract lint: a bound name outside the contract = **error** (unless `allowCustomFields`), a type-incompatible binding = **error**, a required contract field missing from the page = **warning** on the root; under a strict contract, fresh value elements start **unbound** instead of minting a `field_*` name. The contract constrains **authoring only** — binding is plain `node.name`, persisted schemas stay self-contained and render without it. `allowedElements` governs every seam of it: field default elements and the representation switcher only ever offer **allowed** elements. New `PageConfig.hideElementPicker` (default `false`) removes the free element picker (Containers/Elements palette groups + outline add-child menu) for fields-only authoring. `convertTo` refuses conversions that would drop children, and a definition combining `container: true` with `builder.preview` DEV-warns (the canvas renders the children body, not the preview). New exports: `isFieldCompatible`, `compatibleFields`, `compatibleElementTypes`, `defaultElementForField` (all allow-list aware via their optional `config` parameter), the `PageFieldSpec` / `PageValueType` types, and `defineFields<TDto>()` — an opt-in, zero-runtime-cost typed field list for static DTOs (names must be DTO properties, value types must fit the property types); it returns a plain `PageFieldSpec[]`, so dynamically extended DTOs keep using the array directly or mix both.
* **`@cocoar/vue-page-builder` — touch-first pointer drag & drop.** Native HTML5 DnD (which never fires from touch on Android tablets) is replaced by a pointer-events engine: 5 px movement threshold for mouse, 300 ms long-press for touch/pen (early movement = scroll intent), ghost clone, nearest-zone hit-testing, edge auto-scroll, Escape/pointercancel abort. The outline's drag grip actually reorders now (drop bars between rows + drop-*into* highlighting on containers) — it was a false affordance before.
* **`@cocoar/vue-page-builder` — builder table-stakes.** Duplicate (deep copy with fresh ids, in outline row actions and canvas chrome), default-value editors, outline keyboard/ARIA (`role="tree"`, roving tabindex, Arrow/Home/End, Enter/Space), and **scoped shortcuts**: the undo/redo/delete listener acts only while focus is inside *this* builder instance and never inside editable targets — native text undo works again in the JSON textarea and host-app inputs.
* **`@cocoar/vue-page-builder` — `<CoarPageRenderer>` `initialValues` prop.** Host-supplied values (edit-form prefill) merged over the schema defaults, filtered to named inputs in the allowed tree. Replacing the object with **different values** re-initializes the form; a value-identical replacement (the inline-object-literal footgun — a new reference on every parent render) is ignored, so in-progress user input survives. Compared over the keys the form actually consumes (irrelevant-key changes can't wipe input) and over **raw** values (reactive-proxy-safe, arrays by content).
* **`@cocoar/vue-page-builder` — submit lifecycle: async actions, busy state, form-level error channel.** An `ActionHandler` may return a Promise: the renderer awaits it, the triggering button spins (`pendingAction`), every other action button and link disables (`isSubmitting`), and repeated clicks are ignored — the double-submit guard now covers non-validating buttons too. Failures have a home: an action rejection surfaces its `Error.message` (the consumer's user-facing channel) in a **form-level error banner** (`CoarNote`, `role="alert"`, above the page; `#form-error` slot to replace it; `usePageElement().formError` to render it in-page), non-`Error` rejections and `onValidate` throws show a localized generic message, and the reserved **`_form` key** (`FORM_ERROR_KEY`, exported) in `onValidate` results routes there instead of to a field. The banner clears on any field edit and at the start of each trigger. Handlers and `onValidate` receive a **snapshot**, not the live reactive values object — and the action ships **the exact snapshot `onValidate` approved**, so edits made while an async validation was in flight never ship unvalidated. `onValidate` errors keyed to fields that cannot display (hidden by `visibleWhen`, renamed, never on the page) route to the banner instead of blocking the submit invisibly. A failed validating click focuses and scrolls the first invalid control into view.
* **`@cocoar/vue-page-builder` — Enter-to-submit (double opt-in).** The page root's new `enterSubmits` (checkbox in the host-owned **Page** section of the props panel) + per-element eligibility declared in the definition (`ElementValueSpec.submitOnEnter`, boolean or per-props predicate — single-line `text-input`, `password-input` and `number-input` declare it; textarea/OTP/selects, the date inputs (their picker panel uses Enter) and undeclared consumer elements never submit). A plain Enter fires the page's **default button** — the first `button` with the new `default: true` prop (checkbox in the button inspector; lint warns when several buttons claim it), else the first `validates: true` button in tree order — through the full submit pipeline. The input is blurred first so commit-on-blur controls (number input) flush the value the user sees; modified, already-consumed (`preventDefault`) and IME composition-commit Enters never submit.
* **`@cocoar/vue-page-builder` — built-in email format check.** `text-input` with `inputType: 'email'` validates against the WHATWG email pattern (full string, skips empty, localized `coar.pageBuilder.validation.email` message) — the most common format rule needs no hand-written `pattern` anymore. Rides the `textRules` opt-in, so consumer elements with an `inputType` prop participate by declaration.
* **`@cocoar/vue-page-builder` — complete action payloads.** Every value built-in declares a `value.defaultValue` factory, so **untouched named fields are present** in `ActionValues` as documented: `''` for text/password/OTP, `false` for checkbox/switch, `[]` for multi-select, `null` for number/select/radio-group/date/datetime ("nothing entered/picked").
* **`@cocoar/vue-page-builder` — host form API on `<CoarPageRenderer>`.** New `update:values` emit (snapshot copy on init, every edit and reset) plus exposed `values` / `isDirty` / `isFormValid` / `reset()` — unlocks autosave, drafts, unsaved-changes guards and host-driven resets without abusing actions as the only exit.
* **`@cocoar/vue-page-builder` — `visibleWhen`: conditional visibility as host vocabulary.** Any node can declare `visibleWhen: { field, equals | in }` against the live value model (arrays compare by content; malformed conditions fail open). The condition gates the node **and its subtree** in rendering *and* in the value model — in the same walk as `allowedElements` — so hidden `required` fields neither veto validating buttons nor ship values; payloads, `onValidate` input, `update:values` and the exposed `values` carry only the allowed and **visible** tree, while values typed before hiding are kept internally and return on re-show. A condition on the page root is ignored — a page can never blank itself. Builder: host-owned **Visibility** section (controlling-field select + `equals` editor authored in the **controller's value type** — checked/unchecked for booleans, option lists for choice inputs, numbers coerced; array-valued controllers are not offered, `in` is JSON-authorable), an eye marker on conditional canvas nodes, `convertTo` carries the condition, and lint warns on malformed conditions, unknown controlling fields and **circular chains** (self-references included — hidden controllers can't be edited, so loops could lock each other hidden).
* **`@cocoar/vue-page-builder` — hardening against tampered documents and stale context.** The renderer heals a missing/non-object `props` bag for **any** element type on the fly (a hand-written consumer-element node without a bag used to crash the whole page on its first `node.props` access). Reserved field names (`__proto__`, `constructor`, `prototype`) are excluded from the value model end to end — they neither veto nor ship, reads/writes are guarded against prototype pollution, the builder lint flags them as errors, and `onValidate` results keyed to them route to the form banner (they block visibly instead of being dropped). `usePageElement().config` is now a live getter, so a config supplied or replaced after an element mounted (late-arriving `optionsSource`, swapped allow-list) reaches it reactively. Value comparison (`isDirty`, the `initialValues` guard, `visibleWhen.equals`) is by **content** for JSON-safe values — nested objects and arrays included, reactive-proxy-safe. Fields revealed by `visibleWhen` *during* an async `onValidate` are auto-touched when the result maps errors onto them, so a blocked submit stays visible. The circular-`visibleWhen` lint models **ancestor-container** gating too (a field controlling its own ancestor card is the easiest self-lock to author), and `equals` conditions on multi-value (`string[]`) controllers get their own lint + a panel hint instead of a silently unsatisfiable condition. Enter-to-submit ignores Safari's post-`compositionend` IME commit (keyCode 229) and, while the form is busy, ignores Enter *without* blurring the focused input.
* **`@cocoar/vue-page-builder` — `optionsSource`: API-backed option lists.** New `PageConfig.optionsSource?: (sourceId) => Promise<OptionItem[]>` (the async sibling of `assetResolver`) + `optionsSourceId` prop on `select` / `multi-select` / `radio-group` (inspector text input): a set source id resolves through the callback at render time and wins over the static `options`; static stays the default and the fallback when the callback is absent (lint warns). Loading/failed lists stay empty (one warning per component), malformed entries are filtered, stale responses are discarded. The `useResolvedOptions` composable is exported so consumer elements get the same behavior.
* **`@cocoar/vue-ui` — `CoarTextInput` `type` prop** (`text | email | url | tel | search`, single-line only, additive) — so the page builder's `inputType` actually reaches the DOM (only `password` worked before).

### Fixed

* **`@cocoar/vue-page-builder` — P0 correctness & data-safety.** Dragging a node into a *later sibling* container silently deleted it (`moveNode` now rebases the target path into post-removal coordinates; selection follows). The JSON tab gates Apply through structural normalize + validate with healing instead of trusting pasted JSON. Heading levels are clamped 1–6 (a tampered level crashed rendering). The Required toggle no longer wipes the other validation rules. `allowedElements` now gates the **value model** too — a disallowed (invisible) required field could previously veto every submit. Legacy `column`/`row` schemas migrate on the fly in the renderer, and `normalizePageSchema` / `migrateLegacyTypes` / `KNOWN_ELEMENT_TYPES` are exported from the package root. The renderer's `assetResolver` falls back to `config.assetResolver` (the documented "same config to both" contract).
* **`@cocoar/vue-page-builder` — npm packaging.** New `./styles` subpath export — the stylesheet (all builder chrome **and** the renderer's core layout, e.g. stack flex) was emitted but unreachable from the published package, so every non-workspace consumer got a layout-broken component. The npm page also gains README + LICENSE. Import once: `import '@cocoar/vue-page-builder/styles'`.
* **`@cocoar/vue-page-builder` — library build no longer bundles `@cocoar/vue-localization` and `@js-temporal/polyfill`.** Both are external now; the bundled Temporal copy guaranteed the dual-instance `instanceof` trap at the date-picker boundary, and the bundled localization copy would have split the translation registry in two.

***

## 2.16.0

**Point events, visually honest.** A timed event without `end` (a "point event" — think *call at 14:00*) previously rendered over the +30-minute layout default in the exact same card as a real 30-minute meeting, so *call at 14:00* and *standup 14:00–14:30* were indistinguishable in Day / Week. The card now says what it knows: the start time — and nothing more.

### Added

* **`@cocoar/vue-calendar` — distinguishable rendering for point events in the time grid.** A timed event without `end` keeps its +30-minute slot geometry (layout math untouched — the card geometry of the web and SwiftUI ports stays identical) but renders with a solid start edge in the event color exactly on the start time, a semi-transparent card body (fill and leading bar mixed toward transparent; the **title stays fully opaque** — the body is tap target + label carrier, not a duration statement), and **no resize handles** (there is no `end` to grab; moving still works). The start edge is suppressed when the card is clipped at the top of the visible window, since the top edge then isn't the start time. Month and Agenda render point events unchanged — they draw no duration geometry. Two new scheme-invariant theme tokens: `--coar-calendar-point-edge-height` (default `3px`) and `--coar-calendar-point-body-opacity` (default `0.38`), value-matched to the SwiftUI port (`Cocoar.Calendar.iOS` `0eef2e0`), so web and iOS point events look alike. See the updated [Day](/components/calendar/day-view) / [Week](/components/calendar/week-view) pages.

***

## 2.15.0

**Calendar dark mode, out of the box** — plus a ghost-card layout fix. The calendar grid previously stayed white in a dark app shell because the `--coar-calendar-*` tokens only existed as hardcoded light fallbacks; the package now ships a full dark palette, value-identical to the SwiftUI port (`Cocoar.Calendar.iOS`), so web and iOS render the same dark calendar.

### Added

* **`@cocoar/vue-calendar` — dark-mode values for the grid tokens.** The package stylesheet now defines every `--coar-calendar-*` token for dark mode, activating on the `.dark-mode` class (the Cocoar convention, same as `@cocoar/vue-ui`) **or** the `[data-theme="dark"]` attribute. The values mirror the SwiftUI port's `CalendarTheme.dark` (derived from the vue-ui dark primitives): surfaces `#18181b` / weekend `#212125` / other-month `#131316`, today-tint lifted to ~14% accent (4% is invisible on dark), grid lines `#2c2c30`, borders `#3f3f46`. Two new tokens join the set — `--coar-calendar-agenda-divider` (agenda row separator, near-invisible `#27272a` in dark; falls back to `--coar-calendar-border` in light) and `--coar-calendar-event-default-bg` (fill of events without a `meta.color`: dark accent `#1e3a8a` so the light title text stays readable; falls back to `--coar-color-accent-soft`). The calendar-local text tokens `--coar-text-base` / `--coar-text-subtle` (names not defined by `@cocoar/vue-ui`) get dark values too, so labels flip with the surfaces. Event colors from `meta.color` are intentionally **not** remapped — they render raw in both modes. Light mode is byte-identical to before (light values remain per-usage fallbacks). See the updated [Theming section](/components/calendar/#theming).

### Fixed

* **`@cocoar/vue-calendar` — timed events without `end` no longer render ghost cards on following days.** `layoutDayEvents` applied the default 30-minute duration **after** projecting the start onto the day, so on any day after the event's start day the "before this day" sentinel (−1) yielded a visible 0:00–0:29 interval — a phantom card on **every** later day of the visible window in Week / Day views. The default now only applies when the start actually falls on the laid-out day; end-less events are visible on their start day only. *Heads-up for the SwiftUI port: `TimeGridLayout.swift` replicates the old behaviour fixture-true — regenerate the layout fixtures and port the fix.*

***

## 2.14.0

**Diagrams in Markdown.** A ` ```mermaid ` fenced code block now renders as a diagram, via a new pluggable fence-renderer seam, a standalone `@cocoar/vue-mermaid` renderer and the thin `@cocoar/vue-markdown-mermaid` adapter. The Markdown packages carry **zero** dependency on Mermaid — installing and registering the adapter is the opt-in, and a fence with no registered renderer stays a readable code block, so the Markdown stays portable.

### Added

* **`@cocoar/vue-markdown` — fenced-code-block renderer registry.** A new open, language-keyed `FenceRegistry` (`MARKDOWN_FENCE_RENDERERS_KEY`, `resolveFenceRenderer`) lets a consumer render a specific fence language (e.g. `mermaid`) with a rich component instead of a plain code block. `<CoarMarkdown>` gains a `fenceRenderers` prop (provide/inject, like `embeds`); an unregistered language still renders as a normal, syntax-highlighted code block. Additive — existing behaviour is unchanged.
* **`@cocoar/vue-mermaid` — new standalone diagram component.** `<CoarMermaidDiagram :code>` renders a Mermaid diagram from a source string — **markdown-agnostic**, usable anywhere. Lazy-loaded Mermaid (its own chunk), client-only, `securityLevel: 'strict'` (author diagram text is sanitized), waits for `document.fonts.ready` (so labels aren't clipped by pre-font-load measurements), and an error-with-source fallback for invalid diagrams. **Cocoar-themed** — design tokens map onto Mermaid's `themeVariables`, colors normalized to sRGB. **Zoom & pan** (`zoomable`): fixed-height viewport with +/−/⤢ controls, Ctrl/⌘+wheel zoom, drag-to-pan and double-click reset — plain wheel and one-finger touch still scroll the page, so a diagram never traps scrolling. Import styles via `@cocoar/vue-mermaid/styles`.
* **`@cocoar/vue-markdown-mermaid` — new opt-in fence adapter.** Registers `@cocoar/vue-mermaid` as the `mermaid` fence renderer for `@cocoar/vue-markdown`. Ships `mermaidFenceRenderers` (ready-to-spread) and `createMermaidFenceRenderers({ zoomable })`.

### Fixed

* **`@cocoar/vue-map` — the package now exposes its stylesheet.** `@cocoar/vue-map/styles` (`./styles` export) ships the ~5 KB of `.coar-map*` component styles (pins, legend, layout). Previously there was no way to import them from the published package, and they are **not** part of `@cocoar/vue-ui`'s stylesheet — so a consumer using the built package got an unstyled map. Leaflet's own CSS is still loaded lazily by the component.

***

## 2.13.0

Optional-time date pickers: a small **clock toggle beside the field** lets one input be *either* a plain date *or* a date with time — no more separate "add time" checkbox.

### Added

* **`@cocoar/vue-ui` — `<CoarZonedDateTimeOrDatePicker>` + `<CoarPlainDateTimeOrDatePicker>`.** A date picker whose time is **optional**. A clock toggle sits **beside** the field (left or right via `togglePosition`); off enters a `Temporal.PlainDate`, on enters a date with time — a `Temporal.ZonedDateTime` (zoned variant) or `Temporal.PlainDateTime` (plain variant). One `v-model` carries the union value and `v-model:withTime` is the toggle; the two stay in sync (a non-null value's own type *is* the mode), so you read the result straight off its Temporal type. Flipping the clock converts the current value rather than clearing it — adding a time keeps the date (and, zoned, attaches the `timeZone` or the user's zone); removing it drops back to the date. They're thin **compositions** over the existing `CoarPlainDatePicker` / `CoarPlainDateTimePicker` / `CoarZonedDateTimePicker` (all common props pass through: size, disabled, readonly, required, error, clearable, locale, min/max, minuteStep, and the zoned timezone props). The toggle icon switches between a clock and a struck-through clock with a state-aware tooltip + `aria-pressed`; its roundness tracks `--coar-input-radius` so it always matches the adjacent field. See the new **[Date · optional time](/components/date-or-time-picker)** page.
* **`@cocoar/vue-ui` — new built-in `clock-off` icon** (a clock with a diagonal strike), available to the icon system like any other built-in.

***

## 2.12.0

Custom **embeds** for the markdown stack, plus a new standalone **map** package — viewer and **visual editor**. Authors write a `:::key{props}` directive and the shared stack renders a consumer-registered Vue component — read-only in the [`<CoarMarkdown>`](/components/markdown) viewer, **live and editable** in [`<CoarMarkdownEditor>`](/components/markdown-editor) — with a lossless round-trip to plain Markdown. The embedded component has **zero dependency on markdown**: it's a plain component with normal props that a consumer registers from the outside, so the markdown packages never depend on it. To place those inserts, the editor's sidebar `tools` becomes an **ordered, groupable layout**. The new `@cocoar/vue-map` ships both [`<CoarMap>`](/components/map/) (display) and [`<CoarMapEditor>`](/components/map/editor) (author points/routes via `v-model:data`), each markdown-agnostic by design. See the new **[Custom Embeds](/components/markdown-embeds)** page. Everything is opt-in behind the `cocoar` flavor.

### Added

* **`@cocoar/vue-map` — new package: standalone interactive map (`<CoarMap>`).** A data-driven Leaflet map for Vue 3 that's **completely independent of markdown** (and of any embedding layer) — it takes resolved `MapData` + `MapConfig` and knows nothing about ids, fetching, or `:::` directives. Renders category-colored stop pins, named shape-point dots and a route polyline; hover tooltips, click popups, an opt-in legend (`show-legend`, then shown when ≥ 2 categories are present), caption, and `viewport`/auto-fit. An interactive bridge lets a consumer-built list drive the map and stay in sync: `v-model:selected`, a `point-click` event, and exposed `focusPoint(index)` / `highlightPoint(index)` methods (`fallbackEntries(...)` rows carry the matching point `index`). Leaflet (JS + CSS) is imported **lazily** on mount, with a crawlable no-JS `<ol>` fallback until it hydrates. Untrusted point text is escaped (popups built from DOM text nodes). A consumer can register it as a markdown embed (`{ map: { viewer: MapEmbedWrapper } }`) where the wrapper resolves its id → `MapData` — but that wiring lives entirely in the consumer. *(Google basemaps are out of scope for now; a Google basemap is skipped in favour of the default.)*
* **`@cocoar/vue-map` — visual map editor (`<CoarMapEditor>`).** The write counterpart of `<CoarMap>`, controlled via `v-model:data` (it never mutates the prop — every edit emits a fresh `MapData`). Click an empty spot to add a point (type-aware: `route`/`multi` append a stop, `single` moves the one point), drag any marker to move it with the route polyline following **live**, click a marker to edit its `label`/`note`/`category`/`icon` and toggle `stop`↔`shape` in a popup (anchored over the marker, flips below near the top edge, closable via **×** / `Esc` / click-away, fully overridable via the **`#point-form`** slot), reorder route waypoints, delete, and **click the route line to insert a waypoint exactly there** (snapped to the nearest segment). Adding a point does **not** auto-open the popup, and clicking empty space while a point is selected **dismisses** it rather than adding — so rapid placement stays fluid and "click away to close" works as expected. `readonly` freezes editing. A consumer toolbar can drive the same edits through exposed `addPoint` / `updatePoint` / `removePoint` / `reorder` / `captureViewport` (+ `focusPoint` / `highlightPoint`) methods. The immutable, Leaflet-free editing ops (`addPointForType`, `movePoint`, `updatePoint`, `removePoint`, `reorderPoint`, `insertOnSegment`, `setViewport`, `nearestSegment`, `normalizeLatLng`) are exported too. Built on the same lazy-Leaflet, markdown-agnostic, XSS-safe foundation as `<CoarMap>`; tree-shakeable so viewer-only consumers don't pull in the editing weight. The editor's built-in property popup is rendered with the **Cocoar UI** form controls (`CoarTextInput` / `CoarSelect` / `CoarButton`); `@cocoar/vue-ui` is an **optional `peerDependency`** of `@cocoar/vue-map`, so the editor opts into the design system while viewer-only `<CoarMap>` consumers aren't required to install it. See the new **[Map Editor](/components/map/editor)** page.
* **`@cocoar/vue-map` — ready-made point list (`<CoarMapPointList>`).** A drop-anywhere companion list so apps don't rebuild it. Controlled (`v-model:data` / `v-model:selected`) and decoupled from the map — it emits `focus` / `highlight` events you wire to the map's `focusPoint` / `highlightPoint`. Opt-in `reorderable` adds **drag-and-drop sorting** (a per-row handle, built on Cocoar UI's `useDragDrop`) and `removable` adds a per-row delete; both keep the selection on the same logical point through the change. Lists every point (including unnamed `shape` vertices), with a `#row` slot to override row content. Works next to `<CoarMapEditor>` (full editing) or a read-only `<CoarMap>` (pure navigator). New exports `selectionAfterReorder` / `selectionAfterRemove` keep custom lists consistent.
* **`@cocoar/vue-markdown-core` — `:::key{props}` custom-embed directive.** A standalone directive line parses to a generic `embed` node (`{ key, props }`) and serializes back losslessly (`parse → serialize → parse` is a fixed point; canonical forms like `:::map{id=<guid>}` are byte-stable). Exposes `parseEmbedDirective`, `serializeEmbedDirective` and `toEmbedProps`. The parser is registry-agnostic — any key round-trips, registered or not. Vue-free, like the rest of the core.
* **`@cocoar/vue-markdown` — embed registry + viewer rendering.** New `embeds` prop on `<CoarMarkdown>` (and an app-wide `MARKDOWN_EMBEDS_KEY` provide) maps a directive key to a component via `EmbedRegistry` / `EmbedDefinition` (`{ viewer, editor?, insert? }`). A registered key renders through your component (props passed straight through); an unregistered key degrades to a labelled placeholder instead of vanishing. XSS-safe by construction — attribute values are bound as Vue props/text, never `innerHTML`.
* **`@cocoar/vue-markdown-editor` — live, editable embeds.** Pass the same `embeds` registry and the editor folds `:::key{props}` into an atomic block whose NodeView mounts the registered component **live**. When the entry supplies an `editor` component it's mounted editable via a single typed `controller` prop (`EmbedEditorProps` / `EmbedEditorController` — `controller.patch(...)` writes attribute changes back to the Markdown); otherwise the read-only `viewer` is shown. Gated behind a new `embeds` flavor capability (on in `cocoar`, the default).
* **`@cocoar/vue-markdown-editor` — groupable, ordered toolbar layout.** `tools` now accepts `CoarMarkdownEditorToolEntry[]`: built-in tool ids, custom-embed inserts addressed as `embed:<key>` (icon/label from the registry's `insert`), `{ flyout }` submenu groups (mixing built-in and embed items), and `'divider'`s. Array order is the toolbar order, so embeds and built-ins can be placed and grouped anywhere.

### Changed

* **`@cocoar/vue-markdown-editor` — `tools` is now an ordered layout (breaking).** A `tools` array previously acted as an order-insensitive whitelist that filtered a fixed sequence; it is now an ordered layout (array order = toolbar order). Flat built-in arrays remain valid and the default (omit `tools`) is unchanged, so apps passing tools in canonical order are unaffected — list tools in the order you want otherwise. `tools` is typed `CoarMarkdownEditorToolEntry[]` (a superset of `CoarMarkdownEditorTool[]`).
* **`@cocoar/vue-markdown-editor` — the default `cocoar` flavor now recognises `:::key{props}` embeds.** A standalone `:::word{…}` line folds to an embed node (rendered as a placeholder when its key isn't registered) instead of staying literal text. Use a stricter `flavor` (`'commonmark'` / `'gfm'`, or a capability object without `embeds`) to keep such lines as plain text.

***

## 2.11.0

A library-wide consistency pass for the input & form-control family. The whole field family — text / number / password / select / multi-select / tag-select and the three date-time pickers — now sits on one internal shell (`CoarInputFrame`), so box, border, radius, surface, states and field padding all come from a single place. The non-typing form controls (checkbox, switch, radio, listbox, dual-listbox, segmented control) are aligned to the same input + semantic-error tokens, and the Theme Editor is rebuilt around the new token model.

It is **mostly visual-neutral** — padding and sizing values were preserved. The breaking changes are narrow and concentrated: the date/time pickers move their label & validation onto `CoarFormField` (a consistency fix), `clearable` now defaults to `false`, and a few design tokens are renamed/removed. See the **[Migrating to 2.11 guide](/guide/migration)** — most apps need a one-line change or nothing at all.

Underpinning it is a spacing-scale cleanup and a dedicated field-padding token. The spacing scale had drifted: two dead steps, a duplicate, and an off-scale value (`12px`) faked with `calc(--spacing-s + --spacing-xs)` — which implicitly coupled input padding to two scale steps, so tuning `--coar-spacing-s` silently shifted every text field. A usage census (workhorses `s`/`xs` ≈ 70% of all references; `xxl`/`xxxl` unused; `2xs` a duplicate of `xxs`) drove the change.

### Removed

* **`@cocoar/vue-ui` — dead / duplicate spacing tokens (breaking).** `--coar-spacing-2xs` (a duplicate of `--coar-spacing-xxs`, both `2px`), `--coar-spacing-xxl` (`48px`) and `--coar-spacing-xxxl` (`64px`) are removed — the latter two had zero usages across the library. The scale is now `3xs 1 · xxs 2 · xs 4 · s 8 · m 16 · l 24 · xl 32`. Consumers referencing the removed tokens should switch `2xs → xxs` and pick a remaining step for `xxl`/`xxxl`.
* **`@cocoar/vue-ui` — `--coar-input-padding-x` (breaking, renamed).** Replaced by `--coar-field-padding-x` (see below).
* **`@cocoar/vue-ui` — date-picker `label` / `hint` props + own label/message rendering (breaking).** `CoarPlainDatePicker`, `CoarPlainDateTimePicker` and `CoarZonedDateTimePicker` no longer render their own label, required-asterisk or below-field error/hint message. Wrap them in [`CoarFormField`](/components/form-field) for a label, the required `*`, validation messages and the inline status icon — exactly like every other input. The pickers now `inject` the field contract (id / error / `aria-describedby`), which also **fixes** a latent bug where a `CoarFormField`-wrapped picker didn't pick up the error border. See the `error` prop change below.

### Added

* **`@cocoar/vue-ui` — `--coar-field-padding-x` (`12px`) + `--coar-field-padding-x-tight` (`calc(--coar-field-padding-x / 2)`).** A dedicated component token for form-field horizontal padding, intentionally **off** the spacing scale (`12px` sits in the scale's `8→16` gap) and **decoupled** from it — tuning `--coar-spacing-*` no longer moves field padding. Single source of truth for text / password / number / select fields (the consumer multiplies by `--coar-component-density`). The Theme Editor's "Inputs → Field padding" control (with its opt-in override switch) now drives this token.
* **`@cocoar/vue-ui` — `xs` size for `CoarSwitch` and `CoarRadioGroup`.** Both gain an extra-small `size="xs"` to match `CoarCheckbox` (which already had one): a `24×14` track with a `10px` thumb for the switch, a `14px` control with a `5px` dot for the radio, both labelled at `--coar-component-xs-font-size`. Adds `--coar-switch-xs-track-width` / `-track-height` / `-thumb-size` tokens. Additive — `s` / `m` / `l` are unchanged.

### Changed

* **`@cocoar/vue-ui` — `CoarTextInput` / `CoarPasswordInput` field padding.** Now read `--coar-field-padding-x` (value unchanged at `12px`). `CoarPasswordInput` no longer re-derives the same value inline with `calc(--spacing-s + --spacing-xs)` (which had drifted from the shared token) and its size-variant toggle paddings use `--coar-field-padding-x` / `-tight` instead of off-scale `calc()` sums.
* **`@cocoar/vue-ui` — field horizontal padding now scales per control size.** The whole field family (text / password / number / select / multi-select / tag-select) derives its horizontal padding as `--coar-field-padding-x × per-size-scale × density`, so xs/s/m/l no longer share a single flat value (e.g. at base `12px`: xs `8.1` · s `9.6` · m `12` · l `14.4`). You still tune **one** knob (`--coar-field-padding-x`, the `m` base) and every size scales proportionally — e.g. bump it for pill-shaped inputs and the smaller sizes follow. Adds `--coar-component-{xs,s,m,l}-scale` (unitless, height-derived: `0.675 / 0.8 / 1 / 1.2`) as a reusable per-size multiplier. Also unifies select/number field padding onto `--coar-field-padding-x` (they previously used a flat `--coar-spacing-s`, so the Theme Editor's Field-padding control now affects them too).
* **`@cocoar/vue-ui` — Theme Editor.** Dropped the dead `XXL` spacing slider; renamed the "Horizontal padding" control to "Field padding" (writes `--coar-field-padding-x`).
* **`@cocoar/vue-ui` — date-picker `error` prop is now `boolean` (breaking).** `CoarPlainDatePicker` / `CoarPlainDateTimePicker` / `CoarZonedDateTimePicker` `error` changed from `string` (an error message rendered below the field) to `boolean` (flips the red border + `aria-invalid`), matching `CoarTextInput` & the rest of the field family. The message itself moves to the wrapping `CoarFormField`. To migrate: `<CoarPlainDatePicker error="Required" />` → `<CoarFormField label="…" error="Required"><CoarPlainDatePicker /></CoarFormField>`. New `id` prop (explicit input id; else taken from `CoarFormField`, else auto) for parity with the other inputs.
* **`@cocoar/vue-ui` — list-selection controls aligned to the input token contract.** `CoarListbox` and `CoarDualListbox` now render their list panels with the input border + radius tokens (`--coar-border-input`, `--coar-input-radius`, capped at the field pill-end via `min(…, --coar-component-m-height / 2)` so a tall list doesn't bow into a stadium at full radius — the same cap the select dropdown panels use) and gain a distinct disabled surface (`--coar-surface-input-disabled`), matching the field family. `CoarDualListbox`'s transfer buttons are rebuilt on `CoarButton` (`secondary`, icon-only) instead of hand-rolled buttons, so they inherit the shared focus ring, sizing and disabled state (dropping an off-spec `opacity: 0.35` and hardcoded `32×28` dimensions). Visual refinement only — no API change.
* **`@cocoar/vue-ui` — toggle controls aligned to the input + semantic-error token contract.** `CoarCheckbox`, `CoarSwitch` and `CoarRadioGroup` now key their box / track / control chrome off the shared input tokens and the correct semantic-error layers: the checkbox box radius uses `--coar-input-radius` (was `--coar-radius-xs`); checkbox + switch error states use `--coar-border-semantic-error-bold` / `--coar-background-semantic-error-bold` instead of the text-layer token (which fixes a too-dark error tint in dark mode); the radio control adopts `--coar-border-input` / `--coar-surface-input` / `--coar-border-input-hover` (was the `neutral-primary` tokens plus an accent hover) and `--coar-component-{size}-font-size` labels, and its disabled opacity is unified to `0.6` to match the rest of the toggle family. Action controls (`CoarButton` / `CoarSegmentedControl`) intentionally keep their `0.5` disabled look. Visual refinement only — no API change.
* **`@cocoar/vue-ui` — `clearable` now defaults to `false` (breaking).** `CoarTextInput`, `CoarPasswordInput`, `CoarNumberInput`, `CoarPlainDatePicker`, `CoarPlainDateTimePicker` and `CoarZonedDateTimePicker` previously defaulted `clearable` to `true`; it's now `false`, in line with the library rule that every boolean prop defaults `false` (and matching `CoarSelect` / `CoarMultiSelect`, which were already `false`). Add `clearable` where you want the inline clear ✕. Also fixed: the right-aligned controls (number + the 3 date-pickers) used to render a hidden clear button unconditionally, reserving an empty slot on the **left**; the clear affix is now omitted entirely when not clearable, so a non-clearable control has no reserved gap. `@cocoar/vue-data-grid` is unaffected — its cell editors pass `clearable` explicitly.

***

## 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.
* **`@cocoar/vue-page-builder` — flex layout model** *(retroactive note: this shipped in 2.10.0 but was missing from the changelog)*. `NodeStyle` gained the guided flex model — container `justify` / `align`, per-node `alignSelf`, `size` (`fit` · `fill` · `fixed`, direction-aware `fill`) with `width`, and `minHeight` — plus the Style-panel controls for all of them and a shared `styleMapping` so the editor canvas matches the rendered preview 1:1. Schemas using these fields are valid from 2.10.0 onward.

### 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
description: >-
  The six Cocoar Design System principles — clarity, consistency, accessibility,
  touch-first, performance, developer experience — plus the design token
  architecture and do's and don'ts.
---

# 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
description: >-
  Cocoar's two-layer color system: primitive palettes and semantic tokens that
  adapt to light and dark mode, with naming convention and full token reference.
---

# 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
description: >-
  The Cocoar type scale: eleven utility classes from display to footnote using
  Inter and Poppins, with sizes, weights, and usage examples.
---

# 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
description: >-
  Spacing and effects tokens: the 4 px spacing scale, border radius, stroke
  widths, and six shadow elevation levels with reference tables.
---

# 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
description: >-
  CoarIcon and the built-in SVG icon set: preset sizes, colors, rotation, spin
  animation, and registering custom icon sources with fallback.
---

# 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
description: >-
  Motion design tokens: duration and easing CSS variables plus pre-composed
  transition values, with interactive demos and usage examples.
---

# 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
description: >-
  CoarThemeEditor, a live token editor: explore primitive, semantic, and
  component token layers, apply presets, and export a CSS snippet.
---

# 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
description: >-
  Install and configure @cocoar/vue-localization: register the
  createCoarLocalization() plugin, set locale and translation URLs, and switch
  languages at runtime.
---

# 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
description: >-
  Locale-aware number, currency, percent, and date formatting via the useL10n()
  composable from @cocoar/vue-localization, reacting to language changes.
---

# 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
description: >-
  Translation lookup with the useI18n() composable: t() and tRef() with
  parameter interpolation, HTTP-loaded or code-registered translations, and
  fallbacks.
---

# 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
description: >-
  The useTimezone() composable exposes the detected IANA timezone as a reactive
  ref, with support for custom timezone providers.
---

# 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
description: >-
  CoarButton — action button with five variants, four sizes, icons, loading and
  disabled states, full width and router-aware link rendering.
---

# 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
description: >-
  CoarFormField — label, hint and validation wrapper for form controls with a
  severity-aware status icon, pinnable popover and live-evaluated rules
---

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

## Layout and Label Position

`CoarFormField` can place its label before or after any control, either stacked or inline. All four combinations have a visible effect. Inline layouts are especially useful when the field label is the only label of a checkbox or switch; leave the control's own `label` unset in that case.

## 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"`. |
| `layout` | `'stacked' \| 'inline'` | `'stacked'` | Places the label/status cluster and control vertically or on one row. |
| `labelPosition` | `'before' \| 'after'` | `'before'` | Places the complete label/status cluster before or after the control. Works in both layouts. |
| `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
description: >-
  CoarTextInput — text field with validation states, prefix/suffix decorations,
  clearable option, four sizes and multiline textarea mode
---

# 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, a small X button appears on hover or focus so users can quickly reset the field. It's **off by default** — set `clearable` to opt in.

## 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` | `false` | 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
description: >-
  CoarNumberInput — numeric input with min/max clamping, configurable step,
  optional stepper buttons, four sizes and standard form states
---

# 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` | `false` | 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
description: >-
  CoarPasswordInput — masked text input with show/hide visibility toggle,
  clearable option, four sizes, validation states and CoarFormField integration
---

# 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` | `false` | 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
description: >-
  CoarOtpInput — N-cell one-time-code input with auto-advance, paste spreading,
  numeric/alphanumeric/text modes, masking, transform/accept hooks and a
  complete event
---

# 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
description: >-
  CoarSelect, CoarMultiSelect and CoarTagSelect — dropdown selection with inline
  search, clearable state, option groups, sorting and form-field integration
---

# 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
description: >-
  CoarListbox — single-column selectable list with grouping, search,
  multi-select highlighting, keyboard navigation, custom item renderers and
  display-only mode
---

# 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
description: >-
  CoarDualListbox — two-column transfer list with move buttons, per-column
  search, grouping, custom item renderers and drag & drop between columns
---

# 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
description: >-
  CoarCheckbox — boolean checkbox with v-model, indeterminate state, four sizes,
  label positioning, validation states and CoarFormField integration.
---

# 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. When the form field owns the label, use `layout="inline"` for checkbox and switch rows.

## Label Position

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

## Long Labels

Checkbox labels may wrap naturally. These deliberately narrow examples show both label positions and a mixed-length group.

## 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/checkbox-group.md
description: >-
  CoarCheckboxGroup — coordinate multiple checkboxes through one array or
  boolean-record model, with FormField integration.
---

# Checkbox Group

`CoarCheckboxGroup` turns multiple keyed checkboxes into one field value. Each child keeps its own visible label and DOM id; the group owns selection state, layout, shared form name, disabled/error state, and accessibility semantics.

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

## Array and Object Models

Use `value` as the stable domain key of each checkbox. An array model contains the selected keys. Object mode contains every registered key with an explicit Boolean value. External model changes immediately update the visible checkboxes in both modes.

## With Form Field

Wrap the complete group in one `CoarFormField`. The FormField label describes the group; the child labels describe the individual options.

```vue
<CoarFormField
  label="Permissions"
  hint="Select every permission this role should receive."
>
  <CoarCheckboxGroup v-model="permissions">
    <CoarCheckbox value="read" label="Read" />
    <CoarCheckbox value="write" label="Write" />
  </CoarCheckboxGroup>
</CoarFormField>
```

## API

### CoarCheckboxGroup props

| Prop | Type | Default | Description |
|---|---|---|---|
| `v-model` | `readonly string[] \| Readonly<Record<string, boolean>>` | `undefined` | Complete group value |
| `modelType` | `'array' \| 'object'` | inferred, then `'array'` | Output shape, especially useful before a model has a value |
| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Child layout |
| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Size inherited by every child checkbox |
| `name` | `string` | `undefined` | Native form name shared by all child inputs |
| `disabled` | `boolean` | `false` | Disables all children |
| `error` | `boolean` | `false` | Marks the group and all children invalid |

::: info Group keys
Inside a group, every `CoarCheckbox` must have a non-empty, unique `value`. `id` remains a DOM/accessibility identifier and is never used as application data.
:::

---

---
url: /components/radio-group.md
description: >-
  CoarRadioGroup and CoarRadioButton — single-choice selection with horizontal
  or vertical layout, four sizes, label positioning, keyboard navigation and
  form-field integration
---

# 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

Four 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` | `'xs' \| '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
description: >-
  CoarSwitch — toggle for boolean settings that apply immediately, with four
  sizes, label positioning, validation states and keyboard and screen-reader
  support
---

# 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

Four 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` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Switch size |
| `disabled` | `boolean` | `false` | Disable the switch |
| `labelPosition` | `'before' \| 'after'` | `'after'` | Label position relative to the switch |

---

---
url: /components/segmented-control.md
description: >-
  CoarSegmentedControl — toolbar button-bar for switching between
  mutually-exclusive view options, with icons, four sizes, disabled segments and
  full-width mode
---

# 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/date-picker.md
description: >-
  CoarPlainDatePicker — calendar date picker returning Temporal.PlainDate, with
  min/max limits, validation states, four sizes and form-field integration.
---

# 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 |
| `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` | `boolean` | `false` | Error state (red border + `aria-invalid`). Auto-injected from a wrapping [`CoarFormField`](/components/form-field). |
| `id` | `string` | `''` | Explicit input id (else taken from `CoarFormField`, else auto). |

> **Label, hint, error message and the status icon live on the wrapping [`CoarFormField`](/components/form-field)** — not on the picker. Wrap the picker in a `CoarFormField` to get a label, the required asterisk, validation messages and the inline status indicator. The picker auto-adopts the field's id, error state and `aria-describedby` via injection.

## 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
description: >-
  CoarPlainDateTimePicker — combined calendar and time input returning a
  timezone-less Temporal.PlainDateTime, with validation states, four sizes and
  localized labels.
---

# 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 |
| `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` | `boolean` | `false` | Error state (red border + `aria-invalid`). Auto-injected from a wrapping [`CoarFormField`](/components/form-field). |
| `id` | `string` | `''` | Explicit input id (else taken from `CoarFormField`, else auto). |

> **Label, hint, error message and the status icon live on the wrapping [`CoarFormField`](/components/form-field)** — not on the picker. Wrap the picker in a `CoarFormField` for a label, the required asterisk, validation messages and the inline status indicator; the picker auto-adopts the field's id, error state and `aria-describedby` via injection.

---

---
url: /components/zoned-date-time-picker.md
description: >-
  CoarZonedDateTimePicker — timezone-aware datetime picker capturing date, time
  and IANA timezone as one Temporal.ZonedDateTime, with form states and four
  sizes
---

# 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'`) |
| `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` | `boolean` | `false` | Error state (red border + `aria-invalid`). Auto-injected from a wrapping [`CoarFormField`](/components/form-field). |
| `id` | `string` | `''` | Explicit input id (else taken from `CoarFormField`, else auto). |

> **Label, hint, error message and the status icon live on the wrapping [`CoarFormField`](/components/form-field)** — not on the picker. Wrap the picker in a `CoarFormField` for a label, the required asterisk, validation messages and the inline status indicator; the picker auto-adopts the field's id, error state and `aria-describedby` via injection.

---

---
url: /components/date-or-time-picker.md
description: >-
  CoarZonedDateTimeOrDatePicker and CoarPlainDateTimeOrDatePicker — date pickers
  with a clock toggle switching between plain date and date-with-time values.
---

# Date · optional time

Sometimes a field is "a date, and *maybe* a time" — a due date that's usually
just a day but occasionally needs an hour, a reminder that can be all-day or
timed. Instead of a separate checkbox, these pickers put a small **clock toggle
beside the field**: off means a plain date, on means a date with time.

Two variants, by whether the time carries a timezone:

```ts
import {
  CoarZonedDateTimeOrDatePicker, // PlainDate  ⇄  ZonedDateTime (with IANA zone)
  CoarPlainDateTimeOrDatePicker, // PlainDate  ⇄  PlainDateTime (zone-less)
} from '@cocoar/vue-ui';
```

## Basic usage

Click the clock to switch modes. The value is one of two `Temporal` types — read
it directly to know what you got.

## The value model

A single `v-model` carries the **union** value, and `v-model:withTime` is the
toggle. They stay in sync: a non-null value's own type *is* the mode, and while
empty the toggle decides.

```vue
<CoarZonedDateTimeOrDatePicker v-model="value" v-model:with-time="withTime" />
```

```ts
// value is Temporal.ZonedDateTime | Temporal.PlainDate | null
if (value instanceof Temporal.ZonedDateTime) {
  // time was on — persist a timestamp
} else if (value instanceof Temporal.PlainDate) {
  // date only — persist a calendar date
}
```

Toggling **on** keeps the date and adds a time (the current time, rounded to
`minuteStep`) — and, for the zoned variant, the `timeZone` (or the user's zone).
Toggling **off** drops the time (and zone) back to the date. So flipping the
clock never loses the day.

## Zone-less variant

`CoarPlainDateTimeOrDatePicker` is the same idea without timezones — the with-time
value is a `Temporal.PlainDateTime`.

## Toggle position & sizes

The clock sits to the **left** by default; set `toggle-position="end"` for the
right. Sizes match the rest of the form-control family (`xs` · `s` · `m` · `l`),
and the toggle scales with the field.

::: info Composition, not reinvention
These are thin wrappers over [`CoarPlainDatePicker`](/components/date-picker),
[`CoarPlainDateTimePicker`](/components/date-time-picker) and
[`CoarZonedDateTimePicker`](/components/zoned-date-time-picker) — they render the
existing picker for the active mode and add the toggle beside it. All the
common props pass straight through.
:::

## Theming

There's no new chrome to theme: the field is a `CoarInputFrame` and the toggle a
`CoarButton`, both driven by the usual tokens. The toggle's roundness **tracks
`--coar-input-radius`**, so it always matches the adjacent field (a pill theme
gives a round toggle), and the gap uses `--coar-spacing-xs`. Nothing to register
in the theme editor — tuning the existing input / button / spacing / accent
tokens restyles these too.

## Accessibility

The clock is a toggle button: it exposes `aria-pressed` for its state and a
state-aware tooltip + `aria-label` (**Add time** when off, **Remove time** when
on, both overridable). The active field itself is the underlying picker, so its
keyboard and screen-reader behaviour is identical to the standalone pickers.

> Wrap the picker in a [`CoarFormField`](/components/form-field) for a label, the
> required asterisk, validation message and status icon — exactly like the other
> date pickers. The field auto-adopts the form field's id and error state.

## API

Both components share this surface (the zoned variant adds the timezone props).

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `v-model` | `PlainDate \| ZonedDateTime \| null` (zoned)`PlainDate \| PlainDateTime \| null` (plain) | `null` | The union value. |
| `v-model:withTime` | `boolean` | `false` | The clock toggle / mode. |
| `placeholder` | `string` | `''` | Placeholder text. |
| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Field + toggle size. |
| `disabled` | `boolean` | `false` | Disable the field and toggle. |
| `readonly` | `boolean` | `false` | Read-only (toggle disabled too). |
| `required` | `boolean` | `false` | Mark as required. |
| `error` | `boolean` | `false` | Error state. Auto-injected from a wrapping `CoarFormField`. |
| `clearable` | `boolean` | `false` | Show the inline clear button. |
| `locale` | `string` | — | Locale override. |
| `min` / `max` | with-time type | `null` | Bounds; the date mode uses their date part. |
| `minuteStep` | `1 \| 5 \| 10 \| 15` | `5` | Time-of-day step (also the default-time rounding). |
| `togglePosition` | `'start' \| 'end'` | `'start'` | Clock side, relative to the field. |
| `addTimeLabel` | `string` | `'Add time'` | Tooltip + label while time is off. |
| `removeTimeLabel` | `string` | `'Remove time'` | Tooltip + label while time is on. |

**Zoned variant only:**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `timeZone` | `string \| null` | `null` | Default IANA zone for a value gaining a time (else the user's zone). |
| `timezoneFilter` | `string[]` | `[]` | Wildcard filters for the timezone list (e.g. `['Europe/*']`). |

### Events

| Event | Payload | Description |
|-------|---------|-------------|
| `update:modelValue` | union value | The value changed. |
| `update:withTime` | `boolean` | The mode changed. |
| `opened` / `closed` | — | The calendar panel opened / closed. |

---

---
url: /components/date-views.md
description: >-
  CoarPlainDateView, CoarPlainDateTimeView and CoarZonedDateTimeView —
  read-only, locale-aware displays for Temporal date values with cross-zone
  projection.
---

# 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
description: >-
  CoarAvatar — user avatar with image and generated-initials fallback, six
  sizes, circle or square shape, clickable mode and group stacking.
---

# 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
description: >-
  CoarBadge — count and status badge with six semantic variants, five sizes,
  max-value capping, dot mode, pulse animation and border ring.
---

# 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
description: >-
  CoarCard — content container with elevated and outlined styles, semantic color
  variants, padding sizes and header, footer and inset slots.
---

# 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
description: >-
  CoarCodeBlock — syntax-highlighted code display with copy-to-clipboard button,
  collapsible behavior, line numbers, title label and color variants.
---

# 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
description: >-
  CoarDivider — horizontal separator with optional slotted label,
  left/center/right alignment, subtle or strong weight and spacing controls.
---

# 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
description: >-
  CoarLink — styled anchor for router and external navigation with accent/subtle
  variants, three sizes, safe new-tab defaults and disabled handling
---

# 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
description: >-
  CoarNote — callout for supplementary information with six semantic color
  variants, three padding sizes and rich HTML slot content
---

# 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/notice.md
description: >-
  CoarNotice — compact inline notices and application banners with six semantic
  variants
---

# Notice

Notices communicate short, timely status information. They are deliberately more compact than [Notes](./note): use a Notice for a sentence near a control or directly below an application header, and a Note for rich supporting content inside a page.

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

## Variants

Every variant has its own semantic color and default icon. The icon can be replaced with the `icon` prop.

## Banner

`placement="banner"` removes the radius and side borders so the Notice can sit flush below a header. The component is not sticky by itself—the surrounding application layout decides where it stays.

Banner text always wraps. For compact inline use, `truncate` can deliberately keep a message on one line.

## Details and actions

Keep the primary message short. Optional long-form information belongs in the `details` slot and opens in a popover. Put links or buttons in the `cta` slot; the Notice itself is intentionally not clickable.

## API

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'error' \| 'accent'` | `'info'` | Semantic color and default icon |
| `placement` | `'inline' \| 'banner'` | `'inline'` | Bordered callout or edge-to-edge banner |
| `label` | `string` | — | Bold lead-in; a colon is added |
| `icon` | `string` | variant default | Custom icon name |
| `truncate` | `boolean` | `false` | Single-line inline content; ignored for banners |

### Slots

| Slot | Description |
|------|-------------|
| `default` | Short primary message |
| `details` | Long-form content shown in a popover |
| `cta` | Link or button aligned to the right |

---

---
url: /components/progress-bar.md
description: >-
  CoarProgressBar — determinate and indeterminate progress indicator with
  semantic color variants, three sizes, optional value display and accessible
  labels
---

# 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
description: >-
  CoarSpinner — animated loading indicator for operations of unknown duration,
  with four sizes, accessible labels and full-page overlay patterns
---

# 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
description: >-
  CoarTable — lightweight styled table wrapper with striped, plain and bordered
  variants, compact padding, hover highlighting and rich cell content
---

# 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
description: >-
  CoarTag — label chip with six semantic color variants, three sizes, closable
  and selectable modes for metadata, categories and filter bars
---

# 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
description: >-
  CoarMenu — context menus and action lists with full keyboard support, icons,
  headings, dividers, nested and flyout submenus and router-aware link items
---

# 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
description: >-
  CoarContextMenu with useContextMenu — right-click menu at the pointer position
  with viewport clamping, submenus, flyouts and auto-close behavior.
---

# 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
description: >-
  CoarSidebar — navigation sidebar with header/content/footer sections,
  collapsible icon-only mode, expand and flyout groups, four-side orientation
  and router-aware items
---

# 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
description: >-
  CoarNavbar — top-level navigation bar with start, center and end content
  slots, elevated shadow by default or a flat bordered variant
---

# 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
description: >-
  CoarTabGroup and CoarTab — v-model tab navigation with disabled tabs, tab-bar
  actions slot, fill-height mode and full keyboard support
---

# 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
description: >-
  CoarTree — generic tree primitive with keyboard navigation, drag-and-drop
  reorder, single/multiple/checkbox selection, context menus, lazy loading and a
  fluent useTree builder
---

# 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/breadcrumb.md
description: >-
  CoarBreadcrumb — hierarchical navigation trail with router-aware links,
  non-interactive active item, icons and automatic render-mode selection per
  crumb.
---

# 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
description: >-
  CoarPagination — page navigation computed from totalItems and pageSize with
  ellipsis truncation, first/last buttons and localized aria-labels
---

# 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
description: >-
  CoarSplitPane and CoarPanelLayout — resizable split panes and a VS-Code-style
  workbench shell with top/left/content/right/bottom/status regions
---

# 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
description: >-
  CoarWizard — multi-step flow shell for modals with animated body resize,
  scrollable auto-centering step indicator, edge-placeable progress strip and
  step gating
---

# 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
description: >-
  useDialog — promise-based modal dialogs for confirm, alert and custom
  components, with configurable buttons, sizes and localized labels.
---

# 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
description: >-
  CoarPopover — anchored panel for rich interactive content with hover, click or
  combined trigger modes and automatic viewport-aware positioning
---

# 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
description: >-
  CoarPopconfirm — inline confirmation bubble anchored to a trigger element,
  with confirm/cancel actions, danger variant, custom labels and placement
  control
---

# 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
description: >-
  useToast and CoarToastContainer — non-blocking notification service with
  semantic variants, duration and position control, action buttons and progress
  indicator
---

# 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
description: >-
  v-tooltip directive — text-only hover and focus hints for any element, with
  placement options and accessible labels for icon buttons
---

# 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
description: >-
  CoarFade, CoarSlide, CoarScale, CoarCollapse — pre-built Vue transition
  wrappers on design-system motion tokens with duration presets and
  prefers-reduced-motion support
---

# 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
description: >-
  useVirtualList — composable that virtualizes large scrollable lists, rendering
  only visible rows with overscan, variable item heights and scrollToIndex
---

# 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
description: >-
  useDragDrop — HTML5 drag-and-drop composable with group, accept and canDrop
  matching rules for building custom drag surfaces like Kanban boards.
---

# 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
description: >-
  @cocoar/vue-fragment-parser — parses URL hash fragments into typed routes with
  parameters; composables enable deep-linkable modals with browser-back to close
---

# 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
description: >-
  @cocoar/vue-markdown — markdown rendering split into a framework-agnostic
  parser (markdown-core) and the CoarMarkdown Vue component with GFM support
---

# 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. |
| `embeds` | `EmbedRegistry` | *(optional)* Custom-embed registry — renders `:::key{props}` directives via your components. See [Custom Embeds](/components/markdown-embeds). |
| `fenceRenderers` | `FenceRegistry` | *(optional)* Fenced-code-block renderer registry — render a fence language (e.g. ` ```mermaid `) with a rich component instead of a plain code block. Unregistered languages stay code blocks. See [Diagrams](/components/markdown-diagrams). |

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

## Custom Embeds

Render your own Vue components from a `:::key{props}` directive by passing an
`embeds` registry. The same registry works in `<CoarMarkdownEditor>`, where the
embed becomes editable — so a document looks consistent whether read or written.

```vue
<CoarMarkdown :doc="doc" :embeds="embeds" />
```

See the dedicated **[Custom Embeds](/components/markdown-embeds)** page for the
registry shape, security model, and a live editor + viewer demo.

## Diagrams

Render a fenced code block — ` ```mermaid ` — as a diagram by passing a
`fenceRenderers` registry. An unregistered fence language stays a plain,
syntax-highlighted code block, so the markdown stays portable.

```vue
<CoarMarkdown :doc="doc" :fence-renderers="fenceRenderers" />
```

See the dedicated **[Diagrams](/components/markdown-diagrams)** page for the
opt-in `@cocoar/vue-markdown-mermaid` package, theming, zoom/pan and how to
register your own fence renderer.

## Node Types

```ts
type MarkdownNodeType =
  | 'frontmatter'
  | 'heading' | 'paragraph' | 'blockquote'
  | 'list' | 'listItem'
  | 'codeBlock' | 'table' | 'tableRow' | 'tableCell'
  | 'thematicBreak' | 'lineBreak'
  | 'text' | 'emphasis' | 'strong' | 'strikethrough'
  | 'inlineCode' | 'link' | 'image'
  | 'colorSpan' | 'embed';

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
description: >-
  CoarMarkdownEditor — Milkdown-based WYSIWYG markdown editor with lossless
  round-trip, floating or fixed toolbar and a render registry shared with
  CoarMarkdown
---

# 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** + **custom embeds** (non-portable) | 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?, embeds? }`) is **opt-in** — unspecified capabilities are off, so `{}` ≡ `'commonmark'`. The default is `'cocoar'`, which also enables `embeds` — see [Custom Embeds](/components/markdown-embeds).

::: tip flavor vs. tools
`flavor` is the **hard format contract** (what can exist in the document). The [`tools`](#toolbar-layout-tools) layout is **soft toolbar curation** (which buttons show, and where) *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.
:::

## Custom Embeds

Register your own Vue components against a `:::key{props}` directive and the
editor folds them into live, editable blocks (the viewer renders the same
component read-only). Pass an `embeds` registry and use the `cocoar` flavor:

```vue
<CoarMarkdownEditor v-model="value" flavor="cocoar" :embeds="embeds" :tools="tools" toolbar-mode="both" />
```

This is its own topic — see the dedicated **[Custom Embeds](/components/markdown-embeds)**
page for the registry shape, the editor `controller` contract, toolbar insert
placement, and a live demo.

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

## Toolbar layout (`tools`)

Pass a `tools` array to control which buttons the **sidebar** toolbar exposes and
in what order. When omitted, the default layout is used. **The array order IS the
toolbar order** — entries render top-to-bottom (or left-to-right) as listed.

```vue
<!-- Minimal subset, in the given order -->
<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" />
```

::: warning Order is now significant
Earlier, a flat `tools` array was an order-insensitive whitelist filtering a fixed
sequence. It is now an **ordered layout**. If you relied on canonical ordering,
list the tools in the order you want; the default (omit `tools`) is unchanged.
:::

### Groups and custom items

An entry can also be a **flyout group** (a submenu) or a `'divider'`. A group
bundles any mix of built-in tools and [custom-embed](/components/markdown-embeds)
inserts (`embed:<key>`) behind one button:

```ts
import type { CoarMarkdownEditorToolEntry } from '@cocoar/vue-markdown-editor';

const tools: CoarMarkdownEditorToolEntry[] = [
  'bold', 'italic', 'headings',
  'divider',
  { flyout: ['table', 'image', 'embed:chart'], label: 'Insert', icon: 'plus' },
  'divider',
  'undo', 'redo',
];
```

| Entry shape | Meaning |
|---|---|
| `'bold'` (a `CoarMarkdownEditorTool`) | A built-in tool. |
| `` `embed:chart` `` (a `` `embed:${string}` ``) | A registered custom embed's insert item — see [Custom Embeds](/components/markdown-embeds). |
| `{ flyout: ToolRef[], label?, icon? }` | A flyout submenu containing any of the above. |
| `'divider'` | A separator. |

### 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` | `CoarMarkdownEditorToolEntry[]` | *default layout* | Ordered toolbar layout (built-in ids, `embed:<key>` refs, `{ flyout }` groups, `'divider'`). See [Toolbar layout](#toolbar-layout-tools) |
| `flavor` | `'commonmark' \| 'gfm' \| 'cocoar' \| { gfm?, textColor?, embeds? }` | `'cocoar'` | Portability contract — hard-enforces which features can be authored. See [Flavors](#flavors-portability) |
| `embeds` | `EmbedRegistry` | *undefined* | Custom-embed registry (`:::key{props}` → your component). Requires the `embeds` capability (`cocoar` flavor). See [Custom Embeds](/components/markdown-embeds) |
| `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/markdown-embeds.md
description: >-
  Markdown custom embeds — register Vue components rendered from :::key{props}
  directives in both viewer and editor, with lossless round-trip to plain text
---

# Custom Embeds&#x20;

Embed your own Vue components into markdown with a `:::key{props}` directive. The
**same** registry drives the shared viewer (`<CoarMarkdown>`) and the editor
(`<CoarMarkdownEditor>`): a registered component renders read-only when reading
and editable when writing, and the directive round-trips losslessly to text.

The embedded component has **zero dependency on markdown** — it's a plain
component with normal props that a consumer registers from the outside. The
markdown packages never depend on it; the registry is the only meeting point.

::: info Spans three packages
The directive parser lives in `@cocoar/vue-markdown-core` (Vue-free); the registry
and renderer in `@cocoar/vue-markdown`; the editor NodeView + insert affordance in
`@cocoar/vue-markdown-editor`. Registering an embed once lights up all three.
:::

The demo registers one embed under the key `stat`. Edit the metric inline in the
editor, or insert a fresh one from the **Insert ▾** flyout in the left rail — the
viewer (right) updates from the same markdown.

## The directive

A custom embed is a standalone block on its own line:

```
:::stat{label="Revenue" value="1,284" trend="+12.4%" tone=positive}
```

* `stat` is the **key** — it selects the registered component.
* The `{…}` attributes become the component's props. Values are strings;
  bareword values may be unquoted (`tone=positive`, `id=2f1c0b9e-…`), values with
  spaces or specials are quoted (`label="Revenue"`). A valueless attribute
  (`{interactive}`) is an empty string.

The parser is **registry-agnostic**: any `:::key{…}` parses to a generic `embed`
node and round-trips, even when no component is registered for that key (it then
renders as a labelled placeholder — see [Unknown keys](#unknown-keys)).

::: tip Lossless round-trip
`parse → serialize → parse` is a fixed point. Canonical forms like
`:::map{id=<guid>}` are byte-stable; non-canonical input (extra quoting) is
normalized on the first serialize and stable thereafter.
:::

## Registering an embed

The registry maps a key to a definition. Pass it to the viewer and/or editor via
the `embeds` prop:

```ts
import type { EmbedRegistry } from '@cocoar/vue-markdown';
import StatCard from './StatCard.vue';        // your read-only component
import StatCardConfig from './StatCardConfig.vue'; // your editable component

const embeds: EmbedRegistry = {
  stat: {
    viewer: StatCard,           // required — read-only render (viewer + editor fallback)
    editor: StatCardConfig,     // optional — editable variant in the editor
    insert: {                   // optional — toolbar insert affordance
      label: 'Stat card',
      icon: 'layout-grid',
    },
  },
};
```

| Field | Type | Description |
|---|---|---|
| `viewer` | `Component` | **Required.** Read-only render for this key. Used by the viewer, and as the editor's fallback when no `editor` is supplied. Receives the directive attributes as props. |
| `editor` | `Component` | *Optional.* Editable variant mounted in the editor. Receives a single `controller` prop — see [The editor contract](#the-editor-contract). Falls back to `viewer` when omitted. |
| `insert` | `EmbedInsertIntegration` | *Optional.* Toolbar insert affordance — `{ label?, icon?, pick? }`. See [Toolbar insert](#toolbar-insert). |

::: tip `markRaw` your components
Wrap component definitions in `markRaw(...)` when building the registry so Vue
doesn't make them reactive: `{ viewer: markRaw(StatCard) }`.
:::

## Viewer

Pass `embeds` to `<CoarMarkdown>`. The directive renders through the registered
`viewer`, read-only:

```vue
<template>
  <CoarMarkdown :doc="doc" :embeds="embeds" />
</template>

<script setup lang="ts">
import { parse } from '@cocoar/vue-markdown-core';
import { CoarMarkdown } from '@cocoar/vue-markdown';
import { embeds } from './embeds';

const doc = parse(':::stat{label="Revenue" value="1,284"}', { gfm: true });
</script>
```

An app-wide default works too — `app.provide(MARKDOWN_EMBEDS_KEY, embeds)`. A
per-instance `embeds` prop wins over the provided value.

## Editor

Custom embeds are **non-portable**, so they're gated behind the `cocoar`
[flavor](/components/markdown-editor#flavors-portability) (or an explicit
`{ embeds: true }` capability). Pass the same registry via `embeds`:

```vue
<CoarMarkdownEditor
  v-model="value"
  flavor="cocoar"
  :embeds="embeds"
/>
```

The editor folds a `:::key{…}` line into an **atomic block** rendered by a live
NodeView. When the registry entry provides an `editor` component it's mounted
editable; otherwise the read-only `viewer` is shown. Either way the directive
round-trips on save.

### The editor contract

An editor component receives a single, typed `controller` prop — there is no
`v-model` emit string to remember. The controller carries the current attributes
and the write-back methods:

```ts
interface EmbedEditorController<T extends Record<string, string> = Record<string, string>> {
  readonly props: Readonly<T>;     // current directive attributes
  update(next: T): void;           // replace the whole bag → writes to markdown
  patch(partial: Partial<T>): void; // merge a partial patch (the common case)
}

interface EmbedEditorProps<T extends Record<string, string> = Record<string, string>> {
  controller: EmbedEditorController<T>;
}
```

Type your component with `EmbedEditorProps` and call `controller.patch(...)` to
write changes back. Those writes flow into the ProseMirror node and round-trip to
the `:::key{props}` markdown — which is the **only** difference between an editor
and the viewer: the viewer renders an immutable parsed document and cannot write.

```vue
<script setup lang="ts">
import type { EmbedEditorProps } from '@cocoar/vue-markdown';
import StatCard from './StatCard.vue';

const props = defineProps<EmbedEditorProps>();
</script>

<template>
  <div>
    <input
      :value="props.controller.props.label ?? ''"
      @input="props.controller.patch({ label: ($event.target as HTMLInputElement).value })"
    />
    <StatCard v-bind="props.controller.props" />
  </div>
</template>
```

::: tip Any edit UX — inline, modal, picker
The editor component is yours. It can edit inline (as above), or render the
read-only preview plus an **Edit** button that opens a `useDialog()` modal and
calls `controller.update(next)` on save. The library only provides the write
channel; the configuration UI is the embed's to design.
:::

::: info Generic attribute typing
`EmbedEditorProps<T>` is generic, so a specific embed can type its own bag —
`defineProps<EmbedEditorProps<{ id: string; zoom: string }>>()` — instead of the
default `Record<string, string>`.
:::

## Toolbar insert

Give a registry entry an `insert` and it can be placed in the toolbar. The
**registry** defines the *item* (icon, label, behaviour); the editor's
[`tools`](/components/markdown-editor#toolbar-layout-tools) layout decides
*where* it appears — referenced by `embed:<key>`:

```ts
const tools: CoarMarkdownEditorToolEntry[] = [
  'bold', 'italic', 'headings',
  'divider',
  { flyout: ['embed:stat'], label: 'Insert', icon: 'plus' }, // submenu, builtin + embed mixable
  'divider',
  'undo', 'redo',
];
```

```vue
<CoarMarkdownEditor v-model="value" flavor="cocoar" :embeds="embeds" :tools="tools" toolbar-mode="both" />
```

::: warning Insert lives in the sidebar
Like the table / image / code-block buttons, the insert item is a **sidebar**
tool — use `toolbar-mode="fixed"` or `"both"` so the rail is visible. Embeds are
block inserts, not text formatting, so they never appear in the floating toolbar.
:::

`EmbedInsertIntegration`:

| Field | Type | Description |
|---|---|---|
| `label` | `string` | Item label / tooltip. Defaults to the key. |
| `icon` | `string` | `CoarIcon` name. Defaults to `layout-grid`. |
| `pick` | `() => Promise<Record<string,string> \| null> \| Record<string,string> \| null` | *Optional.* Resolve the **start attributes** for a new embed — e.g. open a picker dialog. Return `null` to cancel. When omitted, a bare `:::key` is inserted. |

A `pick` callback is where you'd open a chooser (which map? which chart?) and
return its props, e.g. `() => ({ id: chosenGuid })` → inserts `:::map{id=…}`.

## Unknown keys

A `:::key{…}` whose key isn't registered still parses and round-trips — it just
renders as a labelled placeholder (`🧩 Unknown embed: :::key`) in both the viewer
and the editor, so the author sees that an embed is there instead of a blank gap.
This also means a document moved to an app that hasn't registered the embed
degrades gracefully rather than losing content.

## Security

In the JS renderer, attribute values are bound as **Vue props / text**, never via
`innerHTML` — so untrusted author text (a label like `</script><img onerror=…>`)
is inert by construction; no manual HTML escaping is needed. (A server-side
string-lowering renderer in another language must escape on its own.)

## API reference

### `@cocoar/vue-markdown-core`

| Export | Description |
|---|---|
| `parseEmbedDirective(line)` | Parse a single line into `{ key, props } \| null`. |
| `serializeEmbedDirective({ key, props })` | Serialize back to the canonical `:::key{props}` form. |
| `toEmbedProps(value)` | Coerce an unknown value into a clean `Record<string, string>`. |
| `'embed'` node type | Added to `MarkdownNodeType`; `attrs` carry `{ key, props }`. |

### `@cocoar/vue-markdown`

| Export | Description |
|---|---|
| `EmbedRegistry` | `Record<string, EmbedDefinition>` — the key → definition map. |
| `EmbedDefinition` | `{ viewer, editor?, insert? }`. |
| `EmbedEditorProps` / `EmbedEditorController` | The editor component's `controller` contract. |
| `EmbedInsertIntegration` | `{ label?, icon?, pick? }`. |
| `MARKDOWN_EMBEDS_KEY` | Inject key for an app-wide registry. |
| `EmbedRenderer` | The shared resolve-and-render component (used internally by viewer + editor). |

### `@cocoar/vue-markdown-editor`

| Export | Description |
|---|---|
| `CoarMarkdownEditorToolEntry` | A `tools` entry: a ref, a `{ flyout }` group, or `'divider'`. |
| `CoarMarkdownEditorToolRef` | `CoarMarkdownEditorTool \| ` `` `embed:${string}` ``. |
| `CoarMarkdownEditorToolFlyout` | `{ flyout, label?, icon? }`. |

All embed types are re-exported from `@cocoar/vue-markdown-editor`, so a consumer
can import everything from one place.

---

---
url: /components/markdown-diagrams.md
description: >-
  @cocoar/vue-markdown-mermaid — renders mermaid code fences in CoarMarkdown as
  Cocoar-themed diagrams; lazy-loaded, strict security, degrades to plain code
  blocks
---

# Diagrams&#x20;

Render diagrams inside markdown from a fenced code block — \`\`\`mermaid
— using [`@cocoar/vue-markdown-mermaid`](https://www.npmjs.com/package/@cocoar/vue-markdown-mermaid).
The diagram source lives in the markdown as a normal code fence, so it
round-trips losslessly and **degrades to a readable code block** anywhere the
renderer isn't installed (strict CommonMark, a viewer-only build, a native mobile
renderer).

::: info Two mechanisms, two shapes
A **fenced code block** is for content whose *body is authored text in a DSL* —
diagrams, code. A [custom embed](/components/markdown-embeds) (`:::key{props}`) is
for a *single-line reference + a few props* rendered by a rich, visually-edited
component (e.g. a map). Diagrams belong in a fence; the map belongs in an embed.
:::

::: tip Two packages
The renderer lives in the standalone, markdown-free **`@cocoar/vue-mermaid`**
([`<CoarMermaidDiagram :code>`](/components/mermaid) — usable anywhere).
**`@cocoar/vue-markdown-mermaid`** is the thin adapter that registers it as a
fence renderer. Rendering a diagram **outside** markdown? See the
[**Mermaid Diagram**](/components/mermaid) page.
:::

## How it works

The markdown packages have **no dependency on Mermaid**. `<CoarMarkdown>` exposes
an open, language-keyed **fence-renderer registry**: register a component for a
fence language and that language renders through it instead of as a plain code
block. Installing `@cocoar/vue-markdown-mermaid` and registering it is the opt-in.

* **On disk** a diagram is a fenced code block with the `mermaid` info string.
  It's ordinary CommonMark — nothing custom to parse.
* **Rendering** is client-only (Mermaid needs a DOM) and lazy — Mermaid is
  dynamically imported on the first diagram, so viewer pages without one never
  pay for it.
* **Theming** maps Cocoar design tokens onto Mermaid's `themeVariables`, so
  diagrams match the app's fonts and palette.
* **Security**: Mermaid runs with `securityLevel: 'strict'` — author diagram text
  is treated as untrusted (HTML in labels is sanitized).
* **Invalid diagrams** degrade to an error box that still shows the raw source;
  they never throw up to the app.

## Install

```bash
pnpm add @cocoar/vue-markdown-mermaid
```

`vue` and `@cocoar/vue-markdown` are peer dependencies; `@cocoar/vue-mermaid`
(which carries Mermaid, dynamically imported on first render) comes along as a
regular dependency. Import its stylesheet once (diagram wrapper, error box, zoom
viewport):

```ts
import '@cocoar/vue-mermaid/styles';
```

## Usage

Pass the ready-made registry fragment to the viewer's `fenceRenderers` prop:

```vue
<template>
  <CoarMarkdown :doc="doc" :fence-renderers="mermaidFenceRenderers" />
</template>

<script setup lang="ts">
import { parse } from '@cocoar/vue-markdown-core';
import { CoarMarkdown } from '@cocoar/vue-markdown';
import { mermaidFenceRenderers } from '@cocoar/vue-markdown-mermaid';

const doc = parse(source);
</script>
```

A diagram in the source is just a fenced code block (shown here inside a wider
fence so it isn't rendered):

````text
```mermaid
flowchart LR
  A[Start] --> B{Choice}
  B -->|yes| C[Do it]
  B -->|no| D[Skip]
```
````

An app-wide default works too — `app.provide(MARKDOWN_FENCE_RENDERERS_KEY, mermaidFenceRenderers)`.
A per-instance `fence-renderers` prop wins over the provided value.

## Zoom & pan

Per-diagram options are configured on the **registry** (the fence contract only
passes `{ code, language }` to a component), via `createMermaidFenceRenderers`:

```ts
import { createMermaidFenceRenderers } from '@cocoar/vue-markdown-mermaid';

const fenceRenderers = createMermaidFenceRenderers({ zoomable: true });
```

Each diagram then sits in a fixed-height viewport with **+ / − / ⤢** controls,
**Ctrl/⌘ + wheel** zoom, **drag** to pan and **double-click** to reset. Plain
wheel and one-finger touch scrolling are left to the page, so a diagram never
traps the scroll. Set the height with the `--coar-mermaid-height` CSS variable
(default `420px`).

## Registering your own fence renderer

The registry is open — any language can be mapped to any component. Register your
own (e.g. a Graphviz renderer) alongside Mermaid, or replace Mermaid entirely:

```ts
import type { FenceRegistry } from '@cocoar/vue-markdown';
import { mermaidFenceRenderers } from '@cocoar/vue-markdown-mermaid';
import MyGraphviz from './MyGraphviz.vue';

// Component receives `{ code, language }` (FenceRendererProps).
const fenceRenderers: FenceRegistry = {
  ...mermaidFenceRenderers,
  dot: MyGraphviz,
};
```

A registered component receives the fence's raw text as `code` and the info
string as `language`. This is the same seam a future BPMN or PlantUML renderer
would plug into — no change to the markdown core.

## API reference

### `@cocoar/vue-markdown`

| Export | Description |
|---|---|
| `FenceRegistry` | `Record<string, Component>` — fence language → renderer component. Keys match case-insensitively. |
| `FenceRendererProps` | `{ code: string; language: string }` — props a registered renderer receives. |
| `MARKDOWN_FENCE_RENDERERS_KEY` | Inject key for an app-wide registry. |
| `resolveFenceRenderer(registry, language)` | The case-insensitive lookup used by `DefaultCodeBlock`. |

### `@cocoar/vue-markdown-mermaid` (the fence adapter)

| Export | Description |
|---|---|
| `mermaidFenceRenderers` | Ready-to-spread `FenceRegistry` fragment (`{ mermaid }`), no zoom. |
| `createMermaidFenceRenderers(options?)` | Build a registry with options baked in — `{ zoomable }`. |

### `@cocoar/vue-mermaid` (the standalone renderer)

| Export | Description |
|---|---|
| `CoarMermaidDiagram` | The renderer component (`{ code, language, zoomable }` props). Use directly to render diagrams outside markdown. |
| `buildMermaidThemeVariables(getToken, resolveColor?)` | Pure Cocoar-token → Mermaid-theme mapping. |
| `makeCssColorResolver()` / `readCssTokens(el?)` | Browser-backed color/token resolvers for the bridge. |

---

---
url: /components/mermaid.md
description: >-
  CoarMermaidDiagram — standalone Mermaid diagram component for Vue 3 rendering
  from a source string; Cocoar-themed, lazily loaded, with opt-in zoom/pan
---

# Mermaid Diagram&#x20;

A standalone [Mermaid](https://mermaid.js.org/) diagram component for Vue 3.
`<CoarMermaidDiagram :code>` renders a diagram from a Mermaid source **string** —
Cocoar-themed, lazy-loaded, with opt-in zoom/pan.

It knows **nothing about markdown** or any embedding layer — feed it a diagram
source and it renders. To turn ` ```mermaid ` fenced code blocks inside
`<CoarMarkdown>` into diagrams, use the thin adapter on the
[**Markdown Diagrams**](/components/markdown-diagrams) page (it registers this
same component as a fence renderer).

::: info Separate package

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

`vue` is the only peer dependency. Mermaid is a regular dependency, imported
**lazily** on first render (its own chunk). Import the stylesheet once:

```ts
import '@cocoar/vue-mermaid/styles';
```

:::

## Usage

```vue
<template>
  <CoarMermaidDiagram :code="code" zoomable />
</template>

<script setup lang="ts">
import { CoarMermaidDiagram } from '@cocoar/vue-mermaid';

const code = `
flowchart LR
  A[Start] --> B{Choice}
  B -->|yes| C[Do it]
  B -->|no| D[Skip]
`;
</script>
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `code` | `string` | — | The Mermaid diagram source. |
| `language` | `string` | `'mermaid'` | Info-string label; handy when one component is reused for several fence keys. |
| `zoomable` | `boolean` | `false` | Enable the zoom/pan viewport. |

## How it works

* **Rendering is client-only** — Mermaid needs a DOM to measure and lay out, so
  nothing renders on the server or before mount. (Wrap it in `<ClientOnly>` in an
  SSR context like VitePress.)
* **Lazy** — Mermaid is dynamically imported on the first diagram, so pages
  without one never pay for it.
* **Cocoar-themed** — design tokens map onto Mermaid's `themeVariables`. Cocoar
  color tokens are `oklch(...)`, which Mermaid's parser can't read, so they're
  normalized to sRGB first (via a 1×1 canvas).
* **Font-safe** — rendering waits for `document.fonts.ready`, so labels aren't
  clipped by boxes that were measured before the web font loaded.
* **Security** — Mermaid runs with `securityLevel: 'strict'`; author diagram text
  is treated as untrusted (HTML in labels is sanitized).
* **Invalid source degrades** to an error box that still shows the raw source —
  it never throws up to the app.

::: tip Many diagrams on one page
Renders are serialized internally — `mermaid.render` shares global state and
isn't concurrency-safe, so several diagrams mounting at once would otherwise
corrupt each other.
:::

## Zoom & pan

With `zoomable`, the diagram sits in a fixed-height viewport with:

* **+ / − / ⤢ buttons** (top-right) — the primary, touch-friendly zoom;
* **Ctrl / ⌘ + wheel** — zoom toward the cursor;
* **drag** — pan (mouse / pen);
* **double-click** — reset.

Plain mouse-wheel scrolling is deliberately **not** captured, so a diagram never
traps the page scroll. On touch, one-finger scrolling still scrolls the page
(zoom via the buttons). Set the viewport height with the `--coar-mermaid-height`
CSS variable (default `420px`):

```css
.my-diagram { --coar-mermaid-height: 600px; }
```

## Theming

Theming is applied automatically from the ambient Cocoar tokens. The mapping is
exported as pure functions if you need to build your own Mermaid config:

| Export | Description |
|---|---|
| `buildMermaidThemeVariables(getToken, resolveColor?)` | Cocoar token getter → Mermaid `themeVariables`. |
| `readCssTokens(el?)` | `getComputedStyle`-backed token getter. |
| `makeCssColorResolver()` | Canvas-backed CSS-color → sRGB resolver (handles `oklch(...)`). |

## In markdown

To render diagrams from ` ```mermaid ` fences inside `<CoarMarkdown>`, don't wire
this component up by hand — install `@cocoar/vue-markdown-mermaid` and pass its
`mermaidFenceRenderers` to the viewer's `fenceRenderers` prop. See
[**Markdown Diagrams**](/components/markdown-diagrams).

---

---
url: /components/script-editor.md
description: >-
  @cocoar/vue-script-editor — Monaco-based TypeScript/JavaScript/JSON editor
  with v-model, custom type definitions, constrained mode with protected lines
  and automatic theming
---

# 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
description: >-
  CoarDataGrid — AG Grid-based data grid with fluent builder API, locale-aware
  column types, wrapper-column decorations and Cocoar theming with dark mode.
---

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

### Dark mode

Dark styles ship with the package. The theme maps AG Grid's variables onto the semantic `--coar-*` tokens (with hardcoded fallbacks), so the grid follows your design-system theme in both modes. Dark values activate via the `.dark-mode` class — on `<html>` or any ancestor (the Cocoar convention, same as `@cocoar/vue-ui`), or directly on the grid element. `[data-theme="dark"]` is **not** a trigger here.

## 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
description: >-
  CoarDataGrid in-cell editing — editable() with per-row predicates, custom Vue
  editors via cellEditorConfig, and onCellValueChanged for committed edits.
---

# 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
description: >-
  CoarDataGrid text column — col.text() edits cells with CoarTextInput via
  CoarTextCellEditor, with placeholder, maxLength, and per-row editable gating.
---

# 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
description: >-
  CoarDataGrid number column — col.number() formats locale-aware and edits with
  CoarNumberCellEditor supporting min/max, decimals, step, and stepper buttons.
---

# 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
description: >-
  CoarDataGrid select column — col.select() renders the matched option label and
  edits via CoarSelect with auto-commit on pick, clearable, searchable, and
  row-aware options.
---

# 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
description: >-
  CoarDataGrid multi-value columns — col.multiSelect() and col.tagSelect() edit
  array cells via CoarMultiSelect or CoarTagSelect, with chips display, search,
  and allowCreate.
---

# 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
description: >-
  CoarDataGrid date columns — col.plainDate/plainDateTime/zonedDateTime render
  Temporal values locale-aware and edit via the matching Cocoar date-time
  picker.
---

# 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
description: >-
  CoarDataGrid checkbox column — col.checkbox() renders a read-only CoarCheckbox
  per cell, with opt-in edit-mode toggling, per-row gating, and indeterminate
  tri-state.
---

# 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
description: >-
  Overview of @cocoar/vue-page-builder, a headless visual page composition
  framework: consumer-defined element registry, portable JSON schemas, shared
  PageConfig for builder and renderer.
---

# Page Builder&#x20;

::: warning Preview
Page Builder is **provisional**. It shipped as GA in 2.17 — that was an
oversight, and 3.0 corrects it: the package is back under the Preview badge
until the authoring model settles. Public API, `PageConfig` and the document
schema may still change in a minor release, and 3.0 itself removed four config
concepts and renamed several more.

Documents are safe across those changes: every schema change ships a migration
that runs on ingest. Pin a version if you depend on the API, and read the
[Authoring contract](./authoring-contract) for what is still open.
:::

`@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, and even **which element types exist** — is defined by the **consumer application**, not the library. Built-in elements are pre-registered definitions on an open [element registry](./custom-elements); consumer apps register their own element types on the same contract.

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

Import the stylesheet once (it carries the builder chrome **and** the renderer's
layout styles — without it, stacks lose their flex layout):

```ts
import '@cocoar/vue-page-builder/styles';
```

::: info Peer dependencies
`@cocoar/vue-page-builder` declares `@cocoar/vue-ui` **and** `@cocoar/vue-localization` as peer dependencies. All builder chrome and the renderer's validation messages resolve through `@cocoar/vue-localization` (keys under `coar.pageBuilder.*`), with built-in English fallbacks — English-only apps need no i18n setup.
:::

```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',
  schemaVersion: 6,
  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/${encodeURIComponent(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. When `config.assetResolver` is set, the renderer falls back to it automatically, so the `:asset-resolver` prop is only needed as an override.

## 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 — built-in types and
   * consumer-registered keys alike. Omit to allow every type.
   * `page` (the root marker) is always implicitly allowed.
   */
  allowedElements?: (ElementType | (string & {}))[]

  /**
   * Consumer-registered element types, merged ADDITIVELY over the built-in
   * set (shadowing a built-in key warns in DEV). One registration serves
   * palette, canvas, inspector and runtime. App-wide defaults can be
   * provided under PAGE_ELEMENT_TYPES_KEY instead; this field wins when both
   * are present. See the Custom elements guide.
   */
  elements?: PageElementRegistry

  /**
   * The data contract behind the page (DTO fields). When present, the
   * builder's Field section offers these instead of a free-text name —
   * filtered per element to the compatible value types — the palette
   * gains a draggable Fields group, and the builder lint flags unknown
   * names, incompatible bindings and missing required fields.
   * See the Field contract section below.
   */
  fields?: PageFieldSpec[]

  /** Allow-listed host context for property bindings, conditions and repeaters. */
  contextFields?: PageContextField[]
  // interface PageContextField {
  //   path: string
  //   type: PageContextValueType
  //   itemFields?: PageContextItemField[]
  //   /** Closed set of values — the condition editor offers them as a dropdown
  //    *  instead of a free-text box. This is how a host view state, tier or
  //    *  status becomes authorable without a second mechanism for it. */
  //   values?: string[]
  // }

  /** Locales offered by the builder for LocalizedValue props. */
  locales?: { id: string; label: string }[]
  defaultLocale?: string

  documentLimits?: { maxNodes?: number; maxDepth?: number }

  /**
   * Allow binding names outside `fields`. Defaults to false — with a
   * contract, authors pick from it.
   */
  allowCustomFields?: boolean

  /**
   * Hide free value-producing elements from the library and the Inputs
   * entries of the outline's add-child menu — exactly what the field
   * contract replaces. Containers and content/action elements stay available.
   * Pure authoring UI;
   * `allowedElements` remains the boundary for what may be used at all.
   */
  hideElementPicker?: boolean

  /**
   * Action IDs that registry elements with `action: true` 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 — the renderer falls back to this when
   * that prop is absent, so passing the same config to both is enough.
   */
  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>

  /**
   * Resolves an options-source id to the option list of a choice input
   * (select / multi-select / radio-group) — the async sibling of
   * `assetResolver`, for API-backed lists (countries, users, …). A node
   * opts in via its `optionsSourceId` prop; static `options` stay the
   * default and the fallback when this callback is absent.
   */
  optionsSource?: (sourceId: string) => Promise<OptionItem[]>
}
```

### `allowedElements`

Takes built-in types and consumer-registered keys alike. Enforced at **both** layers:

* *Builder*: hidden from the palette and add-child menu; tenants can't insert disallowed types. Nodes of a disallowed type already present in the schema get a validation **error** and a "skipped at runtime" treatment on the canvas; nodes of an *unregistered* type get a **warning** (they stay in the tree losslessly), so authors learn about both before saving.
* *Renderer*: disallowed nodes are skipped at render time (with one `console.warn` per type) even if they appear in hand-written or tampered JSON. This is the security boundary.

The gate also applies to the renderer's **value model**, not just rendering: disallowed subtrees contribute no default values and their fields never block validation — an invisible `required` field can't permanently veto a validating button.

```ts
allowedElements: [
  'stack', 'card', 'section', 'divider',
  'heading', 'paragraph',
  'text-input', 'checkbox', 'button', 'link', 'image',
  'acme-rating',   // a consumer-registered key from config.elementTypes
],
```

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

### `elements` — custom element types

The element set is open: one `definePageElement()` definition registers a component defined entirely in **your app** as a first-class element — it appears in the palette, canvas, inspector, preview and value model exactly like a built-in. Registrations merge **additively** over the built-ins; keys are lowercase kebab-case (`^[a-z][a-z0-9-]*$`) and a vendor prefix is recommended:

```ts
import { definePageElement, type PageConfig } from '@cocoar/vue-page-builder';
import RatingRenderer from './RatingRenderer.vue';

const config: PageConfig = {
  elements: {
    'acme-rating': definePageElement({
      renderer: RatingRenderer,                      // receives { node }
      value: { isEmpty: (v) => !v || Number(v) === 0 }, // participates in the value model
    }),
  },
  allowedElements: ['stack', 'heading', 'text-input', 'button', 'acme-rating'],
};
```

Unregistered types degrade **losslessly**: kept in the tree and in the JSON tab, flagged in the builder, skipped at runtime with one console warning per type, and excluded from the value model so they can never block a submit. The full contract — builder half (palette label, canvas preview, inspector, lint), `usePageElement()` renderer context, app-wide registration via `PAGE_ELEMENT_TYPES_KEY` — is covered in the [Custom elements guide](./custom-elements).

### Field contract

In practice a page is rarely a free-form document — it usually **projects a DTO**: the login request, the profile record, the ticket form. The field names and their types are known up front, and authors should *pick* from them instead of inventing names the backend then has to guess at. `config.dataContract` declares that contract:

```ts
const config: PageConfig = {
  fields: [
    { name: 'username',   valueType: 'string',  label: 'Username', required: true },
    { name: 'password',   valueType: 'string',  label: 'Password', required: true, defaultElement: 'password-input' },
    { name: 'rememberMe', valueType: 'boolean', label: 'Remember me' },
    { name: 'age',        valueType: 'number',  label: 'Age' },
    { name: 'dueUntil',   valueType: 'date',    label: 'Due until' },
  ],
};
```

Each `PageFieldSpec` is `{ name, valueType, label?, required?, defaultElement? }`: `name` is the `ActionValues` key (the DTO property), `valueType` decides which elements can edit the field, `label` is carried onto the element on binding, `required` sets `validation.required` on binding and keeps a root-level warning alive while the field is missing from the page, and `defaultElement` picks the element the field-first flow creates.

#### Value types and compatibility

Compatibility is an exact token match between the field's `valueType` and the element definition's `ElementValueSpec.types`. `PageValueType` is an **open** token union — the built-in tokens below plus any consumer token (`'geo'`, `'money'`, …):

| `valueType` | Compatible built-in elements |
|-------------|------------------------------|
| `string` | `text-input`, `password-input`, `select`, `radio-group`, `otp-input` |
| `boolean` | `checkbox`, `switch` |
| `number` | `number-input` |
| `string[]` | `multi-select` |
| `date` | `date-input` |
| `datetime` | `datetime-input` |

Consumer elements participate through the same declaration: a rating element whose definition says `value: { types: ['number'] }` becomes a representation for `number` fields — compatibility is registry-driven, not a central table. A value spec **without** `types` is unconstrained (compatible with every field), so consumer elements that don't declare are never falsely blocked. See [Custom elements](./custom-elements#_3-value-model-participation).

#### Two authoring flows

**Element-first** — drop any element, then bind it. With a contract, the Field section's *Field name* control becomes a select over the **compatible** fields only (a `text-input` never offers `rememberMe`). Binding takes the contract label along — never overwriting a label the author already edited — and sets `validation.required` for contract-required fields. Clearing the select unbinds; a bound name outside the contract stays visible as `(custom)`.

**Field-first** — with a contract the palette gains a third group, **Fields**: one draggable card per contract field, with a type icon, the contract label and a `*` for required fields; a card greys out once its name is bound anywhere on the page. Dropping a card creates the field's default element — `field.defaultElement` when registered, else the first compatible value element in registry order — **pre-bound**: name set, contract label carried into the props bag (when the element has a `label` prop at all), `validation.required` applied.

#### Representation switch

Same field, different element: the Field section gains an **Element** select listing the representations that can edit the bound field's value type (unbound: any type the current element declares) — filtered to placeable, allow-listed elements and hidden when fewer than two remain. Switching converts the node **in place**: it keeps `id` (selection follows), `name`, `defaultValue`, `validation`, `style` and the label, while the rest of the props bag restarts from the target element's defaults. One undoable step — username as `text-input` ⇄ `password-input` ⇄ `select` ⇄ `otp-input`, one click each.

#### Contract lint

Three rules join [builder-side validation](./coar-page-builder#builder-side-validation):

* a bound name **outside the contract** is an *error* — unless `allowCustomFields` is set,
* a **type-incompatible** binding (say, a `checkbox` bound to a `string` field) is an *error*,
* a **required contract field missing** from the page is a *warning* on the root node.

#### Strict by default

`allowCustomFields` defaults to `false`: with a contract, binding is select-only, and freshly dropped value elements start **unbound** instead of minting a `field_*` name the lint would immediately flag — the author picks a contract field. Setting `allowCustomFields: true` relaxes all of it: the Field section adds a free-text *Custom name* input, fresh elements mint names again, and the unknown-name lint rule stands down.

#### `allowedElements` governs everything

The allow-list composes with the contract at every seam: a field's default element (field-first drop) and the representation switcher only ever offer **allowed** elements. Drop `password-input` from `allowedElements` and a `string` field can no longer be represented as a password input — the field's `defaultElement` falls back to the first compatible *allowed* element, and a field with no allowed representation greys out in the palette.

#### Fields-only authoring

Set `hideElementPicker: true` to remove free value-producing elements from the right-hand **Elements** library and from the outline's **Inputs** add-child group — exactly the entries the field contract replaces. Fields then come exclusively from dragging contract cards. **Containers** and content/action elements (headings, notes, buttons, links, images) stay available because every form needs structure and chrome. Classification is registry-derived from the value spec, so consumer elements sort themselves. This is pure authoring UI — combine it with `allowedElements` when the *rendering* boundary should shrink too.

#### Typed field lists (opt-in)

For a **static** DTO, `defineFields<TDto>()` checks the field list at compile time — names must be DTO properties, value types must fit the property types (string properties admit the `date`/`datetime` tokens, since dates travel as ISO strings):

```ts
interface LoginDto { username: string; password: string; rememberMe: boolean }

fields: defineFields<LoginDto>([
  { name: 'username',   valueType: 'string', required: true },
  { name: 'rememberMe', valueType: 'boolean' },
  // { name: 'usernme', valueType: 'string' },   // ✗ compile error — not a DTO property
  // { name: 'rememberMe', valueType: 'string' } // ✗ compile error — boolean property
])
```

It is pure opt-in sugar with zero runtime cost: the result is a plain `PageFieldSpec[]`, so dynamically grown DTOs keep working — either skip the helper entirely, or mix: `[...defineFields<LoginDto>([...]), ...dynamicExtraFields]`.

#### Authoring-only by design

The contract constrains **authoring only**. Binding is plain `node.name` — persisted schemas stay self-contained, render without the contract, and a document authored under one contract remains a valid document everywhere. The renderer never consults `fields`; `allowedElements` remains the security boundary.

### `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;
      the renderer falls back to it when its :asset-resolver prop is absent. */
  assetResolver: (id) => `https://cdn.example.com/t/${tenantId}/${encodeURIComponent(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;
  },
};
```

::: warning Validate the asset id
`assetResolver` receives whatever `assetId` string sits in the schema — including hand-edited JSON. Encode it (`encodeURIComponent`) or allowlist it (e.g. `/^[A-Za-z0-9_-]+$/`) before splicing it into a URL, or a crafted id like `../other-tenant/logo` walks out of your tenant prefix.
:::

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 and flags; renderer skips, with one `console.warn` per type). The renderer is the hard boundary — even tampered JSON cannot smuggle in disallowed types, and disallowed subtrees are excluded from the value model too (no defaults, no validation veto).

**Actions** — every registry element that declares `action: true` stores the shared optional `ActionProps` contract; built-in buttons and links use it too. The builder supplies one Action + JSON key/value editor with an `fx` switch per value, and the renderer only invokes handlers from the consumer-provided `actions` map — action ids are inert strings. Handler payload precedence is form values < resolved per-key `actionValues` < the legacy bound `actionValue`; only JSON-safe explicit values cross the boundary. Per-key bindings may read controlled context, customer Page State, form fields, named Repeat selections, or the current Repeat item/index. When `config.availableActions` is set, the builder also constrains the Action input to a labeled dropdown. One qualification to "nothing executable lives in the schema": `validation.pattern` is a tenant-authored regular expression that *is* evaluated at render time. It is compiled safely — an invalid pattern becomes an inert rule with a single `console.warn` — and anchored to match the full string, like the HTML `pattern` attribute.

**Images** — `image` nodes store an `assetId` reference, never a raw URL. The renderer calls `assetResolver(id)` at render time. The "tenants cannot reference external domains" guarantee is therefore exactly as strong as **your** `assetResolver` — validate or encode the id before building a URL (see the warning above). 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' },
    ],
    // Allowlist the id — it's tenant-authored schema data, not trusted input.
    assetResolver: (id) =>
      /^[A-Za-z0-9_-]+$/.test(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>
  <!-- No :asset-resolver needed — the renderer falls back to config.assetResolver. -->
  <CoarPageRenderer
    v-if="schema"
    :schema="schema"
    :config="config"
    :actions="actions"
  />
</template>
```

### Notes for the IDP wiring

* **Schema migration** — the builder normalises schemas at **every entry point**: the initial `v-model` value, external `v-model` replacement, and the JSON tab's Apply. Legacy `column`/`row` containers migrate to `stack`, v1 flat documents get their `props` bags, non-`page` roots get wrapped in a `page`, missing or duplicate node ids are repaired, missing `children` arrays / `props` bags and out-of-range heading levels are healed. The runtime renderer additionally runs both migrations on the fly, so old saved schemas keep rendering even without a round-trip through the builder. To run the same migration server-side before persisting, use the exported helpers: `normalizePageSchema(value)` returns `{ schema, issues, changed }`; `migrateLegacyTypes`, `migrateV1PropsBag` and `KNOWN_ELEMENT_TYPES` are exported alongside it.
* **`schemaVersion`** — new roots are stamped with `schemaVersion: 6`. Version 4 keeps the v2 props-bag and v3 runtime-composition grammar and adds a stable page-wide `name` to every element for Element Code (the same name is the form/DTO key for value elements). Version 5 adds builder-only origin metadata for reusable, versioned compositions. Version 6 renames the repeat's `props.source` to `props.contextPath`, so `source` means one thing everywhere. Older documents are normalized deterministically. Persist the version as-is.
* **JSON Apply is gated by severity** — structural **errors** (non-object nodes — data would be dropped) reject the Apply with a message; nothing broken reaches your `v-model`. **Warnings** (healed or lossless findings — including *unknown element types*, which stay in the tree losslessly) apply anyway and are surfaced inline, so documents using newer or unregistered element types remain editable.
* **Validation** — builder validation flags authoring mistakes but never blocks saving: a button/link without an action, or with an action id outside `availableActions`, or an *unregistered* element type, is a *warning*; duplicate field names, missing image asset ids, invalid `validation.pattern`, and disallowed element types are *errors*. If you need hard guarantees, validate server-side before persisting (e.g., reject if any image node has an empty `props.assetId`). At runtime, a `validates: true` button stays **clickable** while the form is invalid — clicking it marks every field touched and reveals all errors instead of running the action; it only disables while an async `onValidate` is in flight. Cross-field or server-side checks (e.g., "email domain not allowed for this tenant") go through the renderer's `:on-validate` prop: it runs at submit time after the declarative rules pass, may return a `Promise` of `{ fieldName: errorMessage }`, a non-empty result blocks the action, and editing a field clears its server error. See [CoarPageRenderer](./coar-page-renderer).
* **CSP** — image URLs come from `assetResolver`, so your CDN domain needs to be in `img-src`. Action IDs and labels are inert strings; the one tenant-authored value evaluated at render time is `validation.pattern`, which is compiled safely and anchored (see [Security Model](#security-model)).
* **Full-screen / centering** — the renderer fills and measures its host width. To center content on a full-height screen, set the `page` node's `minHeight: '100dvh'` + `justify: 'center'` + `align: 'center'`. 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 |
| **GA hardening** | Correctness & data-safety fixes (schema normalization at every entry point, gated JSON Apply, `crypto.randomUUID` ids, `schemaVersion` stamp, safe `pattern` compile) · pointer-events DnD (mouse + touch/pen long-press, outline drag-to-reorder) · validation UX (clickable validating buttons, submit-time async `onValidate`) · outline ARIA tree + scoped keyboard shortcuts · duplicate / select-options / default-value editors · i18n (`coar.pageBuilder.*` via `@cocoar/vue-localization`) | ✅ Done |
| **Element registry** | Unified props-bag wire format (introduced in v2, current `schemaVersion: 6`, transparent older-document normalization) · open [consumer-registered element types](./custom-elements) (`config.elementTypes`, `definePageElement`, `usePageElement`) · lossless degradation of unregistered types · severity-gated JSON Apply · renderer `initialValues` | ✅ Done |
| **Submit lifecycle & dynamics** | Async actions (`isSubmitting`, spinner, reentry guards) · [form-level error channel](./coar-page-renderer#async-actions-the-form-level-error-channel) (`_form`, banner, `#form-error` slot) · [Enter-to-submit](./coar-page-renderer#enter-to-submit) · built-in email format check · host form API (`update:values`, `values` / `isDirty` / `reset`) · [`visibleWhen`](./coar-page-renderer#conditional-visibility-visiblewhen) conditional visibility · [`optionsSource`](./coar-page-renderer#dynamic-options-optionssource) dynamic option lists | ✅ Done |
| **5b — Style editor (visual)** | Spacing sliders + colour pickers (rolls into the tenant theming track) | Planned |
| **Runtime composition v4** | Mobile-first responsive overrides · safe context/state/item bindings · Page State and per-element code · key-based localization · generic repeaters and selected-key outputs · feedback zones · document-limit fallback validation | ✅ Done |
| **5+ — Schema versioning** | Formal multi-step migration framework beyond the current deterministic normalization to v5 | Planned |

---

---
url: /components/page-builder/coar-page-builder.md
description: >-
  CoarPageBuilder visual editor: outline and properties inspector, drag-and-drop
  canvas, searchable element library and reusable compositions, emitting a
  PageNode JSON schema via v-model.
---

# `<CoarPageBuilder>`&#x20;

The visual-editor half of `@cocoar/vue-page-builder`. It renders a three-panel layout: the vertically split Outline and Properties inspector on the left, the canvas in the centre, and a searchable element library on the right. It 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.

::: tip Stylesheet
Import `@cocoar/vue-page-builder/styles` once in your app — it carries the entire builder chrome (panels, canvas, palette). Without it the builder renders unstyled.
:::

## Playground

A live builder with a small starting schema and a restricted `allowedElements` list — note that the palette and the outline's "Add child" menu only offer the permitted types. Drag palette cards onto the canvas, reorder rows in the outline via their grip handles, and try `Ctrl+Z` after an edit. The builder fills its host element, so give it a bounded height.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `modelValue` / `v-model` | `PageNode` | empty `page` | The page schema. Bound two-way; every edit updates the ref. Every tree entering from **outside** — the initial value, a later external replacement, or an initially-`undefined` ref that is filled once an async load resolves — passes through the same normalization as the JSON tab's Apply: legacy `column`/`row` containers become `stack`, v1 flat documents get their `props` bags, a non-`page` root is wrapped in one, missing/duplicate node ids are repaired with fresh `crypto.randomUUID` ids, missing `children` arrays and `props` bags are added, every element receives a unique name, and documents are stamped `schemaVersion: 6`. Repairs log a DEV-only console warning. |
| `config` | [`PageConfig`](./#pageconfig-the-consumer-contract) | — | Allowed elements, [consumer element registrations](./custom-elements), actions, runtime-context contracts, locales, limits and asset callbacks. Pass the same value to the renderer. |
| `previewContext` | `Record<string, unknown>` | — | Safe host data for the embedded preview. Only paths declared by `config.contextFields` are readable. |
| `previewInitialValues` | `ActionValues` | — | Field values the embedded preview starts from, merged **over** the schema's own `defaultValue`s exactly as at runtime. The edit-form case, and the case where the host computes a default the author did not write (a per-tenant "remember me" setting). Replacing the object re-seeds the preview. |
| `previewLocale` | `string` | — | Initial locale for localized schema values in the preview. |
| `previewTheme` | `CoarTheme` | — | Host-resolved brand primitives applied through the same `CoarThemeScope` used at runtime. Scoped to the Preview canvas; builder chrome and dialogs are unaffected. |
| `previewThemeMode` | `'auto' \| 'light' \| 'dark'` | `'auto'` | Colour mode for the preview theme. Auto follows the surrounding application/OS mode. |
| `previewActions` | `Record<string, ActionHandler>` | — | Optional live handlers for action testing in the embedded preview. |
| `previewFallbackSchema` | `PageNode` | — | Host-owned fallback used by the preview when the customized document violates its contract. |
| `previewExpressionValues` | `RuntimeExpressionValues` | — | Optional precomputed expression values for the embedded preview. Source code is never evaluated in the builder's main thread. |
| `authoringMode` | `'properties' \| 'code'` | `'properties'` | In `code` mode the inspector stays structural and Page/Element Code is authoritative for configurable properties. |
| `previewRuntimeHost` | `PageRuntimeHost` | no-capability host | Application capability catalogue for the Builder-owned isolated preview runtime. |
| `previewRuntimePageId` | `string` | schema id | Stable page identity used by preview capability grants and diagnostics. |
| `previewRuntimeTenantId` | `string` | — | Optional tenant identity supplied to preview capability grants. |
| `pageCodeExtraLibs` | `CoarScriptEditorExtraLib[]` | `[]` | Host capability declarations added to Monaco IntelliSense for Page and Element Code. |
| `compositionRepository` | `PageCompositionRepository` | — | Optional host-owned repository of reusable, immutable, versioned subtrees. Supplying it enables the Compositions library and management tab. |
| `compositionManagement` | `'inline' \| 'consume'` | `'inline'` | Whether definitions may be created/published inside this page builder or are managed by a separate host-owned composition editor. |

## Events

| Event | Payload | Description |
|-------|---------|-------------|
| `update:modelValue` | `PageNode` | Emitted after every schema edit for `v-model`. |
| `preview-values` | `ActionValues` | Current field-value snapshot from the embedded preview. |
| `preview-runtime` | `{ fields, form }` | Reactive preview scope for host diagnostics; `form` contains valid, dirty, validating and submitting flags. |
| `open-composition` | `PageCompositionReference` | Requests host navigation to the independently managed composition definition and exact pinned version. |
| `validation` | `AuthoringFinding[]` | The authoring findings the builder draws in its own outline and props panel. Fires on mount and whenever the set changes in content, so an edit that leaves the findings alone stays quiet. The payload is a copy — mutating it cannot corrupt the builder. |

## Reaching the validation findings

Two layers answer two different questions, and mixing them up leads to either a
save button that never enables or a document that fails at activation.

| | Question | API |
|---|---|---|
| **Authoring findings** | "What should I tell the author to fix?" | `@findings` / `useAuthoringFindings()` |
| **Activation contract** | "May this document go live?" | [`validatePageDocument()`](./idp-integration) |

The authoring layer is the broader one — it includes hints the runtime does not
care about (an action that is not in `availableActions`, a required contract
field nobody put on the page) and it *contains* the hard failures of the
activation contract, so gating a save on `severity === 'error'` is sound.

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

const schema = ref<PageNode>();
const findings = ref<AuthoringFinding[]>([]);
const blocking = computed(() => findings.value.filter((f) => f.severity === 'error'));
</script>

<template>
  <CoarPageBuilder v-model="schema" :config="config" @findings="findings = $event" />
  <button :disabled="blocking.length > 0" @click="save">Save</button>
  <ul>
    <li v-for="(finding, i) in blocking" :key="i">{{ finding.message }}</li>
  </ul>
</template>
```

Each finding carries the `nodeId` it belongs to and, where the problem is a
specific property, the `field` — enough to build your own "jump to node" list.

Outside a mounted builder — a document dashboard, a bulk migration check — call
the composable directly in a component `setup()`. It resolves the element
registry reactively, honouring `config.elementTypes` and an app-level
`PAGE_ELEMENT_TYPES_KEY` provide alike:

```ts
const { findings, byNodeId } = useAuthoringFindings(schema, config);
```

## Features

* **Searchable element library** — the right panel groups draggable cards under **Fields** (first when a field contract exists), **Containers**, **Elements** and, when a repository is supplied, **Compositions**. Groups are independently collapsible and a single search filters all of them, so repositories with dozens of definitions remain manageable. Registry entries come from built-ins plus [`config.elementTypes`](./custom-elements), filtered by `config.allowedElements`. `hideElementPicker` removes value-producing entries from **Elements** and from the outline's separate Inputs add-child group; containers and content/action elements remain available.
* **Pointer-based drag & drop** — built on pointer events rather than HTML5 drag events, so it works with mouse, touch **and** pen (tablet-first). Mouse drags start after a 5 px movement threshold, so plain clicks keep working; touch/pen drags arm after a 300 ms long-press. A ghost preview follows the pointer, scroll containers auto-scroll near their edges, and `Escape` cancels a drag in flight.
* **Outline tree** — hierarchical node list with selection and real drag-to-reorder: every row except the root carries a grip handle, thin drop bars light up between rows while dragging, and container rows highlight for drop-**into**. Per-row actions: move up/down, duplicate, delete, plus an inline "Add child" menu. Stacks display "Column" or "Row" based on direction. Warning icons mark nodes with validation issues (hover for the full message).
* **Canvas** — per-element preview components with dashed selection borders; each node's type tab doubles as its drag handle. A registered element without its own preview renders as a neutral icon+label chip; unregistered or disallowed element types get a red "skipped at runtime" treatment, so the canvas never pretends the runtime renderer will show them. Switches to live preview in the **Preview** tab and to a paste-and-apply JSON editor in the **JSON** tab.
* **Properties panel** — the lower-left inspector is resolved from the element registry: each definition ships its own inspector component. Value-producing elements additionally get a host-owned **Field** section (field name, Required, default value — with a per-element default-value editor when the definition provides one, e.g. "Checked by default" for checkboxes). With a [field contract](./#field-contract), the field-name input becomes a select over the contract fields the element can edit (clearing it unbinds; binding carries the contract label and required along), an **Element** select switches the node to another representation of the same field, and `allowCustomFields` adds a free-text custom-name input. Every non-page node also gets a host-owned **Visibility** section authoring [`visibleWhen`](./coar-page-renderer#conditional-visibility-visiblewhen): a "Visible when" select over the page's named fields plus a typed `equals` editor (checked/unchecked for boolean controllers, the option list for choice controllers, free text otherwise; a JSON-authored `in` condition is surfaced read-only) — conditional nodes carry an **eye marker** on their canvas tab. Selecting the page root shows a **Page** section with the [Enter-to-submit](./coar-page-renderer#enter-to-submit) checkbox; the button inspector offers the matching "Default button" checkbox. The choice inputs' inspectors take an **Options source ID** for [API-backed option lists](./coar-page-renderer#dynamic-options-optionssource). A linked composition root additionally shows its name, pinned version, version selector, update-to-latest, detach and open actions. Validation issues for the selected node are surfaced at the top with colored banners. Option-based inputs share an **options editor** (add / remove / reorder options; a removed option clears a default that pointed at it).
* **Reusable compositions** — repository-backed definitions appear beside normal elements and materialize through the same drag-and-drop pipeline. No runtime wrapper or persisted composition element type is introduced: the inserted subtree stays ordinary PageBuilder JSON plus builder-only origin metadata. Version changes are explicit; runtime compilation removes repository metadata and needs no repository access.
* **Duplicate** — available as an outline row action and a canvas button. Deep-clones the subtree with fresh ids on every node; colliding field names are flagged by the duplicate-name validation.
* **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 authoring and preview** — Mobile-first base styles plus Phone, Tablet and Desktop overrides. The exact Compact 320×568, Phone 390×844, Tablet 768×1024 and Desktop 1280×800 frames use the same resolver as runtime; each override can be reset independently. `hidden` removes the node from rendering, validation and action payloads at that breakpoint. Both the Style section and the code-mode **Quick Properties** show the value that applies at the breakpoint being authored, not the base — a node hidden on Compact and revealed on Desktop reads as visible while you are on Desktop. Where that value came from an override, the Quick Property carries a small breakpoint chip, because editing it writes one assignment that applies everywhere and would flatten the difference.
* **Runtime bindings and localization** — bind supported element props and individual `actionValues.<key>` entries to allow-listed context paths, customer Page State, named form fields/selections, or the current repeater item/index. Safe expressions use the same targets. Properties explicitly registered as `valueKind: 'localized-text'` reference stable keys; the central **Translations** tab edits the page-owned catalogue for every configured locale and flags unused keys. Legacy embedded `LocalizedValue` objects remain readable.
* **Conditions, repeaters and feedback zones** — `visibleWhen` supports field/context/state/item sources and bounded `all`/`any` composition. A generic `repeat` renders a child template for an allow-listed context array and can emit a selected-key array under any configured output name. A `feedback` node places form errors, status, loading or authored messages inside the layout.
* **Host-supplied preview inputs** — the embedded preview and its sandbox session run against `previewContext` and `previewLocale`. Until the host supplies whatever its own `config` declares (`contextFields`, `locales`), the preview stays off and says so rather than rendering against invented data. Swapping `previewContext` restarts the sandbox against the new contract, so a host that wants an “empty / typical / 50 items” picker builds it in its own chrome and simply binds the chosen sample.
* **Page Root Code** — selecting the page root exposes a separate constrained code editor. It can reactively configure only `page.style`, `page.responsive`, and `page.enterSubmits`; structure, children, ids, types and names remain visual-builder owned. Shared mutable data stays in the independent Page State editor.
* **Undo / redo** — `Ctrl+Z` / `Ctrl+Y` (or `Cmd+Z` / `Cmd+Shift+Z`), also via toolbar buttons.
* **Scoped keyboard shortcuts** — undo/redo and `Delete` / `Backspace` (removes the selected node) only act while focus is inside *that builder instance*, and never while focus is in an editable target: the JSON textarea, props-panel inputs and your app's own form fields keep their native undo and delete behavior.
* **Keyboard navigation** — the outline is an ARIA tree (`role="tree"` / `role="treeitem"` with `aria-level`, `aria-selected`, `aria-expanded`) with a roving tabindex: `Arrow Up` / `Arrow Down` / `Home` / `End` move focus, `Enter` / `Space` selects the focused row. Canvas nodes are focusable too; `Enter` / `Space` selects the focused node.

## JSON tab

The JSON tab shows the current schema and lets you paste and **Apply** a replacement. Apply is gated by **issue severity** — the pasted tree runs through the same normalization pass the v-model entry points use:

* **Errors block Apply** — structural damage where data would be dropped: non-object nodes (and non-JSON input). The inline message lists what is wrong; nothing reaches the working tree (or, through `v-model`, your storage).
* **Warnings apply anyway** and are surfaced next to the Apply button: everything healed in place or lossless — legacy `column` / `row` containers (→ `stack`), v1 flat nodes (→ `props` bags), a non-`page` root (wrapped in a `page`), missing or duplicate node ids (fresh ids), missing or non-object `props` bags, out-of-range or non-numeric heading levels, non-array `children` (reset), `children` on a non-container, and **unknown element types**.

Unknown element types are deliberately *not* rejected: a document from a newer library version — or one using [consumer elements](./custom-elements) this instance hasn't registered — stays pasteable and round-trips **losslessly** (the nodes stay in the tree; the runtime renderer skips them with one console warning per type).

A successful Apply lands as a single undoable step; when there were no findings at all, the builder switches back to the Editor tab.

::: info Exported helpers
The same machinery is exported for hosts that persist or migrate schemas themselves: `normalizePageSchema(value)` → `{ schema, issues, changed }` (issues carry `severity: 'error' | 'warning'`), `migrateLegacyTypes(node)`, `migrateV1PropsBag(node)`, and the `KNOWN_ELEMENT_TYPES` set (built-ins only). See [Legacy schemas & normalization](./coar-page-renderer#legacy-schemas-normalization).
:::

## Builder-side findings

The builder derives its authoring findings reactively and surfaces them 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 finding for that node.

Built-in rules:

| Rule | Severity |
|------|----------|
| Element type is not registered (skipped at runtime, but kept losslessly in the tree) | warning |
| Type not in `config.allowedElements` (skipped at render time) | error |
| Any registry element with `action: true` has no Action | warning |
| Action ID is not in `config.availableActions` (only checked when that list is non-empty) | warning |
| Action values are not JSON-safe, or the dynamic action-value key is empty/reserved | error |
| `validation.pattern` does not compile as a regular expression | error |
| Image has no Asset ID | error |
| Two named inputs share the same `name` | error |
| Bound field name is not in the [field contract](./#field-contract) (`config.dataContract` set, `allowCustomFields` off) | error |
| Element cannot edit its bound contract field's value type | error |
| Required contract field is missing from the page (reported on the root node) | warning |
| `visibleWhen` is malformed (node stays always visible) | warning |
| `visibleWhen` references a field that is not on the page | warning |
| `visibleWhen` chain is circular (incl. self-reference and loops through ancestor containers) — fields can lock each other hidden | warning |
| `visibleWhen.equals` targets a multi-value (`string[]`) field — the condition can never match | warning |
| Multiple buttons claim `default` — Enter fires only the first in tree order | warning |
| Field name is reserved (`__proto__`, `constructor`, `prototype`) — excluded from the value model | error |
| `optionsSourceId` is set but `config.optionsSource` is not configured | warning |

Element definitions can contribute their own findings through the definition's `builder.lint` hook — they are merged into the same outline/props-panel surfaces with their declared severity (see [Custom elements](./custom-elements)).

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

## Per-element architecture

Every element type — built-in or consumer-registered — is **one registry definition** (`definePageElement`): a runtime renderer plus optional value spec, canvas preview, inspector, default-value editor and lint hook. Built-ins live one folder per element inside the package and are pre-registered on the same contract consumers use:

```
packages/page-builder/src/elements/
├── registry.ts             ← contract types · definePageElement · additive merge
├── builtins.ts             ← the pre-registered built-in registry
├── heading/
│   ├── index.ts            ← the definition (renderer + builder halves)
│   ├── HeadingRenderer.vue
│   ├── HeadingPreview.vue
│   └── HeadingInspector.vue
├── text-input/
└── …
```

`BuilderPropsPanel.vue` is a thin host shell: it resolves the selected node's definition from the merged registry and renders `<component :is="def.builder.inspector" :node :patch />` between the host-owned **Field** and **Style** sections. The palette, add-child menu, canvas previews and outline icons all derive from the same registry — adding an element type is a single definition, **no central files are touched**. Consumer apps register theirs via `config.elementTypes`; the shared `OptionsEditor` component is exported for reuse in consumer inspectors. See the [Custom elements guide](./custom-elements).

## Pairing with the renderer

The builder's Preview tab uses `<CoarPageRenderer>` internally with the same `config` — the renderer falls back to `config.assetResolver` on its own, 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).

## i18n Keys

All builder chrome — and the runtime renderer's validation messages — resolve through [`@cocoar/vue-localization`](/foundations/localization/translations) (a peer dependency) with keys under `coar.pageBuilder.*`. English fallbacks are built in, so apps without a translation setup render English. Values in `{braces}` are interpolation parameters.

### Chrome (tabs, toolbar, panels, preview widths)

| Key | Default (English) |
|-----|-------------------|
| `coar.pageBuilder.chrome.outline` | `'Outline'` |
| `coar.pageBuilder.chrome.collapseOutline` | `'Collapse outline'` |
| `coar.pageBuilder.chrome.expandOutline` | `'Expand outline'` |
| `coar.pageBuilder.chrome.collapseProperties` | `'Collapse properties'` |
| `coar.pageBuilder.chrome.expandProperties` | `'Expand properties'` |
| `coar.pageBuilder.chrome.tabEditor` | `'Editor'` |
| `coar.pageBuilder.chrome.tabPreview` | `'Preview'` |
| `coar.pageBuilder.chrome.tabJson` | `'JSON'` |
| `coar.pageBuilder.chrome.undo` | `'Undo (Ctrl+Z)'` |
| `coar.pageBuilder.chrome.redo` | `'Redo (Ctrl+Y)'` |
| `coar.pageBuilder.chrome.jsonHint` | `'Paste or edit JSON, then click Apply'` |
| `coar.pageBuilder.chrome.jsonApply` | `'Apply →'` |
| `coar.pageBuilder.chrome.previewWidth` | `'Preview width'` |
| `coar.pageBuilder.chrome.previewDesktop` | `'Desktop'` |
| `coar.pageBuilder.chrome.previewFullTitle` | `'Full width'` |
| `coar.pageBuilder.chrome.previewTablet` | `'Tablet · 768'` |
| `coar.pageBuilder.chrome.previewTabletTitle` | `'768px'` |
| `coar.pageBuilder.chrome.previewMobile` | `'Mobile · 375'` |
| `coar.pageBuilder.chrome.previewMobileTitle` | `'375px'` |

### Shared row actions

| Key | Default (English) |
|-----|-------------------|
| `coar.pageBuilder.common.moveUp` | `'Move up'` |
| `coar.pageBuilder.common.moveDown` | `'Move down'` |
| `coar.pageBuilder.common.duplicate` | `'Duplicate'` |
| `coar.pageBuilder.common.delete` | `'Delete'` |

### Outline

| Key | Default (English) |
|-----|-------------------|
| `coar.pageBuilder.outline.treeLabel` | `'Page structure'` |
| `coar.pageBuilder.outline.addChild` | `'Add child'` |
| `coar.pageBuilder.outline.column` | `'Column'` |
| `coar.pageBuilder.outline.row` | `'Row'` |
| `coar.pageBuilder.outline.validationIssues` | `'Validation issues'` |

### Palette

| Key | Default (English) |
|-----|-------------------|
| `coar.pageBuilder.palette.containers` | `'Containers'` |
| `coar.pageBuilder.palette.inputs` | `'Inputs'` |
| `coar.pageBuilder.palette.elements` | `'Elements'` |
| `coar.pageBuilder.palette.fields` | `'Fields'` |
| `coar.pageBuilder.palette.dragToAdd` | `'Drag to add {label}'` |
| `coar.pageBuilder.palette.fieldBound` | `'Already on the page'` |
| `coar.pageBuilder.palette.fieldNoElement` | `'No compatible element available'` |

### Canvas

| Key | Default (English) |
|-----|-------------------|
| `coar.pageBuilder.canvas.emptyContainer` | `'Empty {type} — drop something here'` |
| `coar.pageBuilder.canvas.unknownType` | `'Unknown type "{type}" — skipped at runtime'` |
| `coar.pageBuilder.canvas.notAllowed` | `'Not in allowedElements — skipped at runtime'` |
| `coar.pageBuilder.canvas.visibleWhen` | `'Shown conditionally — depends on "{field}"'` |

### Element type labels

Used by the palette, the outline's add-child menu and the canvas type tabs. These are the built-in elements' `label` keys; consumer-registered elements carry their own `label: { key, fallback }` in the element definition, so their keys live in the consumer's namespace, not under `coar.pageBuilder.*`.

| Key | Default (English) |
|-----|-------------------|
| `coar.pageBuilder.type.page` | `'Page'` |
| `coar.pageBuilder.type.stack` | `'Stack'` |
| `coar.pageBuilder.type.card` | `'Card'` |
| `coar.pageBuilder.type.section` | `'Section'` |
| `coar.pageBuilder.type.divider` | `'Divider'` |
| `coar.pageBuilder.type.spacer` | `'Spacer'` |
| `coar.pageBuilder.type.heading` | `'Heading'` |
| `coar.pageBuilder.type.paragraph` | `'Paragraph'` |
| `coar.pageBuilder.type.note` | `'Note'` |
| `coar.pageBuilder.type.image` | `'Image'` |
| `coar.pageBuilder.type.link` | `'Link'` |
| `coar.pageBuilder.type.button` | `'Button'` |
| `coar.pageBuilder.type.textInput` | `'Text Input'` |
| `coar.pageBuilder.type.passwordInput` | `'Password'` |
| `coar.pageBuilder.type.numberInput` | `'Number Input'` |
| `coar.pageBuilder.type.checkbox` | `'Checkbox'` |
| `coar.pageBuilder.type.switch` | `'Switch'` |
| `coar.pageBuilder.type.select` | `'Select'` |
| `coar.pageBuilder.type.multiSelect` | `'Multi Select'` |
| `coar.pageBuilder.type.radioGroup` | `'Radio Group'` |
| `coar.pageBuilder.type.dateInput` | `'Date'` |
| `coar.pageBuilder.type.dateTimeInput` | `'Date & Time'` |
| `coar.pageBuilder.type.otpInput` | `'OTP Input'` |

### Properties panel

The host-owned **Field** section (name / required / default value, shown for every value-producing element) uses `props.fieldName`, `props.required` and `props.defaultValue`.

| Key | Default (English) |
|-----|-------------------|
| `coar.pageBuilder.props.panelTitle` | `'Properties'` |
| `coar.pageBuilder.props.emptyTitle` | `'No node selected'` |
| `coar.pageBuilder.props.emptyHint` | `'Click a node in the outline or canvas to edit it.'` |
| `coar.pageBuilder.props.text` | `'Text'` |
| `coar.pageBuilder.props.title` | `'Title'` |
| `coar.pageBuilder.props.label` | `'Label'` |
| `coar.pageBuilder.props.level` | `'Level'` |
| `coar.pageBuilder.props.fieldName` | `'Field name'` |
| `coar.pageBuilder.props.fieldUnbound` | `'Not bound'` |
| `coar.pageBuilder.props.customFieldName` | `'Custom name'` |
| `coar.pageBuilder.props.elementType` | `'Element'` |
| `coar.pageBuilder.props.placeholder` | `'Placeholder'` |
| `coar.pageBuilder.props.inputType` | `'Input type'` |
| `coar.pageBuilder.props.rows` | `'Rows'` |
| `coar.pageBuilder.props.min` | `'Min'` |
| `coar.pageBuilder.props.max` | `'Max'` |
| `coar.pageBuilder.props.step` | `'Step'` |
| `coar.pageBuilder.props.decimals` | `'Decimals'` |
| `coar.pageBuilder.props.length` | `'Length'` |
| `coar.pageBuilder.props.mask` | `'Mask input'` |
| `coar.pageBuilder.props.otpType` | `'Character set'` |
| `coar.pageBuilder.props.defaultValue` | `'Default value'` |
| `coar.pageBuilder.props.checkedByDefault` | `'Checked by default'` |
| `coar.pageBuilder.props.onByDefault` | `'On by default'` |
| `coar.pageBuilder.props.required` | `'Required'` |
| `coar.pageBuilder.props.disabled` | `'Disabled'` |
| `coar.pageBuilder.props.options` | `'Options'` |
| `coar.pageBuilder.props.addOption` | `'Add option'` |
| `coar.pageBuilder.props.removeOption` | `'Remove option'` |
| `coar.pageBuilder.props.optionLabelPlaceholder` | `'label'` |
| `coar.pageBuilder.props.optionValuePlaceholder` | `'value'` |
| `coar.pageBuilder.props.action` | `'Action'` |
| `coar.pageBuilder.props.actionHint` | `'Matched against the actions map at render time'` |
| `coar.pageBuilder.props.notConfigured` | `'{id} (not configured)'` |
| `coar.pageBuilder.props.validatesForm` | `'Validates form before firing'` |
| `coar.pageBuilder.props.defaultButton` | `'Default button (Enter submits here)'` |
| `coar.pageBuilder.props.enterSubmits` | `'Enter submits (fires the default button)'` |
| `coar.pageBuilder.props.visibleWhenField` | `'Visible when'` |
| `coar.pageBuilder.props.alwaysVisible` | `'Always visible'` |
| `coar.pageBuilder.props.visibleWhenEquals` | `'equals'` |
| `coar.pageBuilder.props.visibleWhenIn` | `'Multi-value condition (in) — edit it in the JSON tab.'` |
| `coar.pageBuilder.props.visibleWhenArray` | `'"equals" cannot match a multi-value field — author this condition in the JSON tab.'` |
| `coar.pageBuilder.props.checked` | `'checked'` |
| `coar.pageBuilder.props.unchecked` | `'unchecked'` |
| `coar.pageBuilder.props.optionsSource` | `'Options source ID'` |
| `coar.pageBuilder.props.optionsSourceHint` | `'Resolved via config.optionsSource at render time — overrides the static options'` |
| `coar.pageBuilder.props.variant` | `'Variant'` |
| `coar.pageBuilder.props.iconLeft` | `'Icon (left)'` |
| `coar.pageBuilder.props.asset` | `'Asset'` |
| `coar.pageBuilder.props.assetId` | `'Asset ID'` |
| `coar.pageBuilder.props.assetIdHint` | `'Resolved via assetResolver at render time'` |
| `coar.pageBuilder.props.altText` | `'Alt text'` |
| `coar.pageBuilder.props.choose` | `'Choose…'` |
| `coar.pageBuilder.props.change` | `'Change…'` |
| `coar.pageBuilder.props.clear` | `'Clear'` |
| `coar.pageBuilder.props.noImage` | `'No image'` |
| `coar.pageBuilder.props.noPreview` | `'No preview'` |
| `coar.pageBuilder.props.stackDirection` | `'Stack direction'` |
| `coar.pageBuilder.props.direction` | `'Direction'` |
| `coar.pageBuilder.props.column` | `'Column'` |
| `coar.pageBuilder.props.row` | `'Row'` |
| `coar.pageBuilder.props.orientation` | `'Orientation'` |
| `coar.pageBuilder.props.horizontal` | `'Horizontal'` |
| `coar.pageBuilder.props.vertical` | `'Vertical'` |
| `coar.pageBuilder.props.wrapChildren` | `'Wrap children'` |
| `coar.pageBuilder.props.gap` | `'Gap'` |
| `coar.pageBuilder.props.padding` | `'Padding'` |
| `coar.pageBuilder.props.justify` | `'Justify (main axis)'` |
| `coar.pageBuilder.props.alignItems` | `'Align items (cross axis)'` |
| `coar.pageBuilder.props.alignSelf` | `'Align self'` |
| `coar.pageBuilder.props.size` | `'Size'` |
| `coar.pageBuilder.props.sizeAuto` | `'Auto'` |
| `coar.pageBuilder.props.sizeFill` | `'Fill'` |
| `coar.pageBuilder.props.sizeFixedWidth` | `'Fixed width'` |
| `coar.pageBuilder.props.sizeCss` | `'Size (CSS)'` |
| `coar.pageBuilder.props.width` | `'Width'` |
| `coar.pageBuilder.props.minHeight` | `'Min height'` |
| `coar.pageBuilder.props.spacerSizeHint` | `'Leave empty to fill available space'` |
| `coar.pageBuilder.props.default` | `'— default'` |
| `coar.pageBuilder.props.inherit` | `'— inherit'` |
| `coar.pageBuilder.props.none` | `'— none'` |

### Inspector section titles

Headings of the collapsible sections in the properties panel. `props.section.field`, `props.section.page`, `props.section.visibility`, `props.section.style` and `props.section.layout` are host-owned; the per-element titles come from each built-in definition's `inspectorTitle`. Consumer-registered elements provide their own `inspectorTitle: { key, fallback }`, so their keys are not under `coar.pageBuilder.*`.

| Key | Default (English) |
|-----|-------------------|
| `coar.pageBuilder.props.section.field` | `'Field'` |
| `coar.pageBuilder.props.section.page` | `'Page'` |
| `coar.pageBuilder.props.section.visibility` | `'Visibility'` |
| `coar.pageBuilder.props.section.style` | `'Style'` |
| `coar.pageBuilder.props.section.layout` | `'Layout'` |
| `coar.pageBuilder.props.section.card` | `'Card'` |
| `coar.pageBuilder.props.section.section` | `'Section'` |
| `coar.pageBuilder.props.section.spacer` | `'Spacer'` |
| `coar.pageBuilder.props.section.heading` | `'Heading'` |
| `coar.pageBuilder.props.section.paragraph` | `'Paragraph'` |
| `coar.pageBuilder.props.section.note` | `'Note'` |
| `coar.pageBuilder.props.section.image` | `'Image'` |
| `coar.pageBuilder.props.section.link` | `'Link'` |
| `coar.pageBuilder.props.section.button` | `'Button'` |
| `coar.pageBuilder.props.section.textInput` | `'Text input'` |
| `coar.pageBuilder.props.section.passwordInput` | `'Password input'` |
| `coar.pageBuilder.props.section.numberInput` | `'Number input'` |
| `coar.pageBuilder.props.section.checkbox` | `'Checkbox'` |
| `coar.pageBuilder.props.section.switch` | `'Switch'` |
| `coar.pageBuilder.props.section.select` | `'Select'` |
| `coar.pageBuilder.props.section.multiSelect` | `'Multi select'` |
| `coar.pageBuilder.props.section.radioGroup` | `'Radio group'` |
| `coar.pageBuilder.props.section.dateInput` | `'Date'` |
| `coar.pageBuilder.props.section.dateTimeInput` | `'Date & time'` |
| `coar.pageBuilder.props.section.otpInput` | `'OTP input'` |

### Runtime validation messages

Shown by `<CoarPageRenderer>` under invalid fields when a validating button is clicked.

| Key | Default (English) |
|-----|-------------------|
| `coar.pageBuilder.validation.required` | `'This field is required'` |
| `coar.pageBuilder.validation.minLength` | `'Minimum {n} characters'` |
| `coar.pageBuilder.validation.maxLength` | `'Maximum {n} characters'` |
| `coar.pageBuilder.validation.pattern` | `'Invalid format'` |
| `coar.pageBuilder.validation.matchField` | `'Does not match'` |

---

---
url: /components/page-builder/coar-page-renderer.md
description: >-
  CoarPageRenderer turns a PageNode schema into live Cocoar components at
  runtime, enforcing the allowedElements security boundary with actions,
  validation and initialValues.
---

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

::: tip Stylesheet
Import `@cocoar/vue-page-builder/styles` once in your app — the renderer's layout styles (stack flexbox, section/card spacing) live there too, not just the builder chrome.
:::

## Props

| Prop | Type | Description |
|------|------|-------------|
| `schema` | `PageNode` | Required. The page schema to render. Legacy `column`/`row` containers and v1 flat documents are [migrated on the fly](#legacy-schemas-normalization). |
| `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) **and excluded from the value model**. Also supplies the `assetResolver` fallback and the [consumer element registrations](./custom-elements) (`config.elementTypes`). |
| `actions` | `Record<string, (values: ActionValues) => void \| Promise<unknown>>` | Map of action IDs to handler functions. Buttons and links call these. A returned Promise is awaited: buttons disable (the triggering one spins) until it settles, further clicks are ignored, and a rejection surfaces in the [form-level error banner](#async-actions-the-form-level-error-channel). |
| `onValidate` | `(values: ActionValues) => Record<string, string> \| Promise<Record<string, string>>` | Developer-only cross-field/server validation. Runs at **submit time** — when a `validates: true` button is clicked and after all declarative rules pass. May be sync or async; returns `{ fieldName: errorMessage }`. A non-empty result blocks the action. The reserved key `_form` addresses the form as a whole (banner instead of a field). Not exposed in builder UI. See [Validation](#validation). |
| `assetResolver` | `(id: string) => string` | Resolves an `assetId` to a URL at render time. Falls back to `config.assetResolver` when not set. Needed when the schema contains `image` nodes. |
| `initialValues` | `ActionValues` | Host-supplied field values for edit-form scenarios, merged **over** the schema's `defaultValue`s on init. Only keys that match a **named** input in the (allowed) tree are taken — stray host data never leaks into the action payload. Replacing the object with **different values** re-initializes the form, like a schema change; a value-identical replacement (e.g. an inline object literal re-created by a parent re-render — nested objects/arrays compare by content) is ignored, so in-progress user input survives. |
| `runtimeContext` | `Record<string, unknown>` | Host-owned runtime data. The document can only read paths explicitly declared by `config.contextFields`; undeclared paths resolve to the binding fallback. |
| `locale` | `string` | Active locale used to resolve page translation keys, legacy `LocalizedValue` props and localized templates. Regional locales fall back to their base locale and then `config.defaultLocale`. |
| `viewportWidth` | `number` | Optional deterministic container width. Runtime normally measures its container; previews and tests can provide an exact width. |
| `fallbackSchema` | `PageNode` | Host-owned safe document rendered when the customized document fails allow-list, binding or document-limit validation. `usingFallback` is exposed on the component ref. |

## 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/${encodeURIComponent(id)}`"
/>
```

`ActionValues` is `Record<string, unknown>` — a flat map of all named fields at the time the action fires. Every input element with a `name` property contributes its value — **including untouched ones**: text/otp inputs contribute **strings** (`''` when untouched), `number-input` a **number** (`null`), `checkbox`/`switch` **booleans** (`false`), `multi-select` a **string array** (`[]`), `select`/`radio-group` a **string** (`null`), date inputs an **ISO string** (`null`). Fields in [conditionally hidden](#conditional-visibility-visiblewhen) or disallowed subtrees are excluded. Handlers receive a snapshot, not live state. Hand-written schemas carry no hard type guarantee, so narrow the values in your handler.

To prefill a form (edit scenarios), pass `initialValues` — the values seed **over** the schema defaults, filtered to the named fields that actually exist in the allowed tree. Prefer a stable reference (a `computed` or plain object created once): replacing it with different values re-initializes the form and discards user edits.

```vue
<script setup>
// Stable per user — recomputed only when the source data changes.
const profileValues = computed(() => ({ email: user.email, newsletter: true }));
</script>

<template>
  <CoarPageRenderer
    :schema="profileSchema"
    :actions="{ 'profile:save': (v) => api.save(v) }"
    :initial-values="profileValues"
  />
</template>
```

## Events & host form API

The renderer is not a black box between init and action click — it emits value changes and exposes a small form API on its component ref:

| Surface | Description |
|---------|-------------|
| `@update:values` (event) | Fires with a snapshot of the current value map on init, on every field edit and on `reset()` — unlocks autosave, drafts and dirty tracking. The snapshot is a copy, safe to keep; it contains the named fields of the allowed **and currently visible** tree. |
| `values` (exposed) | Snapshot of the current value map (same rules as the event). |
| `isDirty` (exposed) | `true` once any field differs from its initial state (schema defaults + `initialValues`). |
| `isFormValid` (exposed) | Quiet validation state — `true` while every declarative rule passes. Shows no errors. |
| `reset()` (exposed) | Back to the initial state: schema defaults + `initialValues`; touched flags, server errors and the form banner are cleared. |

```vue
<script setup>
const form = ref();
onBeforeRouteLeave(() => !form.value?.isDirty || confirm('Discard changes?'));
</script>

<template>
  <CoarPageRenderer ref="form" :schema="schema" @update:values="autosave" />
</template>
```

## JSON Schema

One node grammar for every element (wire-format **v4**): the v2 `props`-bag and v3 runtime-composition grammar remain compatible; v4 gives every element a stable page-wide `name` for Element Code and form identity.

```ts
interface ElementNode {
  id:            string                   // stable UUID (crypto.randomUUID), assigned by the builder
  type:          string                   // element-registry key — a built-in type or a consumer key
  props:         Record<string, unknown>  // element-specific props (JSON-safe bag)
  style?:        NodeStyle
  responsive?:   Partial<Record<'phone' | 'tablet' | 'desktop', Partial<NodeStyle>>>
  bindings?:     Record<string, RuntimeBinding | RuntimeTemplate>

  // Value-model trio — meaningful when the element's definition declares `value`:
  name?:         string
  defaultValue?: unknown
  validation?:   FieldValidation

  visibleWhen?:  VisibleWhen              // conditional visibility — see below
  children?:     PageNode[]               // containers only
}

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. '100dvh' to make the page fill the viewport
}
```

The root is the one node shape outside the element grammar: `{ id, type: 'page', schemaVersion, enterSubmits?, stateCode?, rootCode?, translations?, style?, responsive?, children }` — a schema-shape marker, not a placeable element, with no props bag. `rootCode` is a constrained reactive presentation binding and can return only root `style`, `responsive`, and `enterSubmits` changes. **`4`** is current. Older documents remain readable and are normalized deterministically. `enterSubmits` opts the page into [Enter-to-submit](#enter-to-submit).

Node `id`s must be unique page-wide — the builder assigns them via `crypto.randomUUID()` and [repairs missing or duplicate ids](#legacy-schemas-normalization) at every entry point.

### 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 is a width-filling block and measures that container for responsive resolution. To center content on a full-screen page (the classic login card), size the `page` itself:

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

`minHeight: '100dvh'` makes the page fill the current dynamic 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. Legacy `vh` and the modern `svh`/`lvh` variants are supported as well.

### Example — login page

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

Note the split: `name`, `defaultValue`, `validation` and `style` sit at **node level** (host vocabulary, uniform for every element), while `label`, `inputType`, `action`, `assetId`, … sit in **`props`** (each element's own vocabulary).

### Try it live

The same card rendered live (logo omitted). Email is `required` + `inputType: 'email'`, password is `required` + `minLength: 8`, and the Sign-in button `validates`. Click it with empty fields — the click marks every field touched and reveals all errors at once; once the form is valid, the action receives the `ActionValues` and writes them below the card.

## Generic runtime composition (v4)

These features are domain-neutral. Authentication pages are one consumer: names such as `approvedScopes` are ordinary schema configuration, not package concepts.

### Responsive styles

The renderer applies a mobile-first cascade using its measured container width: Compact/base from 320 px, Phone from 390 px, Tablet from 768 px and Desktop from 1280 px. Base values live in `style`; breakpoint differences live in `responsive.phone`, `responsive.tablet` and `responsive.desktop`. The renderer and builder preview share the same resolver. Length values pass through a restrictive CSS-length parser, while colors, typography, radii and elevation use controlled design-token enums.

### Safe bindings, localization and conditions

`bindings` maps an element prop to a controlled runtime source. A target may
be a top-level prop (`disabled`, `label`, …) or one action argument
(`actionValues.approvedScopes`). Supported direct sources are:

| Source | Value |
|--------|-------|
| `context` + `path` | Exact host path declared by `config.contextFields` |
| `state` + `path` | Customer-authored `definePageState(...)` value |
| `field` + `path` | Current named form value |
| `selection` + `path` | Current named Repeat selection (`string[]`) |
| `item` + `path` | Current Repeat item path declared by that Repeat's context contract |
| `index` | Current Repeat index |
| `expression` | Host-sandboxed JavaScript result supplied through `expressionValues` |

Context/item traversal is allow-listed; state/form/selection names come from
the page contract itself. A `RuntimeTemplate` can interpolate several
allow-listed values.

New page documents keep customer-owned messages once on the page root and reference them with a serializable translation binding:

```json
{
  "source": "translation",
  "key": "page.submit.label",
  "params": { "name": "Ada" },
  "fallback": "Sign in"
}
```

Element Code creates the same value through `i18n.text(key, params?, fallback?)`. Resolution is page catalogue → host `@cocoar/vue-localization` catalogue → fallback → key. `LocalizedValue` is retained as a compatibility format for existing schemas.

`visibleWhen` uses the same field/context/item sources with `equals`, `notEquals`, `in`, `notIn`, `exists`, `isEmpty` and `isNotEmpty`. Conditions can be combined with bounded `all`/`any` groups. Hidden subtrees do not render, validate or contribute values/action payloads.

### Generic repeaters and selections

`repeat` renders its child template for an allow-listed context array. Item bindings and conditions can only read declared `itemFields`; `maxItems` is capped at 500. Its optional selection contract is also generic:

```json
{
  "type": "repeat",
  "props": {
    "source": "catalog.items",
    "keyPath": "id",
    "selection": {
      "name": "chosenItemIds",
      "valuePath": "id",
      "requiredPath": "mandatory",
      "defaultSelection": "all"
    }
  }
}
```

The result is `ActionValues.chosenItemIds: string[]`. Required items are always
selected and cannot be unchecked. Host `initialValues` may seed the selection;
otherwise `defaultSelection` is `'none'` or `'all'`. Reconciliation retains
the current choice, removes stale and duplicate values, adds required values,
and emits the source-array order. The output name and item paths are freely
configured; the primitive has no knowledge of scopes, products, roles or any
other domain.

### Feedback placement, actions and fallback

`feedback` is an authorable semantic zone. `kind: 'form-error'` places rejected async-action or `_form` validation errors at that exact tree position; other kinds provide error, success, info and loading status with appropriate live-region semantics. Every action-capable element uses the same optional [`ActionProps`](#action-arguments) payload contract.

Hosts can mark nodes as required, lock their visibility/style/placement, and cap node count/depth through `PageConfig`. If a saved customization violates those invariants, `fallbackSchema` provides a safe host-owned render path rather than a partially broken page.

## Built-in Elements

Built-ins are pre-registered [element definitions](./custom-elements) — they ride exactly the same registry contract as consumer-registered elements. The prop names listed below live in each node's **`props` bag**; `name` / `defaultValue` / `validation` / `style` are node-level host fields on every element.

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

| Type | Props | Description |
|------|-------|-------------|
| `heading` | `text`, `level` (1–6) | H1–H6 heading |
| `paragraph` | `text` | Body text block |
| `note` | `text`, `variant` (`neutral` | `info` | `success` | `warning` | `error` | `accent`) | `CoarNote` callout box |

### Inputs

| Type | Key props (in `props`) | Value type | Cocoar component |
|------|-----------|------------|-----------------|
| `text-input` | `label`, `inputType`, `rows`, `placeholder`, `disabled` | `string` | `CoarTextInput` (textarea when `rows > 1`) |
| `password-input` | `label`, `placeholder`, `disabled` | `string` | `CoarPasswordInput` (masked) |
| `number-input` | `label`, `placeholder`, `min`, `max`, `step`, `decimals`, `disabled` | `number` | `CoarNumberInput` |
| `checkbox` | `label`, `disabled` | `boolean` | `CoarCheckbox` |
| `switch` | `label`, `disabled` | `boolean` | `CoarSwitch` |
| `radio-group` | `label`, `options`, `optionsSourceId`, `orientation`, `disabled` | `string` | `CoarRadioGroup` + `CoarRadioButton` |
| `select` | `label`, `options`, `optionsSourceId`, `placeholder`, `disabled` | `string` | `CoarSelect` |
| `multi-select` | `label`, `options`, `optionsSourceId`, `placeholder`, `disabled` | `string[]` | `CoarMultiSelect` |
| `otp-input` | `label`, `length`, `otpType`, `mask`, `disabled` | `string` | `CoarOtpInput` |
| `date-input` | `label`, `placeholder`, `disabled` — `defaultValue` is ISO `YYYY-MM-DD` | ISO `string` | `CoarPlainDatePicker` |
| `datetime-input` | `label`, `placeholder`, `disabled` — `defaultValue` is ISO `YYYY-MM-DDTHH:mm[:ss]` | ISO `string` | `CoarPlainDateTimePicker` |

All inputs support the node-level `name` (wires the value into `ActionValues`), `defaultValue`, and `validation`, plus `props.disabled`. Fields with `validation.required` get the `*` marker via `CoarFormField`. Required semantics adapt to the value shape: a required `multi-select` needs **at least one** selection, a required `otp-input` needs a **complete** code (all cells filled), a required `switch`/`checkbox` must be **on**.

::: info Date values are ISO strings
The wire format for `date-input`/`datetime-input` is always the ISO string — in the schema's `defaultValue` **and** in `ActionValues`. The renderer converts to/from `Temporal.PlainDate`/`PlainDateTime` at the picker boundary; an unparsable value renders as an empty picker instead of crashing. Zoned (time-zone-aware) date-times are deliberately not part of the element set yet.
:::

#### `inputType`

`text-input` maps its `inputType` onto the right control and autocomplete hints:

| `inputType` | Renders | Autocomplete |
|-------------|---------|--------------|
| `'text'` (default) | `CoarTextInput` with `type="text"` | — |
| `'email'` | `CoarTextInput` with `type="email"` | `autocomplete="email"` |
| `'url'` | `CoarTextInput` with `type="url"` | `autocomplete="url"` |

Masked passwords are their own element: `password-input` (renders `CoarPasswordInput`). Legacy `text-input` nodes with `inputType: 'password'` migrate to it transparently on load.

`inputType: 'email'` also opts the field into the built-in **email format check** — see [Email format](#email-format).

#### Dynamic options (`optionsSource`)

The choice inputs (`select`, `multi-select`, `radio-group`) take their options from the static `options` array by default. For API-backed lists (countries, users, …), set the node's `optionsSourceId` and provide the resolver in the config — the async sibling of `assetResolver`:

```ts
const config: PageConfig = {
  optionsSource: async (sourceId) => {
    if (sourceId === 'countries') return api.countries(); // Promise<OptionItem[]>
    return [];
  },
};
```

A set `optionsSourceId` wins over the static `options`; without a configured `optionsSource` the static options are used (and the builder lint warns). While a load is in flight the list is empty; a failed load stays empty and warns once. The resolver is called once per element instance — memoize consumer-side when several elements share a source. Consumer elements get the same behavior via the exported `useResolvedOptions` composable.

#### Declarative rules

Rules live on the node-level `validation` property (host vocabulary, uniform for every valued element):

```ts
interface FieldValidation {
  required?:   boolean    // any valued element — emptiness comes from the element's definition
  minLength?:  number     // string-rule elements (text-input, password-input, …)
  maxLength?:  number     // string-rule elements
  pattern?:    string     // string-rule elements; regex source applied as full-string match
  matchField?: string     // any valued element — value must equal this other named field's value
  message?:    string     // custom error message — overrides defaults
}
```

`required` and `matchField` are host-enforced on every valued element; the string rules (`minLength` / `maxLength` / `pattern`) are host-enforced on elements whose definition opts in via `value.textRules` (built-in: `text-input` and `password-input`). Other elements express extra rules through their definition's `validate` hook (run crash-guarded, after the host rules) — see [Custom elements](./custom-elements). How and when errors surface is described under [Validation](#validation).

### Actions

| Type | Key props | Description |
|------|-----------|-------------|
| `button` | `label`, `action`, `validates`, `default`, `variant`, `size`, `icon` | `CoarButton` — calls the matching `actions` handler. Content-width by default; use `style.size: 'fill'` for a full-width button. `default: true` marks it as the [Enter-to-submit](#enter-to-submit) target. |
| `link` | `label`, `action` | Inline text link. Content-width by default. |

When `validates: true` on a button, clicking it validates all named fields before the action fires. The button **stays clickable while the form is invalid** — the click reveals the errors instead of firing the action. While a trigger is in flight (an async `onValidate` **or** an async action), the triggering button spins and every other action button and link disables; further clicks are ignored. See [Validation](#validation).

#### Action arguments

Buttons, links and consumer elements with `action: true` share one contract:

```ts
interface ActionProps {
  action?: string
  actionValues?: Record<string, unknown>
  actionValueField?: string
  actionValue?: unknown
}
```

All four fields are optional. `actionValues` is a JSON-safe key/value map. The
common Properties-panel editor accepts values such as `"de"`, `42`, `true`,
`null`, arrays and objects; every key has its own **fx** switch. A nested
binding such as `bindings["actionValues.language"]` replaces only that entry.
`actionValue` supplies the older single additional value under
`actionValueField` and remains supported.

The renderer builds a detached handler payload in this explicit order:

1. current named form values,
2. resolved `actionValues` (static defaults plus per-key bindings), overwriting colliding form keys,
3. the dynamic `actionValue`, overwriting a static entry with the same `actionValueField`.

This order is identical for click, link activation, Enter-to-submit and consumer action elements. Invalid non-JSON values never reach a handler; builder and activation validation report them as errors.

### Media

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

### Consumer elements

The element set is **open**: register your own element types via `config.elementTypes` (or app-wide via `PAGE_ELEMENT_TYPES_KEY`) and they render, join the value model and validate exactly like built-ins. Element renderers wire themselves through the `usePageElement()` context (`getValue` / `setValue` / `getError` / `markTouched` / `triggerAction` / `isValidating` / `isSubmitting` / `pendingAction` / `formError` / `resolveAsset` / `config`). See the [Custom elements guide](./custom-elements).

## Validation

Named fields validate against their declarative `validation` rules reactively, but errors only *show* once a field is **touched**:

* **text inputs** are touched on blur,
* **checkbox / select** are touched on change — choosing a value *is* the interaction, there is no meaningful blur moment,
* **clicking a `validates: true` button marks every named field touched at once.**

### Click reveals errors

A validating button is **not** disabled while the form is invalid. Clicking it with an invalid form marks all fields touched, reveals every error — including checkbox and select errors that have no blur moment — focuses and scrolls the **first invalid control** into view (off-screen errors must not make the click look dead), and does **not** run the action. A disabled button can't explain itself; a click can.

Buttons disable only while a trigger is genuinely in flight — an async `onValidate` or an async action. The triggering button shows a spinner; every other action button and link disables; repeated clicks are ignored (double-submit guard for validating and non-validating buttons alike).

### `pattern` semantics

`validation.pattern` is applied as a **full-string match** — the source is compiled as `^(?:pattern)$`, the same semantics as the HTML `pattern` attribute. An invalid pattern never crashes the page: it becomes an **inert rule** (the field passes) and the renderer logs one `console.warn` per distinct pattern.

### Email format

A `text-input` with `inputType: 'email'` validates the entered value against the WHATWG email pattern (`input[type=email]` constraint semantics, full string) **by default** — no hand-written `pattern` needed. The check skips empty values (`required` decides those) and uses the localized `coar.pageBuilder.validation.email` message. Since submission is JS-driven (there is no `<form>`), the browser's own constraint never fires — this host-side rule replaces it. It rides the `textRules` opt-in, so a consumer element with `textRules` and an `inputType` prop participates the same way.

### Submit-time `onValidate`

`onValidate` is the escape hatch for validation that can't be expressed declaratively — server checks, cross-field logic. Its contract:

1. Clicking a `validates: true` button marks all fields touched. If any **declarative** rule fails, the errors show, the first invalid control is focused, and nothing else happens.
2. Only when the declarative rules pass does `onValidate(values)` run. It may return the error map directly or a `Promise` of it; while a promise is pending, the triggering button spins and the other action buttons are disabled.
3. A non-empty result blocks the action: `{ fieldName: errorMessage }` entries show on their fields, the reserved **`_form`** key (exported as `FORM_ERROR_KEY`) shows in the [form-level banner](#async-actions-the-form-level-error-channel). Errors keyed to fields that cannot display (hidden by `visibleWhen`, renamed, never on the page) are routed to the banner too — a blocked submit is never invisible.
4. Editing a field clears that field's server error (and the form banner) immediately — a stale error never outlives the edit that addresses it.
5. If `onValidate` throws (or rejects), the action does not run, a localized generic message shows in the form banner, and the error is logged to the console.
6. An empty result lets the action fire — with **the exact snapshot `onValidate` approved** (edits made while an async `onValidate` was in flight never ship unvalidated; they need their own submit). A returned Promise is awaited.

`onValidate` does **not** run on keystrokes — it fires at submit time only.

```vue
<CoarPageRenderer
  :schema="schema"
  :actions="{ 'auth:login': (v) => auth.login(v) }"
  :on-validate="async (v) => {
    const taken = await api.isEmailTaken(v.email as string);
    return taken ? { email: 'This email is already registered' } : {};
  }"
/>
```

### Async actions & the form-level error channel

Real submits are API calls. An action handler may return a Promise — the renderer awaits it, keeps the whole form in its busy state (spinner on the triggering button, everything else disabled, reentry blocked) until it settles, and routes a **rejection** into the form-level error banner:

```ts
const actions = {
  'auth:login': async (v) => {
    const res = await api.login(v);
    // Throw an Error whose message is user-facing — it becomes the banner text.
    if (!res.ok) throw new Error('Invalid credentials');
  },
};
```

* An `Error`'s `message` is shown verbatim — that is the consumer's channel for user-facing failure text. Catch-and-rethrow if your transport errors ("Failed to fetch") shouldn't reach end users.
* Any other rejection shows the localized generic message (`coar.pageBuilder.formError.actionFailed`).
* The same banner shows the `_form` key of an `onValidate` result — for form-level *validation* outcomes like "Invalid credentials" from a validation endpoint.
* The banner clears on any field edit and at the start of every new trigger.

The default banner renders above the page (a `CoarNote` with `role="alert"`). Two ways to take over the presentation:

```vue
<!-- Replace the banner via the slot… -->
<CoarPageRenderer :schema="schema" :actions="actions">
  <template #form-error="{ error }">
    <MyToast v-if="error" :text="error" />
  </template>
</CoarPageRenderer>
```

…or render it **inside** the page (e.g. right above the submit button) with a small custom element reading `usePageElement().formError` — see [Custom elements](./custom-elements).

## Enter to submit

Enter-to-submit is double opt-in — the page and the element under the caret both agree:

1. The **page root** sets `enterSubmits: true` (a checkbox in the builder's Page section; default off).
2. The **element** declares Enter-eligibility in its definition (`value.submitOnEnter`). Built-ins: single-line `text-input` (`rows <= 1`), `password-input`, `number-input`. A multiline textarea, `select`s, `otp-input`, the date inputs (their picker panel uses Enter) and consumer elements that don't declare the flag never submit on Enter.

A plain Enter (no modifiers) inside an eligible input fires the page's **default button**: the first button with `default: true` (a checkbox in the button inspector; the lint warns when several buttons claim it), else the first `validates: true` button in tree order — with the full submit pipeline (validation, `onValidate`, busy state). Before triggering, the input is blurred so commit-on-blur controls (number input) flush the value the user sees. An Enter the element already consumed (`preventDefault`, e.g. inside a picker popover) and an IME composition-commit Enter never submit.

## Conditional visibility (`visibleWhen`)

Any node can declare a visibility condition against the **live value model** (host vocabulary — works on every element, containers and consumer elements included):

```jsonc
{
  "id": "company", "type": "text-input", "name": "companyName",
  "props": { "label": "Company name" },
  "validation": { "required": true },
  "visibleWhen": { "field": "isBusiness", "equals": true }
}
```

| Field | Meaning |
|-------|---------|
| `field` | Name of the controlling field (a named input on the page). |
| `equals` | Visible while the field's value equals this (JSON-safe values compare by **content**, arrays and objects included). |
| `in` | Visible while the field's value is one of these (array). |

The condition gates the node **and its whole subtree** — in rendering *and* in the value model, in the same walk as `allowedElements`:

* A hidden `required` field never vetoes a validating button.
* Hidden values never ship: action payloads, `onValidate` input, `update:values` and the exposed `values` all carry only the allowed and **visible** tree.
* Values typed before hiding are kept internally and return when the node is re-shown (so a mis-click doesn't wipe input) — they just don't leave the renderer while hidden.
* A malformed condition fails **open** (the node stays visible), and a condition on the **page root is ignored** (a page can never blank itself). The builder lint flags malformed conditions, references to fields that aren't on the page, and **circular chains** (a field whose visibility depends on itself or on a mutual loop — hidden controllers can't be edited, so such chains can lock each other hidden).

Authoring: the builder's **Visibility** section offers the controlling-field select and a typed `equals` editor (checked/unchecked for boolean controllers, the option list for choice controllers, free text otherwise); the `in` form is JSON-authorable. Conditional nodes carry an eye marker on the canvas — the canvas always *shows* them (it is an authoring surface); the Preview tab applies the real gating.

## Legacy schemas & normalization

The renderer migrates **on the fly**: legacy `column` / `row` containers become `stack` (with `direction: 'column'` / `'row'`), then v1 flat nodes (pre-GA grammar, element props directly on the node) get their `props` bag. Old saved schemas keep rendering without a round-trip through the builder. The migration happens at render time only and never mutates the schema object you passed in.

The builder goes further and normalizes at **every entry point** — the initial `v-model` value, external `v-model` replacement, and the JSON tab's Apply (which [gates on issue severity](./coar-page-builder#json-tab): errors block, warnings apply). The same helpers are exported for your own persistence layer:

```ts
import {
  normalizePageSchema,
  migrateLegacyTypes,
  migrateV1PropsBag,
  KNOWN_ELEMENT_TYPES,
} from '@cocoar/vue-page-builder';

const { schema, issues, changed } = normalizePageSchema(stored);
```

| Export | Description |
|--------|-------------|
| `normalizePageSchema(value)` | Returns `{ schema, issues, changed }`. Runs both migrations, then heals silently what has unambiguous intent: a non-`page` root (wrapped in a fresh page), missing `children` arrays, missing/duplicate/empty node ids (fresh UUIDs), missing `props` bags, numeric heading levels outside 1–6 (clamped), a missing/`1` `schemaVersion` (stamped `2`). Every `issue` carries a `severity`: **`error`** = data was dropped (non-object nodes — structurally broken input), **`warning`** = healed in place or lossless (unknown element types — kept in the tree, skipped at render time; non-array `children` or non-object `props` reset; non-numeric heading levels reset to 2; `children` on a non-container). |
| `migrateLegacyTypes(node)` | Just the `column`/`row` → `stack` mapping, recursive and identity-preserving when there is nothing to migrate. |
| `migrateV1PropsBag(node)` | The v1 → v2 wire-format migration: per node, a known element type without a `props` object gets its flat element props moved into a fresh bag. Idempotent and identity-preserving — safe to run unconditionally. |
| `KNOWN_ELEMENT_TYPES` | `ReadonlySet<string>` of the **built-in** element types. Consumer-registered keys are per-instance data (`config.elementTypes`) and deliberately not part of this module constant. |

## Security boundary

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

1. **Allowed elements** — `config.allowedElements` is the hard boundary (it takes built-in types and consumer-registered keys alike). Disallowed types are skipped at render time, with one console warning per type. The gate applies to the **value model** too: disallowed subtrees contribute no default values and cannot block validation — an invisible `required` field can never veto a validating button. Unregistered element types (typos, newer schema versions, consumer elements this instance hasn't registered) degrade the same lenient way: skipped with one warning per type, excluded from the value model, but **kept losslessly in the tree** — the builder [flags them as warnings on the canvas and in validation](./coar-page-builder) instead of destroying them.
2. **Actions** — every registry element with `action: true` stores an action `id`, an inert string. Only handlers present in the `actions` prop fire — any other action ID is a silent no-op. The one piece of tenant-authored logic the renderer evaluates is `validation.pattern`: a regex compiled safely (invalid = inert rule) and anchored — never executed as code.
3. **Reserved field names** — `__proto__`, `constructor` and `prototype` are excluded from the value model entirely (they would collide with `Object.prototype` machinery when used as map keys): such fields neither veto submission nor appear in payloads, and the builder lint flags them as errors.
4. **Images** — `image` nodes store an `assetId` reference, never a raw URL. The renderer always goes through `assetResolver` — which makes the resolver **your** part of the boundary: it decides what an id can reach. Validate or encode the id before building a URL, e.g. allowlist `/^[A-Za-z0-9_-]+$/` or `encodeURIComponent(id)`, so a crafted id like `../other-tenant/logo` cannot traverse out of the tenant's asset prefix.

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

## i18n Keys

The renderer's validation messages can be translated via [`@cocoar/vue-localization`](/foundations/localization/translations) (a peer dependency — English fallbacks are built in). A field-level `validation.message` overrides all of them for that field.

| Key | Default (English) | Used when |
|-----|-------------------|-----------|
| `coar.pageBuilder.validation.required` | `'This field is required'` | `required` fails — value empty, unset, or unchecked |
| `coar.pageBuilder.validation.minLength` | `'Minimum {n} characters'` | text shorter than `minLength` — `{n}` = the limit |
| `coar.pageBuilder.validation.maxLength` | `'Maximum {n} characters'` | text longer than `maxLength` — `{n}` = the limit |
| `coar.pageBuilder.validation.pattern` | `'Invalid format'` | `pattern` full-string match fails |
| `coar.pageBuilder.validation.matchField` | `'Does not match'` | value differs from the referenced field |
| `coar.pageBuilder.validation.email` | `'Enter a valid email address'` | the [built-in email check](#email-format) fails on an `inputType: 'email'` field |
| `coar.pageBuilder.formError.actionFailed` | `'Something went wrong. Please try again.'` | an action rejects without an `Error` message, or `onValidate` throws |

## 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 — and falls back to `config.assetResolver` when the `assetResolver` prop is absent, so handing the same object to both really is the whole wiring.

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

---

---
url: /components/page-builder/authoring-contract.md
---
# Authoring contract

Every capability the renderer honours must be reachable from an authoring
surface. This page is the inventory: each part of the document grammar, the
surface that writes it, and — where a surface is missing — whether that is a
**named exception** or an **open gap**.

## The rules

1. **Nothing is JSON-only.** Every capability is reachable through Element Code
   / Page Code or a panel control. Editing raw JSON is a convenience, never a
   requirement.
2. **Nothing rewrites the document behind the author's back.** Problems are
   reported, not silently healed.
3. **Code is the truth.** Element Code, Page Code and Page State are the
   authored artifact; the document follows from them. A Quick Property is
   nothing but a fixed Element Code block — not editable as text, placed before
   the element's custom code, so custom code can override it. Quick Properties
   are a convenience for frequently-touched properties, not a second model.
4. **Renderer ⊆ Builder.** `CoarPageRenderer` supports exactly what the builder
   can write. It cannot do more than the editor can author.

An exception to any of these is legitimate **only if it is named on this
page**. An unnamed exception is a bug.

## Two modes, one of them on the way out

`authoringMode="properties"` is the **legacy** mode. It writes values directly
into the document (`node.style`, `node.props`, `node.visibleWhen`) through
per-element inspectors, a Style section, a Visibility section and a Field
section. It is scheduled for removal.

`authoringMode="code"` is the target. Everything is authored as code:

| Surface | Writes | Notes |
|---|---|---|
| **Element Code** | `props`, `style`, `responsive`, `validation`, `visibleWhen`, `bindings`, `defaultValue` | Computed per render. Cannot change `type` or `name`. |
| **Quick Properties** | locked assignments inside `elementCode`, ahead of the custom-code slot | Paths limited to `props.*`, `style.*`, `validation.*` |
| **Page Root Code** | `style`, `responsive`, `enterSubmits` on the root | |
| **Page Code / Page State** | shared state, repeat `items`, cross-element logic | |
| **Structure section** | `type` (representation switch), `name` (free or contract-bound) | Structural — deliberately not code |
| **Canvas / Outline** | `children`, tree order, `id` | Structural |
| **Logic tab** | `bindings`, expressions | |
| **Translations tab** | `translations` | |
| **JSON tab** | everything, as a paste-and-apply convenience | Never the only way |

The inventory below is written against the **target** state. Where a capability
today has only a legacy-mode control, that is called out — it is a gap that
opens the day properties mode is removed, not a gap you can see now.

## The sandbox is mandatory

If code is the truth, then the code has to run. `CoarPageRenderer` never
evaluates it: the host runs `usePageCodeRuntime()` against an isolated Worker
session and passes the data-only result as `pageCodeValues`.

Leaving it out does **not** produce an error. `applyPageCodeValues` returns the
schema untouched when it gets no values, so the renderer draws the persisted
document — a different page, silently. And the difference is not small, because
Quick Properties write **only** into `elementCode`; no write path touches
`node.style` or `node.props`. A page whose author set anything in code mode
renders unconfigured without the runtime.

There is no realistic document that avoids this. A Quick Property *is* Element
Code, and a page with a button or a validated field has one.

```ts
const runtime = usePageCodeRuntime({ schema, pageId, /* … */ });
```

```vue
<CoarPageRenderer :schema :config :page-code-values="runtime.values.value" />
```

**Consequence to know about:** the persisted JSON on its own no longer
describes the page. Static `style` values left over from earlier authoring can
disagree with the code that overrides them, and the code wins. Read a document
through the runtime, not by eye.

## Node grammar

### Every node

| Field | Target-state surface |
|---|---|
| `id` | Canvas / Outline, builder-assigned — **named exception** |
| `style` | Element Code (`element.style`), Quick Properties for the common keys |
| `responsive` | Element Code (`element.responsive`) — **no Quick Property**, see gaps |
| `composition`, `compositionOrigins` | Compositions library — **named exception** |

`NodeStyle` in full: presentation (`surface`, `foreground`, `borderTone`,
`borderWidth`, `radius`, `elevation`), typography (`fontFamily`, `fontSize`,
`fontWeight`, `fontStyle`, `fontVariationSettings`, `lineHeight`,
`letterSpacing`, `textAlign`, `textDecoration`), layout (`gap`, `padding`,
`justify`, `align`, `direction`, `wrap`, `alignSelf`, `size`, `width`,
`minWidth`, `maxWidth`, `height`, `minHeight`, `maxHeight`, `aspectRatio`,
`overflow`, `hidden`). All of it is writable from Element Code. Quick Properties
cover the layout subset plus `hidden`; the token-backed keys are deliberately
code-only, because they carry design-system semantics that a free-text field
would invite authors to bypass.

### Elements

| Field | Target-state surface |
|---|---|
| `type` | Palette; Structure section for a representation switch |
| `name` | Structure section (free text, or a select over the field contract) |
| `props` | Element Code; Quick Properties for the common ones |
| `defaultValue` | Element Code (`element.defaultValue`) — no Quick Property |
| `validation` | Element Code; Quick Property for `required` only |
| `bindings` | Logic tab and the per-property *fx* buttons; Element Code |
| `visibleWhen` | Element Code (`element.visibleWhen`), full grammar |
| `elementCode` | Element Code dialog |
| `children` | Canvas / Outline |

### Page root

| Field | Target-state surface |
|---|---|
| `enterSubmits` | Page Root Code (`page.enterSubmits`) |
| `style`, `responsive` | Page Root Code, Quick Properties |
| `pageCode`, `rootCode`, `stateCode` | Their own editors |
| `translations` | Translations tab |
| `children` | Canvas / Outline |
| `schemaVersion` | Builder-managed — **named exception** |
| `style.width`, `style.height` | Not authorable — **named exception** |

## Named exceptions

Each states what it costs.

### The page is exactly its host container

Size values on the page root are dropped, and the root offers no size fields.
The page is one element inside the host's viewport, and the host container owns
its box; `overflow` stays authorable and defaults to `auto`. The contract for
the host is that the container must have a determinable height — for `body`
that means `html, body { height: 100% }`.

**Cost:** a document cannot make itself taller than its host. That is the
intent: a page that fights its container breaks in every second embedding.

### Structure is not code

`type`, `name`, `id` and `children` are authored visually, never by Element
Code — the runtime patch deliberately drops them. A program that could rename
or retype its own node would break every binding and Page Code reference that
points at it, at render time, with no way for the builder to see it coming.

**Cost:** generating elements from data is not possible per element. The
`repeat` element covers the case that motivates it.

### Identity is builder-managed

`id` is a UUID the builder assigns; `schemaVersion` is the wire format. A
hand-picked id collides, and a hand-picked version lies about the shape of the
document.

**Cost:** none for authors. Existing ids are preserved — the builder only
assigns missing ones.

### Composition metadata is repository-owned

`composition` and `compositionOrigins` record which reusable definition a
subtree came from and at which pinned version. Written by the Compositions
library, stripped by `compilePageCompositions()` before runtime delivery, never
hand-edited.

**Cost:** hand-editing them detaches an instance from its definition. The
builder then treats the subtree as ordinary nodes.

### Legacy ingest may rewrite the document

A document from an older `schemaVersion` is migrated on entry. This is the one
place where rule 2 does not hold, and it is bounded to documents the current
builder could not otherwise open.

**Cost:** a v1–v4 document saved by this builder comes back as v5. Round-trips
within one version rewrite nothing.

### Host CSS never reaches the document

There is no way for a document to carry a CSS class or a stylesheet. Styling is
`NodeStyle` per node, `CoarTheme` for brand colours, radii and fonts, and the
`visual-markup` element for free-form decoration inside its sealed iframe.

`config.stylePresets` used to be a fourth channel — a host-registered catalogue
of named classes the author could pick from. It was removed: the author who
builds a page owns the realm it renders in, so the restriction protected
nobody, and a class name written into a document couples it to one application's
stylesheet forever. A leftover `stylePreset` key in an old document is reported
as a warning, never stripped.

**Cost:** a vendor cannot ship a catalogue of ready-made looks. If that becomes
a product requirement, it is a new feature with its own design — not a revival
of this one.

### Host data has one channel

Everything the host knows travels through `runtimeContext`, allow-listed by
`config.contextFields`. There is no separate view-state input and no named
preview fixtures: "which screen is this right now" is ordinary host data, and
a fixture was a bundle of the very props the host already passes.

A context field may declare `values: string[]`, and the condition editor then
offers them as a dropdown instead of a free-text box. That is what makes a
host state, tier or status authorable without a second mechanism carrying it.

Three channels remain, each with one owner: `runtimeContext` (host), Page State
via `definePageState` (the page author), and the field values — `defaultValue`
authored, `initialValues` supplied by the host and winning over it.

**Cost:** a host wanting an "empty / typical / 50 items" preview picker builds
it in its own chrome and binds the chosen sample to `previewContext`. The
builder no longer draws that control.

### The document is not policed

There is no way for a host to pin a node as present, placed or visually
untouchable. `config.requiredNodes` did that and was removed: a page author
owns the realm the page renders in, and the mechanism did not hold anyway — a
locked node still vanished when the container above it was hidden, with the
document reporting no issue.

**Cost:** a host that must guarantee a notice — a compliance line on a consent
screen — enforces it where activation happens. The IDP contract already puts
publication behind trusted server validation; that check runs on the document
about to go live and cannot be reached from the browser.

### Token-backed style keys are code-only

`surface`, `radius`, `elevation` and the typography keys have no Quick
Property. They carry design-system semantics: a token name picked in passing
next to the canvas is how a page ends up with six subtly different card looks.
Element Code still writes them, so nothing is out of reach.

**Cost:** changing a card's surface needs the code editor. Deliberate friction.

## Open gaps

These violate the rules and are not exceptions.

### Blocking the removal of properties mode

| Gap | Evidence | Consequence |
|---|---|---|
| `visibleWhen` has no code-mode control | The Visibility section is legacy-only | Conditions become text-only. Acceptable under rule 1, but it is the single most-used non-style property. |
| Element inspectors are legacy-only | Only `visual-markup` sets `inspectorInCodeMode` | Every per-element prop not covered by a Quick Property becomes text-only: `heading.level`, `note.variant`, `otp.length`, `select.options`, `button.icon`/`validates`/`default`, `image.alt`/`assetId`, `repeat.*`, action wiring. |

### Renderer beyond the builder

| Gap | Evidence | Consequence |
|---|---|---|
| `repeat.maxItems` is not authorable anywhere | Renderer clamps to it (default 100, ceiling 500); no inspector field | A list longer than 100 items truncates and the author cannot say otherwise |
| `repeat.itemAlias` is not authorable | Only read, to label the binding picker | Cosmetic; the alias is stuck at its default |
| `feedback.emptyText` exists in the schema and nothing reads it | Neither renderer nor inspector | Dead field: implement it or remove it |

### Rule 2

| Gap | Evidence |
|---|---|
| Normalization heals instead of reporting | Duplicate names renamed, ids reassigned, heading levels clamped, legacy containers converted, non-object children dropped — on `v-model` assignment, initial value and JSON apply alike |

### Legacy-mode wording, dying with the mode

The Visibility section tells the author to "edit it in the JSON tab" for an
`in` condition and for an `equals` against a multi-value field, and its operator
list omits `in` / `notIn` although `conditions.ts` evaluates both. All three
live only in properties mode. They are wrong today — Element Code expresses all
of it — but they disappear with the mode rather than needing their own fix.

---

---
url: /components/page-builder/custom-elements.md
description: >-
  Registering consumer element types via PageElementDefinition: props-bag wire
  format, runtime renderer with usePageElement, plus palette, preview and
  inspector integration.
---

# Custom elements

`@cocoar/vue-page-builder` dispatches every element — built-in and consumer-defined alike — through one **element registry**. A registration is a plain object (`PageElementDefinition`) that packages everything the renderer and the builder need to know about one element type: the runtime component, its value-model participation, and optionally its editor appearance (palette entry, canvas preview, inspector).

Built-ins (`heading`, `text-input`, `card`, …) are pre-registered definitions on exactly this contract. A consumer element you register is therefore a **first-class element**: it appears in the palette, renders on the canvas, gets its own inspector section, participates in required-field validation, and contributes its value to action payloads — indistinguishable from a built-in.

A complete working example (a star-rating input) lives in the playground at `apps/playground/src/components/rating/`, registered in `apps/playground/src/views/PageBuilderView.vue`. This page walks through that element.

## Wire format

Custom nodes use the same node grammar as every other element — there is no `custom` envelope. The `type` is the registry key; everything element-specific lives in the `props` bag:

```json
{
  "id": "3f2c9a6e-…",
  "type": "acme-rating",
  "props": { "label": "How did we do?", "max": 5 },
  "name": "field_ab12",
  "defaultValue": 3,
  "validation": { "required": true },
  "style": { "alignSelf": "start" }
}
```

The **host vocabulary** stays at node level and is the same for every element:

| Field | Owner | Meaning |
|-------|-------|---------|
| `id` | host | Stable UUID, minted by the builder |
| `type` | host | Registry key (built-in type or consumer key) |
| `props` | **element** | The element's own vocabulary — JSON-safe, persisted verbatim |
| `style` | host | [`NodeStyle`](./coar-page-renderer#json-schema) — sizing, alignment, gap, padding |
| `name` / `defaultValue` / `validation` | host | Value-model trio; only meaningful when the definition has a `value` spec |
| `children` | host | Only when the definition declares `container` |

The bag exists so element props can never collide with host fields — an element prop named `style` or `children` is just `props.style` / `props.children`. The unified props-bag grammar was introduced in v2; version 4 added a stable name to every element, and version 5 added builder-only origin metadata for reusable compositions, and current `schemaVersion: 6` renamed the repeat's `props.source` to `props.contextPath`. Older documents normalize transparently (see [Degradation and compatibility](#degradation-and-compatibility)).

## Walkthrough: a rating element

The element is an interactive star-rating field. Four small pieces:

```
rating/
├── ratingProps.ts          the props-bag type (shared vocabulary)
├── RatingRenderer.vue      runtime component        ← renderer half
├── RatingPreview.vue       builder canvas preview   ┐
├── RatingInspector.vue     props-panel section      │ builder half
├── RatingDefaultInput.vue  typed default-value edit ┘
└── ratingElement.ts        the definition
```

### 1. The props bag

```ts
// ratingProps.ts
/** The rating element's props bag (JSON-safe, lives in `node.props`). */
export type RatingProps = {
  label?: string;
  max: number;
};
```

Keep it JSON-safe — the bag is persisted verbatim. Non-JSON values (dates, functions) don't survive the round-trip; use string wire values and convert at the component boundary (that's what the built-in date inputs do with ISO strings).

### 2. The runtime renderer

The renderer receives `{ node }` and wires itself into the renderer's value model via `usePageElement()` — a curated, stable context with `getValue` / `setValue` / `getError` / `markTouched` / `triggerAction` / `triggerElementAction` / `isValidating` / `isSubmitting` / `pendingAction` / `formError` / `resolveAsset` / `config`:

```vue
<!-- RatingRenderer.vue -->
<script setup lang="ts">
import { computed } from 'vue';
import { CoarFormField } from '@cocoar/vue-ui';
import { usePageElement, type ElementNode } from '@cocoar/vue-page-builder';
import RatingStars from './RatingStars.vue';
import type { RatingProps } from './ratingProps';

const props = defineProps<{ node: ElementNode<string, RatingProps> }>();

const ctx = usePageElement();
const name = computed(() => props.node.name);
</script>

<template>
  <CoarFormField
    :label="node.props.label"
    :required="node.validation?.required"
    :error="name ? ctx.getError(name) : ''"
  >
    <RatingStars
      :model-value="name ? Number(ctx.getValue(name) ?? 0) : 0"
      :max="node.props.max"
      @update:model-value="(v) => { if (name) { ctx.setValue(name, v); ctx.markTouched(name); } }"
    />
  </CoarFormField>
</template>
```

Notes:

* `node.name` is optional — a rating dropped without a field name still renders, it just doesn't participate in the value model. Guard your `getValue`/`setValue` calls.
* `getError(name)` returns a non-empty message only once the field is *touched*; call `markTouched(name)` at the interaction that counts (blur for typing inputs, change for choose-is-the-interaction inputs like this one).
* `usePageElement()` throws outside a `<CoarPageRenderer>` — element renderers only run inside the page renderer (the builder canvas uses the preview instead, never this component).
* Submit-affordance elements read the busy state: `isSubmitting` is true while an action's Promise is pending, `pendingAction` names the action id in flight (spin when it matches your own), `isValidating` covers the `onValidate` window. `formError` carries the [form-level error](./coar-page-renderer#async-actions-the-form-level-error-channel) — a small consumer element can render the banner *inside* the page (e.g. right above the submit button) instead of the host-level default.
* Choice-style elements can resolve `optionsSourceId` props exactly like the built-ins via the exported `useResolvedOptions(() => props.node.props)` composable.

#### Action-capable consumer elements

Compose your props with the exported `ActionProps`, declare `action: true` on the definition, and trigger through `triggerElementAction`. The builder then adds its universal Action and JSON key/value editor; runtime merging behaves exactly like built-in buttons and links.

```ts
import { definePageElement, type ActionProps } from '@cocoar/vue-page-builder'

type ActionChipProps = ActionProps & { label: string }

export const actionChip = definePageElement<ActionChipProps>({
  action: true,
  renderer: ActionChipRenderer,
  builder: {
    label: { key: 'app.pb.actionChip', fallback: 'Action chip' },
    icon: 'bolt',
    defaults: () => ({ label: 'Run' }),
  },
})
```

```vue
<script setup lang="ts">
import { usePageElement, type ActionProps, type ElementNode } from '@cocoar/vue-page-builder'

defineProps<{ node: ElementNode<string, ActionProps & { label: string }> }>()
const ctx = usePageElement()
</script>

<template>
  <button type="button" @click="ctx.triggerElementAction(node.props)">{{ node.props.label }}</button>
</template>
```

Do not manually merge form data with `actionValues`: the shared trigger path applies the documented precedence (**form < resolved per-key action values < legacy dynamic action value**), removes invalid runtime values, and preserves the renderer's async-action guard.

### 3. Value-model participation

Declaring a `value` spec makes the element a managed field whenever the node carries a `name`: it seeds defaults, joins `required`/`matchField` gating, and its value is included in action payloads.

```ts
value: {
  // A rating edits number fields (field-contract compatibility).
  types: ['number'],
  // What "empty" means for validation.required — a 0-star rating is empty.
  isEmpty: (v) => !v || Number(v) === 0,
}
```

The full spec:

```ts
interface ElementValueSpec<P> {
  /** Value types this element can edit — matched against the field
      contract's `PageFieldSpec.valueType`. Omitted = unconstrained. */
  types?: PageValueType[];
  /** Opt into the host-enforced string rules
      (validation.minLength / maxLength / pattern, and the built-in
      email check when the bag carries inputType: 'email'). */
  textRules?: boolean;
  /** May a plain Enter inside this element submit the page (fire the
      default button)? Only effective when the page root sets
      `enterSubmits`. Boolean, or a per-props predicate
      (text-input: (p) => (p.rows ?? 1) <= 1). Undeclared = never. */
  submitOnEnter?: boolean | ((props: P) => boolean);
  /** Fallback default when the node carries no `defaultValue`. Declare it —
      it keeps untouched fields PRESENT in ActionValues (the built-ins seed
      '' for strings, false for booleans, [] for multi-select, null for
      "nothing picked/entered"). */
  defaultValue?: (props: P) => unknown;
  /** Emptiness test for `validation.required`.
      Default: undefined | null | '' | false | [] count as empty. */
  isEmpty?: (value: unknown, props: P) => boolean;
  /** Element-owned validation, run after required/matchField.
      Return an error message, or null when valid. Crash-guarded by the host. */
  validate?: (value: unknown, node: ElementNode<string, P>, values: ActionValues) => string | null;
}
```

The host enforces `validation.required` (via your `isEmpty`) and `matchField` for every valued element; the string rules (`minLength` / `maxLength` / `pattern`) are host-enforced only for definitions that opt in via `textRules` — they need the localized message pipeline and the crash-safe pattern compiler, so the host runs them (the built-in `text-input` and `password-input` set it; any consumer element with a string value can too). `types` declares which [field-contract](./#field-contract) value types the element can edit — omitted means unconstrained (compatible with every field), so declare them to show up for the right DTO fields: the rating's `types: ['number']` is exactly what makes it a representation for `number` fields. Everything else goes through `validate`; error messages it returns are yours to localize.

### 4. The builder half

Everything editor-facing sits under `builder`. Omit the whole block for renderer-only registrations (see [the contract-package pattern](#the-two-module-contract-package-pattern)).

**Canvas preview** — receives `{ node, resolveAsset? }` as props and is mounted **inert** (`pointer-events: none`; clicks select the node). It renders from the node alone — it never gets the runtime renderer context, so it must not use `usePageElement()`:

```vue
<!-- RatingPreview.vue -->
<script setup lang="ts">
import { CoarFormField } from '@cocoar/vue-ui';
import type { ElementNode } from '@cocoar/vue-page-builder';
import RatingStars from './RatingStars.vue';
import type { RatingProps } from './ratingProps';

defineProps<{
  node: ElementNode<string, RatingProps>;
  resolveAsset?: (id: string) => string;
}>();
</script>

<template>
  <CoarFormField :label="node.props.label" :required="node.validation?.required">
    <RatingStars :model-value="Number(node.defaultValue ?? 0)" :max="node.props.max" readonly />
  </CoarFormField>
</template>
```

If you skip `preview`, the canvas shows a neutral icon + label chip — perfectly serviceable for elements whose appearance doesn't matter while authoring.

**Inspector** — the element's own section in the props panel. Receives `{ node, patch }`; `patch({ props: {…} })` merges into the props bag with delete-on-empty semantics per key and goes through the builder's undo history:

```vue
<!-- RatingInspector.vue -->
<script setup lang="ts">
import { CoarFormField, CoarTextInput, CoarNumberInput } from '@cocoar/vue-ui';
import type { ElementNode } from '@cocoar/vue-page-builder';
import type { RatingProps } from './ratingProps';

defineProps<{
  node: ElementNode<string, RatingProps>;
  patch: (update: { props?: Partial<RatingProps> }) => void;
}>();
</script>

<template>
  <CoarFormField label="Label">
    <CoarTextInput
      :model-value="node.props.label ?? ''"
      @update:model-value="(v) => patch({ props: { label: v } })"
    />
  </CoarFormField>
  <CoarFormField label="Max stars">
    <CoarNumberInput
      :model-value="node.props.max"
      :min="1"
      :max="10"
      @update:model-value="(v) => patch({ props: { max: v ?? 5 } })"
    />
  </CoarFormField>
</template>
```

The inspector only edits the **props bag**. Field name, required and default value live in the host-owned Field section — see [What the host owns](#what-the-host-owns). Option-list elements can reuse the exported `OptionsEditor` component (`import { OptionsEditor } from '@cocoar/vue-page-builder'`).

**Typed default-value editor** — the Field section's "Default value" control is a plain text input unless the definition supplies one. Contract: `{ modelValue, props }` in, `update:modelValue` out:

```vue
<!-- RatingDefaultInput.vue -->
<script setup lang="ts">
import RatingStars from './RatingStars.vue';
import type { RatingProps } from './ratingProps';

defineProps<{
  modelValue: unknown;
  props: RatingProps;
}>();

const emit = defineEmits<{ 'update:modelValue': [value: unknown] }>();
</script>

<template>
  <RatingStars
    :model-value="Number(modelValue ?? 0)"
    :max="props.max"
    @update:model-value="(v) => emit('update:modelValue', v || undefined)"
  />
</template>
```

### 5. The definition

`definePageElement` is an identity helper that preserves the props-bag generic for the hooks and `markRaw`s the component fields (definitions travel through reactive config objects):

```ts
// ratingElement.ts
import { definePageElement } from '@cocoar/vue-page-builder';
import type { RatingProps } from './ratingProps';
import RatingRenderer from './RatingRenderer.vue';
import RatingPreview from './RatingPreview.vue';
import RatingInspector from './RatingInspector.vue';
import RatingDefaultInput from './RatingDefaultInput.vue';

export const ratingElement = definePageElement<RatingProps>({
  renderer: RatingRenderer,
  value: {
    // A rating edits number fields (field-contract compatibility).
    types: ['number'],
    // required = at least one star.
    isEmpty: (v) => !v || Number(v) === 0,
  },
  builder: {
    label: { key: 'acme.pb.type.rating', fallback: 'Rating' },
    icon: 'star',
    defaults: () => ({ label: 'Rating', max: 5 }),
    preview: RatingPreview,
    inspector: RatingInspector,
    inspectorTitle: { key: 'acme.pb.section.rating', fallback: 'Rating' },
    defaultValueInput: RatingDefaultInput,
  },
});
```

The remaining definition fields at a glance:

| Field | Effect |
|-------|--------|
| `container: true` | Node gets a `children` array, canvas dropzones, and the container style fields (gap, justify, align). The **host** renders the children into your renderer's default slot — recursion, allow-gating and direction context stay centralized. |
| `inline: true` | Leaf gets the `width: fit-content` treatment (like button/link) instead of stretching. |
| `builder.group` | Palette grouping: `'container'` or `'element'` (default). The `'element'` group is presented split by value-spec presence: value elements show under **Inputs** (the offering `hideElementPicker` removes), the rest under **Elements**. |
| `builder.hideStyleSection` | Suppresses the universal Style section for spacer-style minimal elements. |
| `builder.quickProperties` | Optional Properties-panel shortcuts that write locked Element Code assignments. Mark human copy with `valueKind: 'localized-text'`; the Builder then stores a translation key and edits its values in the central Translations tab. Leave layout, identifiers and enum values literal. |
| `builder.lint` | `(node, config?) => { severity: 'error' \| 'warning'; message: I18nText }[]` — authoring diagnostics merged into the builder's validation panel. Lint never blocks saving. |
| `normalizeProps` | `(raw: unknown) => P` — ingest healing for the props bag (untrusted JSON). Runs crash-guarded inside `normalizePageSchema` on every builder ingest path (v-model, JSON tab) and wherever the server passes `{ elements }`. Return the input unchanged (same reference) when nothing needs healing. |

Labels and lint messages are `I18nText` pairs — `{ key, fallback }`, translated via `@cocoar/vue-localization` with the fallback used when the key isn't registered. English-only apps need no i18n setup.

::: warning `value` + `container` on one element
The flags compose — an element can carry a value **and** accept children (say, a toggleable group), and the runtime handles both. Two authoring caveats, though: the builder **canvas** renders the generic children body for containers, so such an element's own chrome only shows in the Preview tab (a `builder.preview` on a container definition is never mounted — DEV warns about it), and the representation switcher refuses targets that would drop children (`convertTo` guards against it). If you hit this combination in earnest, tell us — full canvas support needs a designed preview-with-children contract.
:::

## Registering

There is deliberately **no global `register()`** — registries are per-instance data, so two builders with different element sets can coexist. Two channels:

**Per instance, via `config.elementTypes`** (wins when both are present):

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

const config: PageConfig = {
  elements: { 'acme-rating': ratingElement },
  // …
};
```

Pass the same `config` to both `<CoarPageBuilder>` and `<CoarPageRenderer>` — one registration serves palette, canvas, inspector and runtime.

**App-wide default, via `app.provide`:**

```ts
// main.ts
import { PAGE_ELEMENT_TYPES_KEY } from '@cocoar/vue-page-builder';
import { ratingElement } from './rating/ratingElement';

app.provide(PAGE_ELEMENT_TYPES_KEY, { 'acme-rating': ratingElement });
```

Every builder/renderer in the app without its own `config.elementTypes` picks these up.

### `allowedElements` composition

`config.allowedElements` takes built-in types and consumer keys in one list — a consumer element is gated exactly like a built-in (hidden from the palette, blocked on the canvas, skipped by the renderer when absent):

```ts
allowedElements: [
  'stack', 'card', 'heading', 'paragraph',
  'text-input', 'checkbox', 'button',
  'acme-rating',
],
```

Registration makes an element *available*; `allowedElements` (when present) decides whether it's *permitted*. Omitting `allowedElements` allows everything registered.

### Keys

Consumer keys must match `^[a-z][a-z0-9-]*$` — lowercase kebab-case, colon-free (so keys survive stricter grammars such as markdown embeds). **Prefix your keys with a vendor namespace** (`acme-rating`, not `rating`): registration merges *additively* over the built-in set, and shadowing an existing key triggers a DEV warning — an unprefixed `rating` would silently collide the day the library ships a built-in of the same name. `mergeElementRegistries` is exported if you need to compose registries yourself.

## The two-module contract-package pattern

The definition splits into a **renderer half** (top level: `renderer`, `value`, `container`, `inline`) and an optional **builder half** (`builder: {…}`). Runtime apps that only ever render pages should not pull inspector/preview components into their bundle. Ship elements as a small contract package with two entry points:

```ts
// @acme/page-elements/renderer — imported by BOTH apps
import { definePageElement } from '@cocoar/vue-page-builder';
import RatingRenderer from './RatingRenderer.vue';

export const ratingRendererHalf = definePageElement<RatingProps>({
  renderer: RatingRenderer,
  value: { types: ['number'], isEmpty: (v) => !v || Number(v) === 0 },
});
```

```ts
// @acme/page-elements/builder — imported by the ADMIN app only
import { definePageElement } from '@cocoar/vue-page-builder';
import { ratingRendererHalf } from './renderer';
import RatingPreview from './RatingPreview.vue';
import RatingInspector from './RatingInspector.vue';
import RatingDefaultInput from './RatingDefaultInput.vue';

export const ratingElement = definePageElement<RatingProps>({
  ...ratingRendererHalf,
  builder: {
    label: { key: 'acme.pb.type.rating', fallback: 'Rating' },
    icon: 'star',
    defaults: () => ({ label: 'Rating', max: 5 }),
    preview: RatingPreview,
    inspector: RatingInspector,
    defaultValueInput: RatingDefaultInput,
  },
});
```

The runtime app registers `{ 'acme-rating': ratingRendererHalf }`, the admin app `{ 'acme-rating': ratingElement }` — same key, same wire format, no builder-only code in the runtime bundle. A definition without a `builder` half renders fine but never appears in the palette.

## Degradation and compatibility

A document is data; the registry is code. The two can disagree — a document authored against a newer library version, an element the current app didn't register, or a type outside `allowedElements`. The policy is **lossless and lenient**:

| Situation | Builder canvas | Builder JSON tab | Runtime renderer | Value model |
|-----------|----------------|------------------|------------------|-------------|
| **Unregistered type** (unknown to this app) | Red "Unknown type — skipped at runtime" treatment; node stays selectable, movable, deletable | Normalize *warning* — Apply is **not** blocked (only structural errors block), node round-trips byte-for-byte incl. its `children` | Skipped, one `console.warn` per type | Excluded — contributes no defaults, **cannot veto submit** |
| **Registered but not in `allowedElements`** | Same blocked treatment + validation error; hidden from palette/add menu | Pasteable, kept | Skipped (this is the security boundary) | Excluded, same non-veto rule |
| **v1 document** (pre-GA flat props, `schemaVersion` absent or `1`) | Migrated to the v2 props bag on ingest (`migrateV1PropsBag`, idempotent), missing names added and `schemaVersion: 6` stamped | Migrated on Apply | Migrated on the fly | Normal |

The non-veto rule matters: a `required` field of a type this deployment can't render would otherwise permanently block every `validates: true` button. Submission is therefore **lenient by design** — an invisible field can't veto submit. If a document must not execute with fields missing, enforce that server-side against the payload.

Server-side, the same ingest pipeline is exported: `normalizePageSchema(value, options?)` returns `{ schema, issues, changed }` with per-issue `severity: 'error' | 'warning'` (`error` = data was dropped, `warning` = healed or lossless), and runs the legacy-type and v1→v2 migrations first. Pass `{ elements }` to make it registry-aware: registered consumer types then count as known (no unknown-type warning, container recursion honours `container: true`) and each definition's `normalizeProps(raw)` hook runs as a crash-guarded healing pass over the props bag — the element's own ingest gate for untrusted JSON. Without the option you get the registry-less structural pass. `migrateV1PropsBag` is exported separately.

## What the host owns

When writing an element, you own the props bag and the components. Everything else is host machinery you get for free — and must not re-implement:

* **Field section** — the props panel renders name / required / default-value controls automatically whenever the definition has a `value` spec. Your inspector never edits `node.name`, `node.validation` or `node.defaultValue`; supply `defaultValueInput` if the default needs a typed editor.
* **Style section** — the universal `NodeStyle` editor (size, alignment, gap, padding; container fields keyed off `container`). Elements don't define their own layout props — `props` is for element vocabulary, `style` is host-owned.
* **Drag and drop** — palette entry, canvas dropzones, outline reorder, duplicate, undo/redo. Dropzone legality derives from `container`; a freshly dropped node gets `id`, `props` from your `defaults()`, a minted `name` when the definition has a `value` spec (under a strict [field contract](./#field-contract) — `config.dataContract` set, `allowCustomFields` off — fresh value elements start unbound instead, and the author binds a contract field), and `children: []` when it's a container.
* **The allow gate** — `allowedElements` filtering in palette, canvas and renderer, including the value-model exclusion. Renderers never need to check it.
* **Conditional visibility** — [`visibleWhen`](./coar-page-renderer#conditional-visibility-visiblewhen) is host vocabulary: the host hides the node (your renderer simply isn't mounted) and excludes its subtree from the value model. Never re-implement show/hide inside a renderer — a hidden-by-you `required` child would still veto submits.
* **Enter-to-submit** — declare eligibility (`value.submitOnEnter`); the host wires the keydown routing and the default-button resolution. No key handlers needed in your renderer.
* **Value plumbing** — default seeding (`node.defaultValue ?? value.defaultValue?.(props)`), the renderer's [`initialValues` host prefill](./coar-page-renderer), touched-state, error computation ordering (required → string rules/email → matchField → your `validate`), the busy/submit lifecycle (`isSubmitting`, reentry guards, the form-error banner), and action payload assembly (allowed + visible fields, snapshot).

Registered element components are **trusted consumer code** — the library does not sandbox them. The tenant-facing security boundary remains `allowedElements` plus the renderer's `actions` map; the registry is a developer-facing extension surface.

---

---
url: /components/page-builder/idp-integration.md
description: >-
  Integrate Page Builder 2.20 into an identity provider with isolated SES Worker
  sessions, host-owned capabilities, versioned documents and
  server-authoritative publication.
---

# IDP integration

Page Builder ships the complete browser runtime and nothing auth-specific.
Login, consent and the rest are built from the same generic registry, Repeat,
selection, action and styling contracts as every other consumer page.

## Public integration surface

```ts
import {
  definePageRuntimeHost,
  usePageCodeRuntime,
  validatePageDocument,
} from '@cocoar/vue-page-builder';
```

The package ships no auth-specific configuration or documents. An IDP builds
its own `PageConfig` — fields, actions, context and states for `login`,
`password-forgot`, `logout` and `consent` — and stores the starting documents
itself; `apps/playground/src/views/auth-customization/` is a worked example.
The runtime contains no auth element types or branches.

## Ownership boundary

| Concern | Owner |
|---|---|
| Structure, styles, translations, Page State and Element Code | Page document |
| Element/action/context allowlists | IDP `PageConfig` |
| API facades and grants | Application `PageRuntimeHost` |
| Login, consent, tickets, redirects and authorization | IDP backend |
| Drafts, revisions, publish, rollback and audit | IDP persistence layer |

Resolve the application/client theme in the host, then use the generic UI
scope for runtime and the Builder's preview-only prop for authoring:

```vue
<CoarThemeScope :theme="applicationTheme" mode="auto">
  <CoarPageRenderer :schema :config />
</CoarThemeScope>

<CoarPageBuilder
  v-model="schema"
  :config="config"
  :preview-theme="applicationTheme"
  preview-theme-mode="dark"
/>
```

The Builder applies `previewTheme` only around its embedded renderer; toolbar,
properties, dialogs and Monaco retain the administration application's theme.
Brand colours, radii and fonts travel through `CoarTheme`; anything beyond it
is authored as node styles or as a `visual-markup` element. The document never
carries a CSS class from the host.

## Monaco workers in the authoring application

The Builder uses Monaco in JavaScript and JSON mode. A Vite consumer must route
both languages to their matching workers before the first Builder mounts:

```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(_workerId, label) {
    if (label === 'typescript' || label === 'javascript') return new TsWorker();
    if (label === 'json') return new JsonWorker();
    return new EditorWorker();
  },
};
```

Routing `json` to the generic editor worker causes diagnostics such as
`Missing requestHandler or method: doValidation`, `findDocumentColors` or
`getFoldingRanges`. This is a consumer worker configuration error, not a
PageBuilder runtime or sandbox failure.

Create one application-wide host. Each `usePageCodeRuntime()` instance creates
an isolated Worker session for one rendered page; sessions do not share globals
or Page State. A host object is available to tenant code only when it exists in
the host catalogue and the grant policy returns its name for that exact runtime
definition.

```ts
const runtimeHost = definePageRuntimeHost({
  endowments: { api: idpPageApiFacade },
  grants: ({ pageId, definition }) =>
    pageId.startsWith('auth:') && definition.id.startsWith('element-action:')
      ? ['api']
      : [],
});
```

Without a grant there is no `api`; there is never ambient `window`, `fetch`, DOM
or filesystem access in Element Code.

For Vite 8, keep only the Worker-bearing runtime subpath outside dependency
pre-bundling:

```ts
optimizeDeps: {
  exclude: ['@cocoar/vue-page-builder/runtime-worker'],
}
```

The main PageBuilder package and all UI/editor dependencies remain optimized.
The packed-consumer matrix verifies forced development optimization and the
production Worker asset on both Linux and Windows.

## Publication boundary

Save drafts as immutable, versioned documents and activate a revision only after
trusted server validation. The browser's `validatePageDocument()` provides the
same fast feedback to the author but cannot authorize publication. Keep a known
good default and published revision so invalid or unavailable customizations can
fall back without breaking authentication.

The complete storage lifecycle, Vue wiring, capability example and production security
boundary are included in the package's `IDP_INTEGRATION.md`.

---

---
url: /components/document-viewer.md
description: >-
  Source-agnostic document viewer for Vue 3 — CoarDocumentViewer renders PDFs,
  images, and image galleries with shared toolbar chrome, side panels, and an
  annotation layer.
---

# 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
description: >-
  CoarDocumentViewer component reference — the source prop, toolbar and
  side-panel chrome toggles, annotation surface props, and v-model panel open
  state.
---

# 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
description: >-
  CoarDocumentViewer toolbar customization — the order-driven tools array of
  tool identifiers, separator trimming rules, and the full
  CoarDocumentViewerTool reference.
---

# 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
description: >-
  CoarDocumentViewer annotation layer — controlled marker, comment, ink, and
  freetext annotations; the consumer owns the data and applies
  create/update/delete events.
---

# 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/map.md
description: >-
  CoarMap, a standalone data-driven Leaflet map for Vue 3 that renders pins,
  routes, popups and a legend from MapData plus MapConfig.
---

# Map&#x20;

An interactive [Leaflet](https://leafletjs.com/) map for Vue 3. `<CoarMap>` is
**standalone and data-driven**: you feed it resolved `MapData` + `MapConfig` and
it renders pins, a route, popups and an optional legend. It has **no dependency
on — and no knowledge of — markdown or any embedding layer**; resolving a source
(a store, an API, a `:::map{id}` directive) into `MapData` is the consumer's job.

::: info Separate package

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

`leaflet` is a regular dependency, imported **lazily** at runtime — `vue` is the
only peer. Import the component stylesheet once (it carries the pin, legend and
layout styles); Leaflet's own CSS is still loaded lazily by the component:

```ts
import '@cocoar/vue-map/styles';
```

:::

::: tip Authoring maps?
This page is the **viewer**. To place, move and edit points visually, see
[**CoarMapEditor**](/components/map/editor) — the write counterpart, same data.
:::

The list on the right is **not** part of `<CoarMap>` — it's built by the demo from
the exported `fallbackEntries` helper and wired to the map via the
[interactive bridge](#interactive-bridge). Click a row to fly to it, hover to
highlight, click a marker to select it back.

## Quick start

```vue
<template>
  <CoarMap :data="data" :config="config" />
</template>

<script setup lang="ts">
import { CoarMap, type MapData, type MapConfig } from '@cocoar/vue-map';

const config: MapConfig = {
  defaultBasemap: 'osm',
  basemaps: [
    { id: 'osm', url: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', attribution: '© OpenStreetMap' },
  ],
  categories: [
    { id: 'sight', label: 'Sights', emoji: '🏛️', color: '#a855f7' },
  ],
};

const data: MapData = {
  type: 'route',
  points: [
    { lat: 51.4995, lng: -0.1248, kind: 'stop', label: 'Westminster', category: 'sight' },
    { lat: 51.5194, lng: -0.1270, kind: 'stop', label: 'British Museum', category: 'sight' },
  ],
};
</script>
```

## Data

| Field | Type | Description |
|---|---|---|
| `type` | `'single' \| 'multi' \| 'route'` | `route` draws a polyline through all points; others just place markers. |
| `caption` | `string?` | Shown under the map. |
| `basemap` | `string?` | Basemap id; falls back to `config.defaultBasemap`. |
| `viewport` | `{ centerLat, centerLng, zoom }?` | Fixed view; when omitted the map **auto-fits** all points. |
| `points` | `MapPoint[]` | The markers + route vertices. |

A **`MapPoint`**:

| Field | Type | Description |
|---|---|---|
| `lat` / `lng` | `number` | Position. |
| `kind` | `'stop' \| 'shape'` | `stop` = a marker; `shape` = a route/line vertex. |
| `label` | `string?` | Hover tooltip + popup title. |
| `note` | `string?` | Extra line in the click popup. |
| `category` | `string?` | *(stop only)* category id → marker color + legend. |
| `icon` | `string?` | *(stop only)* emoji override (else the category's emoji). |

Markers: a **stop** is a category-colored pin (emoji = `icon` or the category's);
a **named shape** point is a small dot; an **unnamed shape** point draws no
marker (it only contributes to the route line + auto-fit bounds).

## Config

| Field | Type | Description |
|---|---|---|
| `defaultBasemap` | `string` | Basemap id used when a map specifies none. |
| `basemaps` | `MapBasemap[]` | Tile sources (`{ id, url, subdomains?, attribution?, maxZoom? }`). |
| `categories` | `MapCategory[]?` | `{ id, label, emoji?, color }` — drives stop colors + the legend. |

Pass it per-instance via `config`, or app-wide:

```ts
import { COAR_MAP_CONFIG_KEY } from '@cocoar/vue-map';
app.provide(COAR_MAP_CONFIG_KEY, config); // a per-instance `config` prop still wins
```

::: info Google basemaps
Out of scope for now. A basemap flagged `google: true` is **skipped** in favour
of the default. The `google` / `googleType` fields are kept on `MapBasemap` so a
registry can carry them for a future release.
:::

## Interactive bridge

The component renders the map; **the list/layout around it is the consumer's
job** (the data is yours, and `fallbackEntries(data, config)` gives ready-made
rows — each carrying its `index` into `data.points`). What a consumer *can't* do
alone is drive the map from outside, so `<CoarMap>` exposes exactly that:

| API | Direction | Description |
|---|---|---|
| `v-model:selected` | both | Selected point index. Set it to ring a marker; reads back when a marker is clicked. |
| `@point-click` | map → out | `{ point, index }` when a marker is clicked. |
| `focusPoint(index)` | out → map | Pan to the point, open its popup, select it. *(exposed method)* |
| `highlightPoint(index \| null)` | out → map | Transient hover emphasis on a marker. *(exposed method)* |

```vue
<script setup lang="ts">
import { ref, computed } from 'vue';
import { CoarMap, fallbackEntries } from '@cocoar/vue-map';

const mapRef = ref<InstanceType<typeof CoarMap>>();
const selected = ref<number | null>(null);
const rows = computed(() => fallbackEntries(data, config));
</script>

<template>
  <CoarMap ref="mapRef" v-model:selected="selected" :data="data" :config="config" />
  <ul>
    <li
      v-for="row in rows"
      :key="row.index"
      :class="{ active: selected === row.index }"
      @click="mapRef?.focusPoint(row.index)"
      @mouseenter="mapRef?.highlightPoint(row.index)"
      @mouseleave="mapRef?.highlightPoint(null)"
    >{{ row.emoji }} {{ row.label }}</li>
  </ul>
</template>
```

## Legend & caption

The legend is **off by default**. Set `show-legend` to enable it — it then
appears when **≥ 2 categories** are present among the stops, listing each
category's swatch + label. The `caption` from `MapData` renders below the map.

```vue
<CoarMap :data="data" :config="config" show-legend />
```

## Lazy loading & fallback

Leaflet (JS **and** CSS) is imported in `onMounted`, so it loads only on pages
that actually render a map (your bundler code-splits it into its own chunk).
Until the map hydrates — and if Leaflet ever fails to load, or with JS off — a
crawlable `<ol>` of the named points is shown and then hidden once the map is
live. The map container's height is `--coar-map-height` (default `360px`).

## Security

Point text (`label`, `note`, `icon`) is treated as untrusted: popups are built
from DOM **text nodes** (never an HTML string), tooltips and the marker emoji are
HTML-escaped, and a category color is guarded before it reaches an inline style.
A hostile label can't break out into markup.

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `data` | `MapData` | *required* | The resolved map data. |
| `config` | `MapConfig` | *provide* | Basemaps + categories. Falls back to `COAR_MAP_CONFIG_KEY`. |
| `selected` | `number \| null` | `null` | Selected point index (`v-model:selected`). |
| `showLegend` | `boolean` | `false` | Show the legend (then needs ≥ 2 categories). |

## Using it as a markdown embed

`<CoarMap>` and the [markdown custom-embed](/components/markdown-embeds) system are
fully independent. To show a map inside markdown, a consumer registers a small
wrapper that resolves the directive's id into `MapData` and renders `<CoarMap>`:

```ts
// the wrapper is the CONSUMER's — it bridges markdown ↔ map; neither package
// depends on the other.
const embeds = {
  map: {
    viewer: defineComponent({
      props: { id: { type: String, required: true } },
      setup: (props) => () => h(CoarMap, { data: resolveMap(props.id), config }),
    }),
  },
};
```

---

---
url: /components/map/editor.md
description: >-
  CoarMapEditor, the write counterpart of CoarMap: place, move, edit, reorder
  and delete points visually, emitting fresh MapData via v-model.
---

# Map Editor&#x20;

A visual editor for [`<CoarMap>`](/components/map/) data. `<CoarMapEditor>` is the
**write counterpart** of `<CoarMap>`: same `MapData` + `MapConfig`, but you can
**place, move, edit, reorder and delete** points directly on the map, with every
change flowing out through `v-model:data`. Like `<CoarMap>` it is **standalone** —
no dependency on, or knowledge of, markdown or any embedding layer.

::: info Same package as the map

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

`CoarMapEditor` ships alongside `CoarMap` and is tree-shakeable — pages that only
render `<CoarMap>` don't pull in the editing weight. Leaflet is imported
**lazily** at runtime. Import the component styles once with
`import '@cocoar/vue-map/styles'` (as for the viewer). The editor's built-in form
uses the Cocoar UI controls, so `@cocoar/vue-ui` is an **optional peer** — install
it when you use the editor; viewer-only `<CoarMap>` consumers don't need it.
:::

## Quick start

```vue
<template>
  <CoarMapEditor v-model:data="data" :config="config" />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { CoarMapEditor, type MapData, type MapConfig } from '@cocoar/vue-map';

const config: MapConfig = {
  defaultBasemap: 'osm',
  basemaps: [
    { id: 'osm', url: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', attribution: '© OpenStreetMap' },
  ],
  categories: [{ id: 'sight', label: 'Sights', emoji: '🏛️', color: '#a855f7' }],
};

const data = ref<MapData>({
  type: 'route',
  points: [
    { lat: 51.4995, lng: -0.1248, kind: 'stop', label: 'Westminster', category: 'sight' },
    { lat: 51.5194, lng: -0.127, kind: 'stop', label: 'British Museum', category: 'sight' },
  ],
});
</script>
```

`data` is **controlled**: the editor never mutates your object, it emits a fresh
`MapData` on every edit. The data contract (`MapData`, `MapPoint`, `MapConfig`)
is identical to [`<CoarMap>`](/components/map/#data) — read that page for the
field-level reference.

## Editing

| Gesture | Result |
|---|---|
| **Click an empty spot** | Adds a point — type-aware: `route` / `multi` **append** a stop, `single` **moves** the one point. The new point is **not** auto-opened, so dropping several in a row stays fluid. |
| **Drag a marker** | Moves that point; the route polyline follows **live**, `update:data` fires on drop. |
| **Click a marker** | Selects it and opens the **property popup** (see below). |
| **Click the route line** | Inserts a waypoint **exactly there**, snapped to the nearest segment. |
| **Click away · `Esc` · popup ×** | Closes the popup (deselects). Clicking empty space **while a point is selected dismisses it** — it does *not* add a point. |

Every point gets a draggable handle — including the unnamed `shape` vertices that
`<CoarMap>` draws as pure line geometry — so route shapes are editable too. Set
`readonly` to freeze all of this (the editor then behaves like `<CoarMap>`).

## Property popup

Selecting a point opens a small popup anchored over its marker. The built-in form
is rendered with the Cocoar UI controls (`CoarTextInput`, `CoarSelect`,
`CoarButton`) so it matches the design system; it edits `label`, `note`,
`category` and `icon` (for stops), toggles a point between **stop** and
**vertex**, **reorders** route waypoints (↑ / ↓) and **deletes** the point. It
flips below the marker automatically when there isn't room above. Close it with
the **×**, **`Esc`**, or by clicking empty map space (which dismisses rather than
adding a point).

Override it entirely with the **`#point-form`** slot to drop in your own
controls (e.g. design-system inputs):

```vue
<CoarMapEditor v-model:data="data" :config="config">
  <template #point-form="{ point, index, update, remove, moveUp, moveDown }">
    <CoarTextInput :model-value="point.label" @update:model-value="(v) => update({ label: v })" />
    <button @click="moveUp">Up</button>
    <button @click="moveDown">Down</button>
    <button @click="remove">Delete</button>
  </template>
</CoarMapEditor>
```

| Slot prop | Type | Description |
|---|---|---|
| `point` | `MapPoint` | The selected point. |
| `index` | `number` | Its index in `data.points`. |
| `update` | `(patch: Partial<MapPoint>) => void` | Apply a partial change to the point. |
| `remove` | `() => void` | Delete the point. |
| `moveUp` / `moveDown` | `() => void` | Reorder the point earlier / later. |

## Imperative bridge

A consumer-built toolbar or point list can drive edits through exposed methods —
the same hooks as `<CoarMap>` plus the editing operations:

| API | Description |
|---|---|
| `v-model:selected` | Selected point index (rings the marker, opens the popup). |
| `@point-click` | `{ point, index }` when a marker is clicked. |
| `addPoint(lat, lng, init?)` | Add a point (type-aware), like a map click. |
| `updatePoint(index, patch)` | Patch a point's fields. |
| `removePoint(index)` | Delete a point. Selection follows (stays on the same point, or clears). |
| `reorder(from, to)` | Move a point within the order. Selection tracks the same point. |
| `captureViewport()` | Save the current center + zoom into `data.viewport`. |
| `focusPoint(index)` / `highlightPoint(index \| null)` | Pan-to-and-select / transient hover emphasis. |

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

const editor = ref<InstanceType<typeof CoarMapEditor>>();
</script>

<template>
  <button @click="editor?.captureViewport()">Save current view</button>
  <CoarMapEditor ref="editor" v-model:data="data" :config="config" />
</template>
```

## Point list (`CoarMapPointList`)

A ready-made, drop-anywhere point list ships in the package so you don't rebuild
it per app. It's **controlled** (`v-model:data` / `v-model:selected`) and stays
decoupled from the map — bind both to the same refs as the editor, and wire its
`focus` / `highlight` events to the map's exposed methods for fly-to + hover.

```vue
<CoarMapEditor ref="editor" v-model:data="data" v-model:selected="sel" :config="config" />

<CoarMapPointList
  v-model:data="data"
  v-model:selected="sel"
  :config="config"
  reorderable
  removable
  @focus="editor.focusPoint($event)"
  @highlight="editor.highlightPoint($event)"
/>
```

| Prop / event | Description |
|---|---|
| `v-model:data` | The map data; reorder + delete emit a fresh `MapData`. |
| `v-model:selected` | Active row ↔ selected index. |
| `config` | Resolves stop emojis/labels (falls back to a point's own `icon`). |
| `reorderable` | Drag-and-drop sorting via a per-row handle (default `false`). |
| `removable` | Per-row delete button (default `false`). |
| `@focus(index)` | Row activated — wire to `focusPoint`. |
| `@highlight(index \| null)` | Row hover — wire to `highlightPoint`. |
| `#row="{ point, index, selected }"` | Override a row's content. |

It lists **every** point — including the unnamed `shape` vertices the viewer
draws as bare geometry — so the whole route order stays editable. Reordering and
deleting keep the selection on the **same point**, so the active row never
drifts. Drag-and-drop is built on Cocoar UI's `useDragDrop`. The list works next
to a read-only [`<CoarMap>`](/components/map/) too (omit `reorderable` /
`removable` for a pure navigator). Prefer your own layout? It's still the
consumer's call — the same edits are available as exposed methods (above) and as
[pure operations](#pure-editing-operations).

## Pure editing operations

The same immutable, Leaflet-free helpers the editor uses are exported, for
consumers building edits outside a map (validation, undo stacks, server sync):

```ts
import {
  addPointForType, movePoint, updatePoint, removePoint,
  reorderPoint, insertOnSegment, setViewport, nearestSegment, normalizeLatLng,
} from '@cocoar/vue-map';

const next = addPointForType(data, 51.5, -0.12);   // returns a fresh MapData
```

Each takes a `MapData` and returns a new one — your input is never mutated.

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `data` | `MapData` | *required* | The map data (`v-model:data`). |
| `config` | `MapConfig` | *provide* | Basemaps + categories. Falls back to `COAR_MAP_CONFIG_KEY`. |
| `selected` | `number \| null` | `null` | Selected point index (`v-model:selected`). |
| `readonly` | `boolean` | `false` | Freeze editing — behaves like `<CoarMap>`. |

## Events

| Event | Payload | Description |
|---|---|---|
| `update:data` | `MapData` | Emitted on every edit. |
| `update:selected` | `number \| null` | Selection changed. |
| `point-click` | `{ point, index }` | A marker was clicked. |

## Relationship to `<CoarMap>`

Use `<CoarMap>` to **display** a map and `<CoarMapEditor>` to **author** one —
they share the exact same `MapData`/`MapConfig`, so editor output drops straight
into the viewer. The editor keeps the same discipline as the viewer: Leaflet is
lazy-loaded, custom pins avoid Leaflet's broken default-icon asset path, point
text is treated as untrusted (escaped on render), and the package stays
**markdown-agnostic** — bridging a map into markdown is the consumer's job, not
the package's.

---

---
url: /components/file-explorer.md
description: >-
  Headless VSCode-style file explorer engine for Vue 3 — useFileExplorer drives
  a pluggable AssetStore backend; you compose the layout from @cocoar/vue-ui
  primitives.
---

# 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
description: >-
  useFileExplorer composable reference — options, reactive tree and tab state,
  imperative ops, and navigation returned by the file-explorer engine.
---

# 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
description: >-
  AssetStore contract for the file-explorer engine — the backend-agnostic
  read/write interface (loadTree, uploadFile, rename, move) with optional lazy
  and browse-only modes.
---

# 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
description: >-
  createInMemoryAssetStore — the reference AssetStore implementation with
  reactive latency, failure, lazy, and conflict knobs for demos, tests, and
  prototyping.
---

# 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
description: >-
  @cocoar/vue-calendar — Temporal-based Vue 3 calendar with Year, Month, Week,
  Day and Agenda views, iOS-style display variations, recurrence and standalone
  sub-views
---

# Calendar&#x20;

A Vue 3 calendar whose visible hierarchy follows the iOS calendar: **Year**, **Month**, **Day** and **Agenda**, plus fixed **Week** and **Work week** time grids for web applications. Month and Day expose their display choices as nested variations instead of flattening every renderer into the primary view switcher.

Events on the public surface use **`Temporal`** values directly (`PlainDate` for all-day, `ZonedDateTime` for timed) — there's no string parsing or implicit-zone guessing. Consumers convert their wire format (ISO strings, epoch ms, etc.) at the boundary; the calendar receives unambiguous values and runs all date math on them across DST boundaries.

```ts
import {
  // Top-level shell + composer
  CoarCalendar,
  useCalendar,
  // Sub-views — each usable standalone via a matching composable
  CoarYearView,
  CoarContinuousMonthView,
  CoarMonthListView,
  CoarMonthView,  useMonthView,
  CoarDayView,    useDayView,
  CoarWeekView,   useWeekView,
  CoarAgendaView, useAgendaView,
  // Drop-in display-zone selector (writes to a string ref consumed by `builder.timezone(ref)`)
  CoarDisplayZoneSwitcher,
  // Helper for surfacing C3 / C5 zone semantics in custom renderers
  getEventZoneHints,
  // Public types
  type CalendarEvent,
  type CalendarView,
  type ViewWindow,
  type EventZoneHints,
} from '@cocoar/vue-calendar';
```

## 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 primary view switcher, nested Month / Day display controls, and the body that dispatches to whichever view is active. **One** `useCalendar()` builder feeds it; switching views is just `api.setView('agenda')`.

```ts
const { builder, api } = useCalendar();
builder.events(events).date(date).timezone('Europe/Vienna');
```

```html
<CoarCalendar :builder="builder" />
```

::: tip Use the shell when…
You want the complete view hierarchy, navigation chrome, and a consistent feel without writing custom layout. This is the path 90 % of consumers want.
:::

### As a single sub-view

Each sub-view is exported and consumes its OWN `:builder` produced by a matching composable:

| View | Component | Composable | Builder |
|---|---|---|---|
| Year | [`<CoarYearView>`](/components/calendar/year-view) | `useCalendar()` + `.view('year')` | `CalendarBuilder` |
| Continuous Month | [`<CoarContinuousMonthView>`](/components/calendar/month-view) | `useCalendar()` + `.view('month')` | `CalendarBuilder` |
| Month List | [`<CoarMonthListView>`](/components/calendar/month-view#month-list) | `useCalendar()` + `.view('monthList')` | `CalendarBuilder` |
| Day | [`<CoarDayView>`](/components/calendar/day-view) | `useDayView()` | `CalendarBuilder` |
| Week | [`<CoarWeekView>`](/components/calendar/week-view) | `useWeekView()` | `CalendarBuilder` |
| Single Month Section | [`<CoarMonthView>`](/components/calendar/month-view#single-month-section) | `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`. RRULE / RDATE / EXDATE expand only for the visible window through the lazy bundled `rrule-temporal` engine, with occurrence provenance preserved for consumer-side series editing. |

The conformance test suite at `src/core/__tests__/timezone/` pins every invariant; CI fails if any of them slips.

## CalendarEvent shape

The library reads the layout-relevant fields (`start`, `end`, `id`); anything you put in `meta` is opaque to the engine and forwarded back to your renderer / slot. Use the generic `CalendarEvent<TMeta>` to keep your meta strongly typed.

```ts
import { Temporal } from '@js-temporal/polyfill';

interface CalendarEvent<TMeta extends Record<string, unknown> = Record<string, unknown>> {
  /** Stable id. For occurrences of a recurring event, this is the SERIES id. */
  id: string;
  /**
   * `ZonedDateTime` for timed events, `PlainDate` for all-day events.
   * The shape of `start` discriminates the event type — there is no
   * separate `allDay` flag.
   */
  start: Temporal.ZonedDateTime | Temporal.PlainDate;
  /** Exclusive end. Must match `start`'s shape. Defaults to start + slot duration (timed) / start + 1 day (all-day). */
  end?: Temporal.ZonedDateTime | Temporal.PlainDate;
  /** Anything the consumer needs in their renderer. */
  meta?: TMeta;
}
```

Construct events directly from `Temporal`:

```ts
import { Temporal } from '@js-temporal/polyfill';

// All-day event:
{ id: 'devconf', start: Temporal.PlainDate.from('2026-04-13'), end: Temporal.PlainDate.from('2026-04-16') }

// Timed event in UTC:
{
  id: 'standup',
  start: Temporal.ZonedDateTime.from('2026-04-15T09:00:00[Europe/Vienna]'),
  end:   Temporal.ZonedDateTime.from('2026-04-15T09:30:00[Europe/Vienna]'),
}

// Timed event in a specific zone:
{
  id: 'vienna-call',
  start: Temporal.ZonedDateTime.from('2026-06-15T10:00:00[Europe/Vienna]'),
  end:   Temporal.ZonedDateTime.from('2026-06-15T11:00:00[Europe/Vienna]'),
}
```

The default event renderer reads `meta.title` and `meta.color` if present. Drop those in `meta` to skip writing a custom renderer for simple cases.

## Display zone — switcher + on-card hints

Every event keeps its **source** zone (`start.timeZoneId`); the calendar renders it in whatever **display** zone the builder is configured with (`.timezone(ref)`). The two are kept separate by design — invariant C5 — so switching the display zone never destroys event intent. Two pieces of UI surface this distinction without writing any custom renderer:

```ts
import { CoarDisplayZoneSwitcher, getEventZoneHints } from '@cocoar/vue-calendar';

const tz = ref(Intl.DateTimeFormat().resolvedOptions().timeZone);
const { builder } = useCalendar();
builder.timezone(tz);
```

```html
<CoarDisplayZoneSwitcher v-model="tz" />
<CoarCalendar :builder="builder" />
```

`<CoarDisplayZoneSwitcher>` is a `<CoarSelect>` pre-populated with a curated short-list of common zones plus the browser-detected zone — pass `:options="..."` to swap in a domain-specific list (or `Intl.supportedValuesOf('timeZone')` for the full IANA roster).

The default event renderers also surface two zone semantics inline on every card:

* **Globe icon** when `start.timeZoneId === 'UTC'` — Article 5's "global event, same instant worldwide" (product launches, livestreams).
* **Cross-zone tag** (globe + accent dot) + tooltip when `start.timeZoneId` differs from the display zone — Article 3's fairness contract: we render the user's clock but don't hide where the event actually lives.

Both are rendered with `title=""` tooltips and an inline sr-only span for screen readers. The two are mutually exclusive — a UTC-anchored event in a non-UTC display gets only the global icon. Custom renderers can re-use the same logic via `getEventZoneHints(event, displayZone)`:

```ts
import { getEventZoneHints } from '@cocoar/vue-calendar';

builder.eventRenderer((ctx) => {
  const { isUtcAnchored, sourceZone } = getEventZoneHints(ctx.event, displayZone.value);
  // …draw whatever icon / chip / accent suits your design.
});
```

## Reactive configuration

Every config setter accepts `MaybeRefOrGetter<T>` — pass a static value, a `ref()`, or a `() => …` getter and Vue tracks whatever shape you give it.

```ts
const { builder } = useCalendar();

builder.timezone('Europe/Vienna');               // static
builder.timezone(timezoneRef);                   // ref
builder.density(() => narrow.value ? 'compact' : 'comfortable');  // getter / computed
```

This applies to the one flat builder shared by the shell and to every standalone sub-view builder.

## Theming

The calendar reads CSS custom properties at runtime, so themes apply the moment you set them on any ancestor — typically `:root`, the calendar's wrapper, or a per-instance class.

Two layers of tokens. **Calendar-specific** tokens are unique to this component and override only what would otherwise inherit from the design system. **Inherited DS tokens** are the shared `--coar-*` palette / type / radius scale every Cocoar component uses; they're listed here for completeness so consumers know what to set if they're embedding the calendar in a non-Cocoar host.

### Calendar-specific

| Token | Light | Dark | Purpose |
|---|---|---|---|
| `--coar-calendar-bg` | `#fff` | `#18181b` | Background of every cell, header, and band. |
| `--coar-calendar-bg-today` | `rgba(37, 99, 235, 0.04)` | `#2563eb24` | Today highlight on month cells + day-column tint. |
| `--coar-calendar-bg-weekend` | `#f6f7f9` | `#212125` | Weekend tint (Sat/Sun) on month cells + day-columns. |
| `--coar-calendar-bg-other-month` | `#fafafb` | `#131316` | Leading / trailing days outside the active month. |
| `--coar-calendar-border` | `#d1d5db` | `#3f3f46` | Cell borders, header underlines, axis dividers. |
| `--coar-calendar-grid-line` | `#e3e5e9` | `#2c2c30` | The slot-line gradient inside time-grid columns. |
| `--coar-calendar-agenda-divider` | → `--coar-calendar-border`, then `#f3f4f6` | `#27272a` | Row separator between agenda entries. |
| `--coar-calendar-event-default-bg` | → `--coar-color-accent-soft`, then `#93c5fd` | `#1e3a8a` | Fill of events without a `meta.color`. |
| `--coar-calendar-point-edge-height` | `3px` | — | Start-edge bar on point events (timed, no `end`) in Day / Week. |
| `--coar-calendar-point-body-opacity` | `0.38` | — | Body fill opacity of point events (title stays fully opaque). |
| `--coar-time-grid-axis-width` | `80px` | — | Width of the hour-axis on the left of Day / Week. |
| `--coar-time-grid-header-height` | *auto* | — | Sticky day-of-week header min-height. |

Light values are per-usage `var()` fallbacks — the tokens are undefined in light mode, so a single override anywhere wins. Dark values ship with the package stylesheet (see below).

### Inherited from the design system

Used as direct `var()` references. Override at the design-system level rather than per-calendar-instance unless you need a calendar-only variant.

| Group | Tokens |
|---|---|
| Palette | `--coar-color-accent`, `--coar-color-accent-soft`, `--coar-color-danger`, `--coar-background-accent-primary`, `--coar-background-neutral-primary`, `--coar-background-neutral-tertiary`, `--coar-surface-subtle` |
| Text | `--coar-text-base`, `--coar-text-subtle` (calendar-local names — not defined by `@cocoar/vue-ui`; dark values ship with this package), `--coar-text-neutral-primary` |
| Type | `--coar-font-size-base`, `--coar-font-size-sm`, `--coar-font-size-xs`, `--coar-body-base-family` |
| Shape | `--coar-radius-md`, `--coar-radius-xs`, `--coar-border-neutral-tertiary` |

### Dark mode

Dark values for every calendar token ship with the package stylesheet — no consumer CSS needed. They activate on either trigger:

* `.dark-mode` class on `<html>` or any ancestor (the Cocoar convention, same as `@cocoar/vue-ui`)
* `[data-theme="dark"]` attribute

The values mirror the SwiftUI port (`Cocoar.Calendar.iOS`, `CalendarTheme.dark`), so web and iOS render identically dark. Accent and danger stay scheme-invariant, and event colors provided via `meta.color` are **not** remapped in either mode — dark-safe event palettes are the consumer's responsibility.

To customize, redefine any token under the same trigger after the package styles:

```css
.dark-mode,
[data-theme='dark'] {
  --coar-calendar-bg: #101014;
}
```

::: tip RTL
Layout-mirroring for `direction: rtl` is **not yet** wired (multi-day bars, resize handles, sticky-header positioning all assume LTR). If you need RTL support, open an issue — the math is mostly localised to the bar / handle inset calc()s, but it deserves a deliberate pass with proper test coverage rather than a one-shot patch.
:::

## Performance notes

* **Variable-size virtualization.** The agenda surface uses a Fenwick-tree-backed measurement cache so every day-row keeps its natural height (header ~37 px, event ~42 px) without breaking anchor-restoration when the user scrolls.
* **No recycling pool.** Vue's keyed v-for diff turned out faster than a stable pool for typical slot content. Heavy custom renderers (charts, video) might still benefit; the surface accepts a custom recycling pool if needed.
* **Cluster-aware lane sizing.** Events with no transitive overlap render at full width even when busy parts of the same day have 3-deep stacks. Matches Google / Outlook behaviour.
* **LoAF, not rAF.** The CI perf gate measures Long Animation Frame entries; rAF FPS is unreliable under wheel-scroll on Chrome (input dispatch defers callbacks 1-2 vsync ticks without producing visual jank).

## Where to next

* **[`<CoarCalendar>` (composer)](/components/calendar/coar-calendar)** — the top-level shell + the full builder API reference.
* **[Year View](/components/calendar/year-view)** — responsive twelve-month overview and drill-in.
* **[Month Views](/components/calendar/month-view)** — continuous Compact / Stacked / Details months and responsive Month List.
* **[Day View](/components/calendar/day-view)** — one-day or width-aware multi-day time-grid surface.
* **[Week View](/components/calendar/week-view)** — 7-day time-grid + all-day band.
* **[Agenda View](/components/calendar/agenda-view)** — virtualized chronological list grouped by day.

---

---
url: /components/calendar/coar-calendar.md
description: >-
  CoarCalendar — top-level calendar shell wiring the iOS-style Year, Month, Day
  and Agenda hierarchy plus Week and Work Week, driven by the chainable
  useCalendar builder
---

# `<CoarCalendar>` — Composer&#x20;

`<CoarCalendar>` is the top-level shell that wires the complete calendar hierarchy together with prev / today / next navigation and responsive display controls. It's driven by the **builder** returned from `useCalendar()` — a single chainable surface that owns events, recurrence, 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.

## View hierarchy

The primary switcher follows iOS while keeping the fixed web time grids as useful additions:

| Primary view | Display choices |
|---|---|
| Year | Responsive twelve-month overview; selecting a day or month drills into Month. |
| Month | Compact, Stacked, Details, List. The first three use continuously scrolling 4–6-week month sections. |
| Week | Fixed seven-day time grid. |
| Work week | The Week grid filtered by `workDays(...)`. |
| Day | One day or width-aware Multi-day (1–7 complete columns). |
| Agenda | Virtualized chronological list. |

`monthList` is a serializable `CalendarView`, but the shell presents it as the **List** choice under Month. Likewise, `dayMode('single' | 'multiDay')` changes the Day renderer without adding another primary view. `dayAgenda` and `timeline` remain opt-in views and are not in the default switcher.

```ts
builder
  .availableViews(['year', 'month', 'monthList', 'week', 'workWeek', 'day', 'agenda'])
  .monthDensity('stacked')
  .dayMode('multiDay')
  .dayColumnMinWidth(220)
  .shadeWeekends(true);
```

## 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 shell forwards it to every event-rendering sub-view (and uses it 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) and is the stable boundary for occurrence-scoped editing.

### Editing a recurring occurrence

The calendar owns expansion and provenance; the host application owns persistence. When an occurrence is clicked, dragged, resized, or deleted, use `getRecurrenceMeta(event)` to offer the familiar scopes:

| Scope | Persistence operation |
|---|---|
| This occurrence | Add `recurrenceId` to the source series' EXDATE set and, for a move/edit, persist one standalone event at the new date/time. |
| This and following | Split the RRULE immediately before `recurrenceId`, then persist the following part as a new series whose DTSTART contains the edit or move. |
| Entire series | Update the original series and shift its DTSTART / RDATE / EXDATE values losslessly. |

The library deliberately does not guess a backend wire shape or perform those writes. It guarantees that every occurrence handler receives the original series id, RFC recurrence id, and source (`rrule` or `rdate`) needed to implement all three operations without identifying an occurrence by its rendered position.

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

## Create and edit integration

The calendar owns interaction geometry; the host application owns the editing experience and persistence. There is deliberately no fixed create/edit overlay because web consumers may want a popover, modal, side panel, routed page, or a completely custom view. The flat builder exposes the same integration seam for each choice:

```ts
builder
  .onDateClick(({ date, native }) => openCreate({ date, anchor: native.currentTarget }))
  .onTimeClick(({ date, time, native }) => openCreate({ date, time, anchor: native.currentTarget }))
  .onEventClick(({ event, native }) => openDetails(event, native.currentTarget))
  .onEventDoubleClick(({ event }) => openEditModal(event))
  .onEventDrop(({ event, next }) => persistMove(event.id, next));
```

`native.currentTarget` is the rendered calendar element and can be passed directly to `@cocoar/vue-ui`'s overlay service. Applications using a modal or routed editor can ignore it. For recurring events, call `getRecurrenceMeta(event)` before opening the editor so the host can offer This occurrence / This and following / Entire series; the calendar supplies stable occurrence identity but never guesses the backend mutation.

## 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 every event-rendering view 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.setMonthDensity('compact');
api.setDayMode('multiDay');
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). |
| `shadeWeekends(b)` | `MaybeRefOrGetter<boolean>` | Tint Saturday / Sunday cells and headers in Month. Default `true`; disable for the unshaded iOS appearance. |
| `monthDensity(d)` | `MaybeRefOrGetter<'compact' \| 'stacked' \| 'details'>` | Month presentation. The shell exposes these beside the optional List variation. Default `'details'`. |
| `dayMode(m)` | `MaybeRefOrGetter<'single' \| 'multiDay'>` | One fixed day or a width-aware 1–7-day surface. Default `'single'`. |
| `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`. |
| `dayColumnCount(n)` | `MaybeRefOrGetter<number>` | Minimum complete columns in Multi-day mode. Clamped to `1…7`. |
| `dayColumnMinWidth(px)` | `MaybeRefOrGetter<number>` | Target width used to derive extra Multi-day columns. |
| `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` | Common: open details, a side panel or a click-anchored popover. |
| `onEventDoubleClick(fn)` | `(payload: { event, native: MouseEvent }) => void` | Common: open the host application's edit UI. |
| `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. |
| `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;
  setMonthDensity(density: CalendarMonthDensity): void;
  setDayMode(mode: CalendarDayMode): 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/year-view.md
description: >-
  CoarYearView — responsive twelve-month calendar overview with today marker and
  drill-in to the continuous Month view
---

# `<CoarYearView>` — Year View&#x20;

Responsive twelve-month overview. The grid automatically chooses how many month cards fit across the available width, uses the configured locale / first weekday, and marks today. Selecting a month title or a day updates the builder cursor and drills into Month.

The Year view intentionally shows date structure rather than event density. It does not render event pills or occurrence markers. Loader and range-change consumers still receive the ordinary year `ViewWindow`, so applications can decide whether to return data for that surface.

## In `<CoarCalendar>`

Year is part of the default primary hierarchy. Include both `year` and `month` when filtering views so drill-in has a visible destination:

```ts
import { Temporal } from '@js-temporal/polyfill';
import { useCalendar } from '@cocoar/vue-calendar';

const { builder, api } = useCalendar();
builder
  .view('year')
  .date(Temporal.PlainDate.from('2026-08-06'))
  .timezone('Europe/Vienna')
  .locale('de-AT')
  .availableViews(['year', 'month']);

api.next(); // 2027
api.prev(); // 2026
```

```html
<CoarCalendar :builder="builder" />
```

## Standalone

`<CoarYearView>` consumes the same flat `CalendarBuilder`. There is no separate year builder because the view needs the ordinary cursor and `api.setView('month')` drill-in contract.

```ts
import { CoarYearView, useCalendar } from '@cocoar/vue-calendar';

const { builder } = useCalendar();
builder.view('year').availableViews(['year', 'month']);
```

```html
<CoarYearView :builder="builder" />
```

## Configuration

| Setter | Default | Purpose |
|---|---|---|
| `date(d)` | today in the display zone | Selects the visible year. |
| `timezone(tz)` | browser zone | Determines which date receives the today marker. |
| `locale(loc)` | `'en-US'` | Month and weekday labels. |
| `firstDayOfWeek(d)` | locale-derived | Overrides weekday order (`0` = Sunday … `6` = Saturday). |

`next()` and `prev()` move by one calendar year while Year is active. Clicking a day keeps that exact date as the Month cursor; clicking a month title selects the first day of that month.

## Prop

| Prop | Type | Description |
|---|---|---|
| `builder` | `CalendarBuilder` | **Required.** Usually from `useCalendar()`. |

---

---
url: /components/calendar/month-view.md
description: >-
  Month views — continuously scrolling Compact, Stacked and Details months,
  responsive Month List, and the lower-level CoarMonthView section
---

# Month Views&#x20;

The shell's Month view follows the iOS structure: months scroll continuously and expose **Compact**, **Stacked**, **Details**, and **List** display choices. Continuous sections render only the 4–6 weeks the month actually needs; leading and trailing positions stay blank instead of repeating neighbour dates.

| Choice | Rendering |
|---|---|
| Compact | 52 px base week rows; per-day events combine into a segmented colour capsule. |
| Stacked | 68 px base rows; compact individual event marks. |
| Details | 94 px base rows; titles, assignees, multi-day bars and row expansion. |
| List | Compact month selector plus the selected day's event list; stacked in narrow containers and side-by-side from 720 px. |

The regular Month choices use `<CoarContinuousMonthView>`. `<CoarMonthView>` remains exported as the lower-level single-month section for widgets and custom compositions.

```ts
const { builder } = useCalendar();
builder
  .view('month')
  .availableViews(['month', 'monthList'])
  .monthDensity('compact')
  .shadeWeekends(true);
```

## Continuous month

Month navigation scrolls to the requested section. Scrolling updates the builder cursor when the next month's heading reaches the top, and event / recurrence loaders preload the adjacent months. The surface initially materializes 13 months and extends in either direction while keeping a bounded DOM window.

```html
<CoarContinuousMonthView :builder="builder" />
```

## Month List {#month-list}

`monthList` is a real serialized `CalendarView`, but `<CoarCalendar>` nests it under Month as the **List** display choice. Selecting a date in the small calendar updates the builder cursor and the adjacent daily event list.

```html
<CoarMonthListView :builder="builder" />
```

## Single month section {#single-month-section}

`<CoarMonthView>` renders the fixed single-section grid used internally by the continuous composition. Multi-day events render as continuous **bars** across the rows they touch; single-day events render as **pills** inside cells. Use it directly when the host owns pagination or needs a compact embedded month.

```html
<CoarMonthView :builder="builder" />
```

## Standalone usage

```ts
import { ref } from 'vue';
import { Temporal } from '@js-temporal/polyfill';
import {
  CoarContinuousMonthView,
  CoarMonthListView,
  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 `<CoarContinuousMonthView>` and resolves `monthDensity`. Selecting List switches the serialized view to `monthList` and mounts `<CoarMonthListView>`. 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, … |
| `monthDensity(d)` | `'compact' \| 'stacked' \| 'details'` | `'details'` | Presentation used by continuous Month. |
| `shadeWeekends(b)` | `MaybeRefOrGetter<boolean>` | `true` | Shades Saturday / Sunday cells and weekday headers. Set `false` for an unshaded appearance. |
| `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 month operations. `api.goTo(...)`, `next()`, and `prev()` align the continuous surface to the requested month; a standalone `<CoarContinuousMonthView>` additionally exposes `scrollToMonth(...)` on its component ref.

## Month component 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/day-view.md
description: >-
  CoarDayView — one-day or width-aware multi-day time grid with hour axis,
  all-day band, configurable columns, time range and slot duration
---

# `<CoarDayView>` — Day View&#x20;

Time-grid surface with two display choices: **One day** renders one fixed column, while **Multi-day** derives 1–7 complete columns from the available container width. Multi-day all-day events that touch the visible range appear in the all-day band pinned under the day headers. Use it standalone via [`useDayView()`](#usedayview) when you need the surface without the [`<CoarCalendar>`](/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)`).

## One day and Multi-day

The shell presents both as variations under Day. Multi-day never squeezes partial columns into the available width: it calculates the number of full columns from `dayColumnMinWidth`, clamps the result to `1…7`, and honours `dayColumnCount` as its minimum.

```ts
builder
  .dayMode('multiDay')
  .dayColumnCount(1)
  .dayColumnMinWidth(220);

api.setDayMode('single');
```

For fixed seven-day and configured-workday grids, use [Week](/components/calendar/week-view) and [Work Week](/components/calendar/work-week-view). They share the same time-grid renderer.

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

## Point events (timed, no `end`)

A timed event without `end` keeps the default 30-minute slot geometry but renders distinguishably from a real 30-minute event: a solid start edge in the event color sits exactly on the start time, and the card body drops to ~38 % fill opacity — the title stays fully opaque. Resize handles are suppressed (there is no `end` to grab). Month and Agenda render point events unchanged. The look matches the SwiftUI port; tune it via `--coar-calendar-point-edge-height` / `--coar-calendar-point-body-opacity` (see [Theming](/components/calendar/#theming)).

## 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. |
| `dayMode(m)` | `'single' \| 'multiDay'` | `'single'` | Fixed one-day column or width-aware multi-day range. |
| `dayColumnCount(n)` | `MaybeRefOrGetter<number>` | `1` | Minimum number of complete columns in Multi-day mode. |
| `dayColumnMinWidth(px)` | `MaybeRefOrGetter<number>` | `220` | Target width used to derive additional columns, capped at seven. |
| `slotDuration(d)` | `MaybeRefOrGetter<number>` | `30` | Slot subdivision (minutes). Also the snap step when dragging. |
| `pixelsPerHour(p)` | `MaybeRefOrGetter<number>` | `60` | Vertical density. `60` = 30 px per 30-min slot. |
| `eventRenderer(r)` | `EventRenderer<TMeta>` | — | Universal renderer. Branch on `ctx.layout?.kind === 'positioned'` (timed cards) vs `'allDayBar'` (all-day band). |
| `dayHeaderRenderer(r)` | `DayHeaderRenderer` | — | Per-day column header. |

## Imperative API

```ts
interface CalendarApi<TMeta> {
  goTo(date: Temporal.PlainDate): void;
  goToToday(): void;
  next(): void;                            // ±1 day in day-view
  prev(): void;
  getVisibleRange(): ViewWindow | null;
  getVisibleEvents(): CalendarEvent<TMeta>[];
  scrollToTime(time: Temporal.PlainTime): void;   // Day / Week only
  scrollToDate(date: Temporal.PlainDate): void;   // Agenda only
  refresh(): void;
  refreshRange(window: ViewWindow): void;
  readonly loading: Readonly<Ref<boolean>>;
  readonly visibleRange: Readonly<Ref<ViewWindow | null>>;
  readonly gridReady: Readonly<Ref<boolean>>;
}
```

## `<CoarDayView>` props + slots

| Prop | Type | Description |
|---|---|---|
| `builder` | `CalendarBuilder` | **Required.** From `useDayView()` (or share the one from `useCalendar()`). |

| Slot | Scope | Purpose |
|---|---|---|
| `event` | `{ event, layout }` | Per-event renderer. `layout` is the `PositionedEvent` (lane / startMinutes / endMinutes / clipping flags). |
| `allDayEvent` | `{ event, layout }` | All-day band renderer. `layout` is the `AllDayBar` (lane / startCol / endCol / clipping flags). |
| `dayHeader` | `{ date, isToday, isWeekend }` | Per-day column header. |

---

---
url: /components/calendar/week-view.md
description: >-
  CoarWeekView — 7-day time-grid calendar view with hour axis, all-day band,
  locale-aware first day of week and a customizable day-header slot
---

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

## Point events (timed, no `end`)

A timed event without `end` keeps the default 30-minute slot geometry but renders distinguishably from a real 30-minute event: a solid start edge in the event color sits exactly on the start time, and the card body drops to ~38 % fill opacity — the title stays fully opaque. Resize handles are suppressed (there is no `end` to grab). Month and Agenda render point events unchanged. The look matches the SwiftUI port; tune it via `--coar-calendar-point-edge-height` / `--coar-calendar-point-body-opacity` (see [Theming](/components/calendar/#theming)).

## 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
description: >-
  CoarWorkWeekView — week view filtered to a configurable working-day set
  (default Mon-Fri), supporting 6-day, 4-day and Sun-Thu weeks on the same time
  grid
---

# `<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/agenda-view.md
description: >-
  CoarAgendaView — virtualized chronological agenda list grouped by day, with
  floating day headers, multi-day event continuation and imperative
  scroll-to-date
---

# `<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
description: >-
  CoarTimelineView — Gantt-lite timeline with one row per event, horizontal
  time-axis bars, automatic recurring-series row collapsing and drag-to-pan
  window
---

# `<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
description: >-
  Performance baseline for @cocoar/vue-calendar — Long Animation Frame
  measurements and targets for virtualization, 2D scrolling and drag-and-drop
  with auto-scroll
---

# 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
description: >-
  Every Cocoar component rendered on a single page for side-by-side inspection
  and light versus dark theme comparison.
---