---
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
Hello Coar
```
## 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);
```
## Mobile Presentation
Add `coar-mobile` to `body` or a local parent for touch-sized buttons and standard
inputs. The existing component APIs stay unchanged. See [Mobile presentation](./mobile)
for the supported controls, sizing floors, and overlay scope limitations.
## 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
```
## 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
```
## AI Coding Assistants
`@cocoar/vue-ui` ships an [Agent Skill](https://agentskills.io/) — a `SKILL.md` plus this
documentation page by page, with every demo inlined as a `vue` code block — so a coding assistant
in your project knows the library's API and the mistakes it would otherwise make. It sits in a
`skills/` folder at the package root and takes no part in your build: nothing is loaded unless you
install it.
Once `@cocoar/vue-ui` is installed, one command installs the skill of exactly that version:
```bash
npx @cocoar/vue-ui skill
```
It hands the package's skill folder to the [skills CLI](https://github.com/vercel-labs/skills),
which detects the agents in your project (Claude Code, Cursor, Codex, Copilot and others) and
asks where to install. Its options pass through: `-y` accepts the defaults, `-g` installs
user-wide instead of into the project, `-a claude-code` targets one agent.
Two alternatives: `npx skills add cocoar-dev/cocoar-ui-vue` takes the latest docs straight from
GitHub, and [agentskills-cli](https://mysticmind.github.io/agentskills-cli/) (a .NET tool that
also reads npm packages) installs it with `agentskills-cli add @cocoar/vue-ui`.
Either places the skill in `.claude/skills/` for Claude Code and `.agents/skills/` for the
agents that read the standard. Without a tool, copy
`node_modules/@cocoar/vue-ui/skills/cocoar-vue-ui/` into the same folder by hand.
The skill is generated from these docs, so it says what the docs say for the version you
reference. The same content is available online as [llms.txt](/llms.txt) (an index with one line
per page) and [llms-full.txt](/llms-full.txt) (everything in one file) for assistants that fetch
documentation by URL.
---
---
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
```
## 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/mobile.md
description: >-
Opt into mobile presentation with a coar-mobile parent: touch-sized buttons,
text/password/number inputs, checkboxes, radios and switches without changing
component APIs.
---
# Mobile presentation
::: warning Preview — new in 3.2
The mobile presentation is new in 3.2 and still a Preview: token names and the
set of adapted controls may change before it loses this mark.
:::
Add `coar-mobile` to `html`, `body`, or a local parent to opt into a mobile
presentation. Import the normal `@cocoar/vue-ui/styles` stylesheet; no extra
plugin, component props, or mobile-specific components are required.
```vue
Save
```
For an entire iOS/Android app or a deliberately mobile web interface:
```ts
document.body.classList.add('coar-mobile');
```
The class is an explicit **presentation preference**, not a claim that a mouse or
keyboard is unavailable. Existing click events, keyboard handling, `v-model`,
validation, disabled/readonly states, and link-button semantics stay unchanged.
Connecting a mouse does not switch the presentation. Narrowing the viewport does
not automatically enable this mode either.
## Supported controls
This is the first mobile-controls increment, not a mobile redesign of the entire
library.
| Component | Mobile presentation |
|-----------|---------------------|
| `CoarButton` | Size-dependent mobile heights (below), at least 44px width and 16px text; includes icon-only, loading, and link buttons |
| `CoarTextInput` | The same mobile height scale and at least 16px editable text, including multiline textareas |
| `CoarPasswordInput` | The same field floors, plus 44×44px clear/reveal targets |
| `CoarNumberInput` | The same field floors, plus 44×44px clear and stepper targets |
| `CoarCheckbox` | At least 48×48px clickable label, without enlarging the indicator |
| `CoarRadioButton` / `CoarRadioGroup` | At least 48×48px clickable option labels, without enlarging the indicators |
| `CoarSwitch` | At least 48×48px clickable label, without enlarging the track |
Text-input clear buttons also receive 44×44px targets. Clear buttons remain fully
opaque without hover or focus when a value can be cleared; empty fields retain
their hidden action slot to avoid layout jumps.
The existing `size` prop selects a different height scale in mobile mode instead
of collapsing every size to one minimum:
| Size | Desktop token height | Mobile height |
|------|----------------------|---------------|
| `xs` | 27px | 44px |
| `s` | 32px | 48px |
| `m` | 40px | 52px |
| `l` | 48px | 56px |
This scale applies to buttons and single-line text/password/number fields;
textareas can grow taller. Larger custom component heights are preserved.
The mobile input border is painted without taking layout space, so even an `xs`
field can contain 44px actions under a global `box-sizing: border-box` reset.
Rounded fields still have intentionally rounded hit regions.
A 16px editable font is intended to avoid the usual small-input focus zoom
on iOS, but actual keyboard and zoom behavior still requires device testing.
## Scope and themes
The mode inherits through ordinary DOM descendants, including `CoarThemeScope`.
It is independent of light/dark mode. Removing the class restores normal sizing
without remounting the controls or resetting their values. Desktop siblings
outside a local mobile parent are unaffected.
**Portaled content is not automatically part of a local mobile scope.** Overlays
teleported to `body` leave that parent's DOM subtree. Use `coar-mobile` on `body`
or `html` when supported controls inside overlays should also use the mode.
This increment does not add a mobile-context bridge for local overlays.
Date/time pickers, select panels, dialogs, OTP inputs, grids, and editors do not
have dedicated mobile presentations in this increment. In particular,
`CoarZonedDateTimePicker` does not yet switch to a sheet or a stepped mobile flow.
The class is the entry point for those future presentations, not a promise that
all components are already adapted.
## Customizing the floors
The mode sets inherited control tokens rather than changing the library's shared
desktop size tokens. Applications can override them locally:
```css
.my-mobile-form.coar-mobile {
--coar-control-xs-height: 48px;
--coar-control-s-height: 52px;
--coar-control-m-height: 56px;
--coar-control-l-height: 60px;
--coar-control-min-font-size: 18px;
--coar-control-min-target-size: 48px;
}
```
`--coar-control-min-size` separately controls the minimum clickable label size
for checkboxes, radios, and switches (48px by default).
Leave enough horizontal room for the field and its actions, especially for
password fields with both clear/reveal buttons and number fields with steppers.
The playground's `/mobile-controls` page demonstrates every size, local scope
switching, nested themes, textarea behavior, and non-editable states.
---
---
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
```
**After:**
```vue
```
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
```
**After** (add `clearable` where you want the ✕):
```vue
```
`@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`, ``'s `viewState` prop,
``'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
```
**After**
```ts
const config: PageConfig = {
contextFields: [
{ path: 'runtime.viewState', type: 'string', allowedValues: ['prompt', 'expired'] },
],
};
```
```vue
```
`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
```
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.3.0
**Timed events that span days show across them in the month.** A timed event
that ends on a later day than it starts — a stay from Thursday afternoon to
Sunday evening, a party past midnight — is a bar over its days, like an
all-day span, instead of a pill on its first day only. The bar stops a third
of a day short of its real ends, so it never reads as all-day.
### Changed
* **`@cocoar/vue-calendar` — a timed month bar keeps its distance from the
edge.** A timed event spanning days stops a third of a day cell short of the
outer edges of its first and last day, so it never reads as an all-day bar.
The inset is fixed — it marks "not all-day", it does not reflect the clock
time; an edge cut by a week row or by the edge of a continuous month's
section keeps running to the border, without a resize handle there.
### Fixed
* **`@cocoar/vue-calendar` — timed events spanning days become month bars.**
A timed event was pinned to its start day as a pill, so Thu 15:30 → Sun 18:00
showed only on Thursday. It now covers its days in the display zone like an
all-day span (split per week row); the end stays exclusive, so an end at
the start of a day (00:00, or 01:00 where DST skips midnight) does not
reach into that day. Same rule in `Cocoar.Calendar.iOS`. Dragging the end
handle of such a bar onto a day makes the bar end on that day, also when
the event ends at the start of a day; grabbing a bar just inside its second
day moves it by the day grabbed, not by one more.
## 3.2.0
**A list for records that do not fit into columns.** `CoarDataList` is the
grid alternative for data with many fields on a notebook screen: the
application owns a free multi-line template per record, the list owns
everything a hand-rolled list keeps reinventing — measured virtual scrolling,
search, a sort menu, selection, grouping, tiles, nesting and drag & drop.
Along the way the shared drag & drop composable gained a pointer engine, so
touch-first surfaces can reorder without giving up HTML5 drops on the desktop.
**The calendar catches up — with its consumers and with iOS.** Every finding
timetodo, amZettel and the Event-Tree stress app reported against
`@cocoar/vue-calendar` since May is addressed, and every behaviour
`Cocoar.Calendar.iOS` 5.3.1 added after the two calendars were last aligned
lands on the web with the same contracts. Along the way Day, Multi-day, Week
and Work week became one time-grid model, the header became optional
(`hideHeader`, `api.rangeLabel`), and the builder's `locale` stopped
defaulting to `en-US`.
**New and marked Preview: booking and scheduling on the time grid.** Days
can be rows on a horizontal time axis (`timeGridOrientation('horizontal')`),
and the time grids can select time ranges by drag, click or long press, show
a host draft and per-day background bands. Built for TimeBooking's booking
week and already running there; their API may still change before the
Preview mark goes.
### Added
* **`@cocoar/vue-calendar` — days as rows: a horizontal time grid (Preview).**
`builder.timeGridOrientation('horizontal')` (and
`api.setTimeGridOrientation`) turns Day, Multi-day, Week and Work week
by 90°: one row per day, time running left → right on one shared axis
— for time tracking, shifts and attendance, where start, end and gaps
of several days are compared at a glance. A presentation knob like
`dayMode`: window, paging, loaders and hooks are unchanged. Overlaps
stack as lanes and a row grows with them; all-day events are chips in
the day cell; drag & drop moves along the axis and onto other rows,
resizes at the left / right edge, honours `canDrop` / `dstPolicy`, and
the keyboard follows the screen (→ later, ↓ next day). No touch paging
in this orientation — a horizontal swipe scrolls the time axis.
`dayLabelWidth(px)` sets the day column (default 132); a day header
without all-day chips gets the row's height (two lines fit), and a
stretched axis never overflows its scroller.
Renderers get `ctx.orientation`; `api.scrollToTime` scrolls the time
axis (and now also works in Work week). Web only for now. Under the hood the
vertical grid's axis-free half moved into `useTimeGridPresentation` and
the drag runtime takes a time-axis adapter; the vertical grid is
unchanged.
* **`@cocoar/vue-calendar` — selecting time, drafts and background bands (Preview).**
For booking and scheduling screens on Week, Work week and Day, in both
orientations, all opt-in. `builder.timeRangeSelect(true)`: a mouse drag
on free space selects a range in the day pressed (Escape cancels), a
click selects what the **selection policy** proposes, both reported by
`onTimeRangeSelect({ date, start, end, source, native })` with
`ZonedDateTime`s in the display zone; under a mouse the proposal is
drawn while hovering; on touch a 500 ms long press starts the drag
while swipes keep scrolling and paging. `selectionPolicy(fn)` decides
in minutes of the day; `defaultSelectionPolicy()` (the slot) and
`gapOrDurationPolicy({ minutes, overlap })` (the gap between two
events, else a fixed length, drags stopping at events) ship with
`freeRangeAt`, `snapToSlot`, `busyMinutesOn` and `minuteOfDayToZoned`.
`hoverIndicator(true)` shows the time at the mouse on the axis and a
line across all days. `draft(ref)` draws a host range (an open form's)
as an outlined block above the events, `#draft` slot included, with
start, duration and end on the axis. `backgrounds((date) => bands)`
paints `tint` / `hatch` / `outline` ranges behind or above the events
and labelled lines, never taking pointer events. With
`timeRangeSelect` a mouse `onTimeClick` fires on release instead of on
press. Web only. Under the hood the vertical hit-test became
`createVerticalTimedAxis`, shared by drag & drop and selection.
* **`@cocoar/vue-calendar` — selected day in the month grid.**
`builder.selectedDate(MaybeRefOrGetter)` marks
one day with a filled circle around its day number — the iOS calendar's
selection decoration (`--coar-calendar-selection-fill`, systemGray5 in
both schemes; today keeps its accent number on top). It is deliberately
not the cursor: the cursor follows the visible month while scrolling, the
selection only moves when the host says so — pass the day a companion
pane follows, typically from `onDateClick`. The cell carries
`aria-selected`. Default `null` marks nothing.
* **`@cocoar/vue-calendar` — day agenda week strip slots.** `weekStripStart`
and `weekStripEnd` on `` (and forwarded by
``) place host controls at either end of the seven-day
strip — typically previous / next week. Both receive `WeekStripSlotScope`:
`cursor`, `weekStart`, `weekEnd`, `goTo(date)` and `shiftWeek(n)`.
* **`@cocoar/vue-ui` — mobile presentation (Preview).** A `coar-mobile` class
on `html`, `body` or any parent gives buttons, text / password / number
inputs, checkboxes, radios and switches touch sizes: heights 44 / 48 / 52 /
56 px for `xs` … `l`, 44 px action targets (clear, reveal, steppers), 48 px
clickable labels and at least 16 px editable text, against iOS focus zoom.
An explicit presentation choice, no device or viewport detection; component
APIs, events and `v-model` are unchanged, and without the class everything
keeps its desktop size. The floors are inherited tokens
(`--coar-control-*-height`, `--coar-control-min-target-size`, …) an app can
override. Overlays teleported to `body` follow only a class on `body` /
`html`; pickers, selects, dialogs and grids have no mobile presentation
yet. New "Mobile presentation" guide.
* **An Agent Skill, generated from the docs.** `@cocoar/vue-ui` ships
`skills/cocoar-vue-ui/`: a `SKILL.md` with the package table and the
mistakes an assistant makes without the docs, plus every documentation page
as a reference file with its demos inlined as `vue` code blocks.
`npx @cocoar/vue-ui skill` installs the skill of the installed version
through the skills CLI (options pass through); `npx skills add
cocoar-dev/cocoar-ui-vue` and `agentskills-cli add @cocoar/vue-ui` work
too. Generated by `pnpm skill:sync`, verified by CI (`pnpm skill:check`).
* **`CoarDataList` — virtualized record list with a free item template.** Every
row is a slot; the list measures its height, virtualizes rows, and provides
AND-term, diacritics-folding search with `::highlight` marks, an
`Intl.Collator` sort menu (`sortOptions`, natural numbers, nulls last,
stable), `groupBy` with headings, `gap`, `density`, `dividers`, `bordered`,
`elevated`, an empty state, and key-based selection (`'none' | 'single' |
'multiple'`) with click, `Ctrl`/`Shift` and full keyboard navigation.
State flows through `v-model:search`, `v-model:sort` and
`v-model:selected`; `item-click`, `item-dblclick`, `item-contextmenu` and
`item-activate` report interactions. Rows carry `role="option"` /
`listitem` semantics; the toolbar labels are translatable via the new
`coar.ui.dataList.*` keys.
* **Fluent `useDataList()` builder and `api`.** `{ builder, api }` follows
the `useTree()` / `CalendarBuilder` pattern: one chain configures data,
behaviour, appearance, handlers and declarative `itemMenu` / `viewportMenu`
context menus (rendered by the list); every setter takes a value, a `Ref` or
a getter. `api` offers selection, `scrollToKey`, `focusKey`,
`invalidateMeasurements`, expansion and the live `items` / `count` / `total`
refs. `useDataListModel()` exposes the headless pipeline
(filter → search → sort → group → nesting plus selection and expansion) for
custom renderers.
* **Grid layout.** `layout: 'grid'` with `tileMinWidth` flows the same records
into equal-width tiles per row — always in exact data order — with rows still
virtualized and measured. `tileCards` draws each tile as a card. Search,
sort, grouping, selection, context menus and the `api` behave identically;
arrows move by tile and by row. Masonry is deliberately not a layout of this
component.
* **Nested lists.** `children(accessor, level => …)` turns the list into a tree
of lists; each child level is configured on its own (`sortOptions`, `sort`,
`layout`, `tileMinWidth`), so parents can be sorted by title while children
keep a manual order. `v-model:expanded`, `maxDepth`, `nestingIndent`,
`nestingStyle` (`'lines' | 'none'`), `hideExpandToggle` and `canNest`
control it; search keeps matching parents and opens them while a query is
active, selection stays flat, `→` / `←` and `+` / `-` expand and collapse.
In the grid layout the children of an expanded tile open in a band under its
row — no tile moves sideways — framed like a folder hanging from its tab
(`bandElevated` adds a shadow); one expanded parent per row.
* **Drag & drop reordering.** Opt in with `reorderable`; the list shows an
insertion line (or the "inside" band for nesting) and reports `reorder`,
`items-add`, `items-remove` and `files-drop` events with `toIndex`,
`afterKey`, `beforeKey`, `group` and `parentKey` — it never mutates the
data. Lists sharing a `dragGroup` exchange items (a board is three lists),
`canDrag`, `canDrop` and `dragAccept` veto, `acceptsFiles` takes OS files
with either engine. Reordering is refused per level while that level is
sorted. Keyboard: `Ctrl`+`X`, arrows / `Home` / `End`, `Ctrl`+`V` or
`Enter`, `Escape`.
* **`unstyledItems` — the template owns the whole box.** The list then draws
no padding, hover, selection, focus, divider or card and keeps only
position, measurement, drop indicators and the row gap. State arrives via the
slot props `selected`, `focused`, `dragging`, `expanded`, `hasChildren`,
`depth`; actions via `select()`, `toggle()`, `toggleExpanded()`.
* **Pointer engine for `useDragDrop`.** New `engine: 'native' | 'pointer' |
'auto'` option: `'pointer'` drives drags from Pointer Events (mouse, pen,
touch with long-press, ghost element, text selection suppressed) between
surfaces registered via `pointer.target`; `'auto'` picks it on
coarse-pointer devices. Sources wire `onPointerDown()` next to the native
handlers and the engine decides which one acts. Matching rules,
`onDropAccept` / `onItemsRemove` and the registry are shared with the native
engine. `CoarListbox` and `CoarDualListbox` expose it as the opt-in
`dragEngine` prop; `CoarTree` stays native by design.
* **Measured rows in `useVirtualList`.** `measure` and `itemKey` options plus
`measureElement(index, el)` and `invalidateMeasurements(key?)` replace the
fixed-height estimate with observed heights (ResizeObserver, keyed by item),
and `scrollToIndex` settles on the target after the surrounding rows have
been measured.
* **Data List documentation.** A new "Data List" page under Display covers the
builder, the item template contract (what the list owns, what the template
owns), grid, nesting, reordering and engines, grouping, large lists, the
headless model, sorting, search, keyboard, the full API and the i18n keys;
the Drag & Drop page documents the engines.
* **Live topmost month while scrolling the Month view.** `api.topmostVisibleMonth`
is the month of the topmost visible section, updated on every scroll
frame (finger down, deceleration); `api.rangeLabel` and the header follow
it immediately. The cursor (`state.date`) — and with it `onRangeChange`
and the loaders — catches up only once the scroll settles (`scrollend`,
or a 160 ms fallback). A month stays active until its section has
scrolled out completely. Counterpart of iOS 3.6.
* **Compact card anatomy under overlap (Day / Week).** The built-in card now
shows the location (`meta.location`) and the time span when it has the
height, and lets the title wrap once on tall cards. When cards in front
leave less than `timedEventDetailMinWidth(px)` (default `112`, iOS
`timedEventDetailMinimumWidth`) unobscured, the card drops to one
end-truncated title line with no rows — every card stays its own click
and drag target. `0` disables the switch; custom `#event` slots and
`eventRenderer` are never touched. Counterpart of iOS 4.0.
* **`--coar-calendar-scroll-inset-bottom`** — bottom content inset for
every scrolling surface (Day / Week grids, Month, List, Agenda,
Timeline, Year), the counterpart of the iOS calendar's content inset.
Set it to the height of whatever overlays the bottom edge (tab bar,
floating button, `env(safe-area-inset-bottom)`) and the last rows scroll
clear of it; focus-driven scrolling honours it via `scroll-padding-bottom`.
Default `0px`.
* **`@cocoar/vue-calendar` — all-day band lane cap.**
`allDayMaxVisibleLanes(n | null)` (default `3`, like the system calendar)
folds lanes beyond the cap into per-day "+N" markers; a click expands the
band, a "Show fewer" control folds it back. `allDayBandMode('fitsContent' |
'alwaysOneLane' | 'reservesCap')` decides how much height the band claims —
`reservesCap` keeps the hour axis at the same place on every day. Pure
`capAllDayBand` / `allDayBandLanes` are exported from the core subpath.
* **Agenda empty state.** `` gains an `empty` slot
(`agendaEmpty` on the shell). It appears only when the list draws nothing
and no load is in flight, never next to empty-day headers, and has no
default rendering.
* **Contrast policy and per-event text colour.** `eventTextContrast('wcag' |
'apca')` selects how the automatic black/white ink on event surfaces is
chosen; APCA (the WCAG 3 draft method) picks white on saturated mid-tones
such as `#e03131` where WCAG 2 narrowly picks black. `meta.textColor`
overrides either policy for one event. `eventInkColor` joins
`eventTextColor` on the core subpath.
* **One model for every time grid.** Day, Multi-day, Week and Work week now
render on one surface and are presets of one range spec — `anchor`
(`cursor` | `weekStart`), `span` (days | `responsive`), `filter` (`all` |
`workDays`), `step` (days | `span`). `builder.timeGridRange(...)` lets the
Day view use any other combination ("start Monday, show five days, page by
a week"); Week and Work week stay fixed presets. `resolveTimeGridRange` and
the presets are exported from the core subpath. Every grid feature — touch
paging, empty-cell hooks, the all-day cap — therefore behaves identically
across the four views by construction.
* **Shell chrome can be switched off.** `` renders
only the body for hosts that own navigation and view selection through
the api; `hide-view-switcher` and `hide-mode-switcher` drop one control
while keeping the header. Until now hosts hid these with `:deep()` CSS
overrides, because an empty `#header` slot falls back to the built-in bar.
* **Swipe paging on week / work-week / day.** A horizontal pan on the columns
(touch) or a drag across the day-name strip (any pointer, grab cursor)
moves the grid with the pointer — header cells, all-day band and columns
together, the hour axis stays put — and pages on release past a quarter of
the width or on a fast flick. A touch that never moves is a tap and reaches
`onTimeClick` on release, so a swipe never starts with a stray slot click.
On the columns, mouse and pen keep their click-on-press semantics. While
you drag, the previous and next page are drawn beside the current one —
same columns, same events — and the builder pre-warms those two windows
in loader mode (`prefetchNeighbours(false)` opts out;
`api.getEventsForWindow(window)` is the read behind it).
`swipeNavigation(false)` switches it off; `prefers-reduced-motion` skips
the settle animation.
* **`@cocoar/vue-calendar/styles` subpath.** The package stylesheet
(`dist/vue-calendar.css`) is now declared in the `exports` map, matching
`@cocoar/vue-ui/styles`. Hosts drop the relative
`node_modules/@cocoar/vue-calendar/dist/vue-calendar.css` import.
* **`onDateDoubleClick` / `onTimeDoubleClick` builder hooks.** Empty month
cells, all-day cells and time-grid slots now report double-clicks
separately from single clicks, so the desktop convention "click selects,
double-click creates" needs no host-side click timer. `onTimeDoubleClick`
snaps to the slot grid exactly like `onTimeClick`; a double-click on an
event element still reaches `onEventDoubleClick` only.
* **Shipped translation catalogs.** `calendarMessages` (`en` / `de`, flat
`coar.calendar.*` keys) and `createCalendarTranslationSource()` for
`service.addTranslationSource(...)`. Regional tags resolve to their base
language; a host source registered afterwards overrides per key. A test
scans the source tree and fails when a component reads a key either
catalog lacks.
* **`api.rangeLabel`** — the title of the visible window ("15.–21. Juni
2026", "June 2026", "2026") as a readonly computed, formatted by the same
`formatRangeLabel` (core) the built-in header uses. For hosts that set
`hideHeader` and draw their own navigation. Correct before any view has
mounted, too.
### Changed
* **Month cells fold overflow into a `+N` row, like iOS.** A Details cell
shows its first `maxEventsPerCell` single-day pills (default now `2`, was
`3`) and one stable `+N` row for the rest; Stacked keeps 2 marks and
Compact 6 capsule segments and cap silently, as on iOS. Rows have a fixed
height per density plus their multi-day lanes — cells no longer scroll,
`maxEventsPerCell` is a real cap instead of a height hint, and Details
pills sit on a fixed 16 px line box so two pills and the marker fit the
94 px row in every host (iOS: 16 pt events on a 19 pt pitch). Pure
`capMonthCellPills` / `monthCellPillLimit` are exported from the core
subpath. Mirrors `ContinuousMonthGeometry` in `Cocoar.Calendar.iOS` 5.3.1.
* **Month rows cap their multi-day lanes.** `monthMaxVisibleLanes(n | null)`
(default `2`) bounds the lane band of a week row: a bar past the cap leaves
the band whole — never clipped mid-row — and counts into the `+N` of every
day it covers, where the day sheet lists it. `null` keeps the iOS port's
unbounded band, where a week grows with every lane. Pure `capMonthRowLanes`
is exported from the core subpath.
* **`+N` opens a day sheet over the cell.** The web goes one step past iOS:
the `+N` row is a button ("N more events", `aria-haspopup="dialog"`) that
opens a small dialog aligned to that one cell — every event of the day as a
live pill, multi-day ones first, scrolling when long, opening downward and flipping
upward when the scroll container runs out of room. Pills in the sheet carry
the grid's own drag / keyboard / double-click wiring, so an event can be
dragged straight out of the sheet onto another day. Closes on Escape, its
close control, an outside pointerdown, another `+N`, or a month change;
focus returns to the button. A tap on the cell body still fires
`onDateClick`; the button does not. In the grid itself hidden events leave
the DOM, so grid keyboard focus and drag reach the visible pills only; a
drag preview into a full cell takes the last visible slot.
* **Agenda and Month List show time spans.** Timed events with an end render
`start – end` (en dash) in the time column; point events keep the start
time; all-day events keep the all-day label. Mirrors the SwiftUI port's
default.
* **`--coar-color-accent` follows the vue-ui accent ramp.** Every usage now
falls back to `--coar-color-accent-500` before the historical blue, so a
host that brands `--coar-accent` gets matching today markers and default
event fills without a calendar-specific override. An explicit
`--coar-color-accent` still wins.
### Removed
* **The month cell's kebab menu and row expansion.** "Show more events" /
"Show fewer events", the hover-reveal trigger in the day-number row and
the right-click menu are gone with the `+N` row above; the
`coar.calendar.month.cellMenu` / `expandRow` / `collapseRow` message keys
are replaced by `coar.calendar.month.moreEvents`.
* **`onMoreClick`** and the `MoreClickHandler` type. The setter never
fired: it was specified for a "+N more" surface that did not exist. The
`+N` row now opens the built-in day sheet; a host that wants its own day
surface uses `onDateClick` plus `api.getEventsForWindow(window)`.
### Fixed
* **`@cocoar/vue-calendar` — `onTimeClick` in the vertical time grid
reports the slot under the pointer.** The slot was measured from the top
of the 15-minute render buffer above the first hour line, so the last
15 minutes of every slot reported the next one (with 15-minute slots,
every click). `onTimeDoubleClick` had the same offset. Clicks in the
buffer rows now report the first / last slot.
* **`@cocoar/vue-calendar` — the continuous month view no longer freezes on
mount.** With ~300 events and 39 series (amZettel, Pixel 8a) mounting the
month view blocked the main thread twice — about 0.6 s and 0.9 s at 4× CPU
throttling — because all 13 sections rendered at once, every section
converted every event into the display zone again, and all series expanded
in one go. Now only the month in view and the next one render on mount; the
other sections start as placeholders of about their height and fill one per
task, nearest first (at once when scrolled near, without moving the read
position). `layoutMonthGrid` caches each event's day bounds and skips
events outside the section with plain number comparisons; series expand one
after another, yielding every 8 ms; month labels reuse their formatters.
Same data, same throttling: the longest block drops from ~870 ms to
\~140 ms. Benchmark: `/calendar-month-perf` in the playground and
`apps/playground/scripts/month-perf.mjs`.
* **`@cocoar/vue-calendar` — on touch screens `onDateClick` waits for a tap.**
Month cells and the all-day band reported `onDateClick` on `pointerdown`,
and on a touch screen every scroll starts with a finger down on a cell — so
swiping the month grid opened the day under the finger (amZettel, Pixel 8a
and iOS WebViews). For touch and pen the hook now fires only for a tap (lift
within 10 px, no `pointercancel`), and in a task after the click that
follows the lift: acting on `pointerup` let that click land on the backdrop
of a sheet the handler had just opened and close it. Without a click (some
WebViews) it fires 350 ms after the lift. `onTimeClick` takes the same
route — its touch tap fired on release, and with `swipeNavigation(false)`
on press. Mouse keeps firing on press; `native` stays the `pointerdown`.
`onEventClick` does the same on touch: a tapped pill, bar or card no
longer reports on `pointerup` (its click closed the sheet the handler had
opened), and agenda / Month List rows and agenda day headers no longer
report on `pointerdown` at the start of every scroll.
Hosts can drop their own tap workarounds.
* **`@cocoar/vue-calendar` — "Today" scrolls today into view inside the
current month.** `api.goToToday()` only moved the cursor, and the
continuous month surface only reacts to a month *change* — so with today's
month already active (or the cursor already on today) the button did
nothing while today's row sat scrolled off-screen. `goToToday()` now also
requests a scroll to today; the month surface exposes `scrollToDate`,
which aligns the month to the top and nudges further when the day cell
would still fall below the fold. Agenda benefits the same way through its
existing `scrollToDate`.
* **`@cocoar/vue-calendar` — month Details geometry follows the host's
styling.** The Details row was a constant 94 px with a 24 px day-number
row and 18 px pills baked in; a host that restyles those (amZettel: 30 px
day-number row, pills with 2 px padding) got multi-day bars shorter than
pills, a gap under the bar band and a clipped `+N`. The view now measures
its rendered day-number row, pill, `+N` row and list spacing
(`useMonthMetrics`, re-measured on resize, font load and layout change);
the Details row is the iOS 94 px or the measured need, bars start below
the measured day-number row, and Details bars take the measured pill
height so bars and pills always match.
* **`@cocoar/vue-ui` — `CoarButton` keeps its label width in narrow flex
rows.** Its `min-width` fell back to `auto`, which a flex row resolves to 0
for a box with `overflow: hidden`: a constrained toolbar squeezed buttons
below their label and clipped the text. The fallback is now `min-content`;
buttons that should shrink need an explicit `min-width` from the host.
* **Date-time pickers no longer revert typed edits on blur.** Maskito's
datetime mask defaulted to `', '` between date and time while the pickers
format and parse with a plain space, so the first keystroke re-masked the
value, parsing failed and the edit was discarded. The mask's
`dateTimeSeparator` is now a space, and the masked 12-hour text uses
Maskito's canonical form (two-digit hour, non-breaking space before the
meridiem) so programmatic writes and the DOM agree. Round-trip tests cover
all four date patterns in 24-hour and 12-hour mode.
* **Locale fallback to the host's localization service now works.** The
builder's `locale` defaulted to `'en-US'`, so the documented fallback to
the `@cocoar/vue-localization` language never applied in any view. The
default is now `undefined`: an explicit `locale(...)` wins, then the
host language, then `en-US`. Hosts with the localization plugin that
never called `locale(...)` will see the calendar in their app language.
* **Cross-zone and UTC decorations no longer crash the agenda.** The
decoration component called the localization service's `t` detached from
its instance; the first event whose source zone differed from the display
zone threw `Cannot read properties of undefined (reading '_language')` and
left the agenda blank. The call is now bound to the service.
* **Clicking an event no longer also reports an empty-cell click.** A pill or
card's `pointerdown` bubbled through its month cell / time-grid column, so
`onDateClick` / `onTimeClick` fired alongside `onEventClick`. The
empty-surface hooks now ignore pointer events that started inside an event
element, matching their documented "empty cell / slot" contract.
* **Multi-day all-day events are announced with their inclusive last day.**
The month-grid `aria-label` named the RFC-5545 exclusive end (a Fri–Sun stay
read "Fri – Mon"); it now names the last covered day, and single-day
all-day events get one date instead of "Fri – Fri".
***
## 3.1.0
**Fixed Markdown structure with focused, typed places to fill it in.** This
release introduces a template-driven Markdown form for protocols, meeting notes
and document-like forms whose headings and explanatory text must remain intact.
It also separates the Markdown editor toolbar from an individual editor, so one
stable toolbar can serve every editable Markdown section on a page.
### Added
* **New `@cocoar/vue-markdown-form` package.** `CoarMarkdownForm` renders an
ordinary Markdown template as fixed document content and turns only explicit
`:field{...}` / `:::field{...}` directives into editable controls. The
reusable template and the filled values stay separate; applications receive
one typed values object without rewriting the Markdown source.
* **Built-in text, number, date, date-time, boolean, select and Markdown
fields.** Fields support required validation, placeholders, options and
type-appropriate constraints. Empty Markdown sections remain reachable, so a
user can delete all section content and still continue filling the document.
* **Fill and readonly document modes.** Fill mode keeps the authored structure
immutable while exposing its controls. Readonly mode renders the completed
document with configurable field decorations, making the same template useful
for entry, review and presentation.
* **Typed renderer context and an open field registry.** Hosts can provide
presentation context such as a basic or styled design, while consumer-defined
field types plug into the same parser, value model and rendering contract as
the built-ins.
* **Responsive field layout controls.** Templates can choose inline or stacked
placement and semantic widths including compact presets, full width and
`fill`, which consumes the remaining space beside a label.
* **One toolbar for multiple Markdown editors.** New
`CoarMarkdownEditorGroup`, `CoarMarkdownToolbar` and
`toolbar-mode="external"` route commands to the currently active editor. The
toolbar remains mounted, changes its available tools without flicker and is
disabled whenever no editor is active.
* **Complete template and integration documentation.** The docs include a
copyable protocol template, the directive grammar, built-in field reference,
typed values, validation, layouts, context, custom fields and the shared
toolbar setup.
### Fixed
* **External Markdown values remain synchronized during editor startup.** Model
updates that arrive before Milkdown is ready are buffered and applied once the
editor initializes, while later host updates continue to flow normally.
***
## 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`, ``'s `viewState`, ``'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` 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 `