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