@cocoar/vue-ui 3.1.0 → 3.2.0-beta.11

package/skills/cocoar-vue-ui/references/guide/error-handling.md

@@ -0,0 +1,162 @@
+<!-- Generated from apps/docs/guide/error-handling.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Error Handling
+
+Cocoar UI components are designed to fail gracefully. Internal errors are either caught and recovered silently, or surfaced to the user through controlled feedback mechanisms. This guide explains the patterns used throughout the library and how to handle errors in your own application code.
+
+## Library Philosophy: Fail Gracefully
+
+Components never throw unhandled exceptions into your application. Instead they follow one of two patterns:
+
+- **Silent fallback** — return a safe default (`null`, `'UTC'`, `false`) and continue
+- **User feedback** — surface the error visibly via a Toast or state change
+
+## Overlay Promises
+
+`CoarDialog` and `CoarPopconfirm` return Promises. Always handle the rejection case:
+
+```ts
+import { useDialog } from '@cocoar/vue-ui';
+
+const dialog = useDialog();
+
+// ✅ Always add .catch()
+dialog.confirm({
+  title: 'Delete item',
+  message: 'This cannot be undone.',
+})
+  .then((confirmed) => {
+    if (confirmed) deleteItem();
+  })
+  .catch(() => {
+    // Dialog was closed unexpectedly (e.g. overlay destroyed before user responded)
+  });
+```
+
+With async/await:
+
+```ts
+try {
+  const confirmed = await dialog.confirm({ title: 'Delete item', message: '...' });
+  if (confirmed) await deleteItem();
+} catch {
+  // Handle unexpected close
+}
+```
+
+> **Tip: Popconfirm**
+>
+> `CoarPopconfirm` emits `@confirmed` and `@cancelled` events — no Promise handling needed there. Use it for simple inline confirmations, and reserve `useDialog()` for programmatic flows where error handling is more important.
+
+## Toast for Error Feedback
+
+Use `useToast().error()` to surface errors to the user. Error toasts are persistent by default (duration `0`) — they stay until the user dismisses them, which is appropriate for errors that require attention.
+
+```ts
+import { useToast } from '@cocoar/vue-ui';
+
+const toast = useToast();
+
+async function saveData() {
+  try {
+    await api.save(payload);
+    toast.success('Saved successfully');
+  } catch (err) {
+    toast.error('Save failed', {
+      message: err instanceof Error ? err.message : 'Please try again.',
+    });
+  }
+}
+```
+
+```ts
+// With a retry action
+toast.error('Connection lost', {
+  message: 'Could not reach the server.',
+  action: {
+    label: 'Retry',
+    callback: () => saveData(),
+  },
+});
+```
+
+## Date and Time Parsing
+
+Date parsing functions return `null` on failure instead of throwing. Always null-check the result before using it:
+
+```ts
+import { coarParsePlainDate } from '@cocoar/vue-ui';
+
+const date = coarParsePlainDate(userInput);
+
+if (date === null) {
+  // Input was invalid — show validation error
+  toast.error('Invalid date format');
+  return;
+}
+
+// date is a Temporal.PlainDate — safe to use
+processDate(date);
+```
+
+The date picker components handle this internally — invalid input simply doesn't update the model value. Your `v-model` will remain `null` until the user enters a valid date.
+
+## Timezone Fallbacks
+
+Timezone utilities default to `'UTC'` when the browser API fails or the timezone identifier is unrecognised. This keeps date/time components functional even in restricted environments:
+
+```ts
+import { useTimezone } from '@cocoar/vue-localization';
+
+const { timezone } = useTimezone();
+// Always a valid IANA identifier — 'UTC' as last resort
+```
+
+## Async Operations in Overlays
+
+When loading data inside a Dialog or Popover, manage loading and error states yourself:
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { useDialog, useToast } from '@cocoar/vue-ui';
+
+const dialog = useDialog();
+const toast = useToast();
+
+async function openEditDialog(id: string) {
+  let data;
+  try {
+    data = await fetchItem(id);
+  } catch {
+    toast.error('Could not load item');
+    return; // Don't open the dialog if data failed to load
+  }
+
+  const saved = await dialog.confirm({
+    title: 'Edit item',
+    // ... pass data to dialog body component
+  }).catch(() => false);
+
+  if (saved) {
+    try {
+      await saveItem(data);
+      toast.success('Saved');
+    } catch {
+      toast.error('Save failed');
+    }
+  }
+}
+</script>
+```
+
+## Pattern Summary
+
+| Situation | Recommended pattern |
+|-----------|---------------------|
+| Dialog/Popconfirm result | `.then().catch()` or `try/await/catch` |
+| API call in component | `try/catch` + `toast.error()` |
+| Date input validation | Null-check return value of parse functions |
+| Non-recoverable error | `toast.error()` with persistent duration (default) |
+| Recoverable error | `toast.error()` with `action: { label: 'Retry', callback }` |
+| Silent failures OK | Rely on library defaults (`null`, `'UTC'`, `false`) |

package/skills/cocoar-vue-ui/references/guide/getting-started.md

@@ -0,0 +1,116 @@
+<!-- Generated from apps/docs/guide/getting-started.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Getting Started
+
+Set up the Cocoar Design System in your Vue 3 project in a few steps.
+
+## 1. Install
+
+```bash
+pnpm add @cocoar/vue-ui
+```
+
+## 2. Import Fonts & Styles
+
+Import fonts and styles in your app's entry point. Fonts are self-hosted via `@fontsource` — no external CDN needed.
+
+```ts
+// main.ts
+import '@cocoar/vue-ui/fonts';   // Poppins + Inter (self-hosted)
+import '@cocoar/vue-ui/styles';  // Design tokens + component styles
+```
+
+> **Info: Bring your own fonts?**
+>
+> The font import is optional. If you prefer a CDN or custom fonts, skip `@cocoar/vue-ui/fonts` and load them yourself. Components fall back to system fonts gracefully.
+
+## 3. Use Components
+
+Import components directly — no global registration required. Tree-shaking is automatic.
+
+```vue
+<script setup>
+import { CoarButton } from '@cocoar/vue-ui';
+</script>
+
+<template>
+  <CoarButton>Hello Coar</CoarButton>
+</template>
+```
+
+## 4. Dark Mode
+
+Toggle dark mode by adding the `.dark-mode` class to the root element. All design tokens and components adapt automatically.
+
+```ts
+document.documentElement.classList.toggle('dark-mode', isDark);
+```
+
+## 5. Overlay System
+
+For components that render overlays (Dialog, Toast, Popover, Tooltip), register the plugin once:
+
+```ts
+// main.ts
+import { createApp } from 'vue';
+import { CoarOverlayPlugin } from '@cocoar/vue-ui';
+
+createApp(App)
+  .use(CoarOverlayPlugin)
+  .mount('#app');
+```
+
+And add the overlay host to your root layout:
+
+```vue
+<template>
+  <router-view />
+  <CoarOverlayHost />
+</template>
+```
+
+## Date/Time Components
+
+The date and time pickers use the [Temporal API](https://tc39.es/proposal-temporal/docs/) via `@js-temporal/polyfill`, which is included as a dependency of `@cocoar/vue-ui`. No extra install needed. When native Temporal support reaches all browsers, the polyfill can be dropped in a future major release.
+
+## Additional Packages
+
+Optional packages for extended functionality:
+
+```bash
+pnpm add @cocoar/vue-localization   # i18n & timezone
+pnpm add @cocoar/vue-data-grid      # AG Grid wrapper
+pnpm add @cocoar/vue-markdown       # Markdown viewer
+```
+
+## 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](https://docs.cocoar.dev/cocoar-ui-vue/llms.txt) (an index with one line
+per page) and [llms-full.txt](https://docs.cocoar.dev/cocoar-ui-vue/llms-full.txt) (everything in one file) for assistants that fetch
+documentation by URL.

package/skills/cocoar-vue-ui/references/guide/migration-page-builder-3.md

@@ -0,0 +1,207 @@
+<!-- Generated from apps/docs/guide/migration-page-builder-3.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# 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.md) page.
+
+**Your documents migrate themselves.** One document field changed
+(`repeat.props.source`), and it is renamed on ingest like every earlier schema
+migration. Nothing to do by hand.
+
+## TL;DR
+
+| If your `PageConfig` sets… | …then |
+| --- | --- |
+| `fields` | Rename to **`dataContract`**. |
+| `elements` | Rename to **`elementTypes`**. |
+| `availableStates` | Remove. Pass the state through `runtimeContext` and declare the field's `allowedValues` — see [§3](#_3-view-state-becomes-ordinary-context). |
+| `previewFixtures` | Remove. Bind your own sample to `previewContext` — see [§4](#_4-preview-fixtures-become-host-chrome). |
+| `stylePresets` | Remove. Styling is `NodeStyle`, `CoarTheme` and `visual-markup` — see [§1](#_1-style-presets-are-gone). |
+| `requiredNodes` | Remove. Enforce it in your publication endpoint — see [§2](#_2-required-nodes-are-gone). |
+| None of these | Check the [rename table](#_6-renamed-api) — you may still import a renamed symbol. |
+
+---
+
+## 1. Style presets are gone
+
+Removed: `config.stylePresets`, `node.stylePreset`, the `PageStylePreset` type,
+`findStylePreset()` and `isSafeStylePreset()`.
+
+They let a host register named CSS classes for the author to pick by id. The
+justification was that a page author must not put CSS into a page they do not
+own — but a page author *does* own the realm their page renders in, so the
+restriction protected nobody. The feature was also never finished: the Editor
+canvas never applied the class, so picking a preset changed nothing until you
+switched to the Preview tab.
+
+**What to use instead.** Styling has three channels and always did:
+
+| Want | Use |
+| --- | --- |
+| Per-node appearance | `NodeStyle` — surface, typography, layout, box |
+| Brand colours, radii, fonts | `CoarTheme` via `CoarThemeScope` / `previewTheme` |
+| Free-form decoration | The `visual-markup` element (sealed iframe, free CSS) |
+
+A leftover `stylePreset` key in a stored document is **reported as an authoring
+warning, never stripped**. The renderer ignores it and emits no class from it.
+
+## 2. Required nodes are gone
+
+Removed: `config.requiredNodes` (with `lockVisibility`, `lockStyle`, `parentId`
+and `maxIndex`).
+
+It pinned a node as present, placed and visually untouchable. Besides the
+ownership argument above, it did not work: a node carrying both locks still
+disappeared when the container **above** it was hidden, and
+`validatePageDocument()` reported the document as valid.
+
+**What to use instead.** Enforce it where activation happens. Your publish
+endpoint already validates the document before a revision goes live; a check
+there cannot be bypassed from the browser, which was never true of the config
+flag.
+
+```ts
+// in the publish endpoint, on the document about to become active
+if (!containsVisibleNode(document, 'legal-notice')) {
+  return reject('The legal notice must stay on the page.');
+}
+```
+
+The builder no longer withholds delete, move or the drag grip from any node.
+
+## 3. View state becomes ordinary context
+
+Removed: `config.availableStates`, `<CoarPageRenderer>`'s `viewState` prop,
+`<CoarPageBuilder>`'s `previewState` prop, `visibleWhen.source: 'state'`, and
+`page.viewState` in the code scope.
+
+The host's "which screen is this right now" was a second mechanism for something
+`runtimeContext` already carried. Note that **Page State is untouched**:
+`definePageState`, `page.state` and `source: 'state'` *bindings* all keep working
+— they mean the page author's own shared data, and losing the name collision is
+part of the point.
+
+**Before**
+
+```ts
+const config: PageConfig = {
+  availableStates: [{ id: 'prompt', label: 'Prompt' }, { id: 'expired', label: 'Expired' }],
+};
+```
+```vue
+<CoarPageRenderer :schema :config :view-state="viewState" />
+```
+
+**After**
+
+```ts
+const config: PageConfig = {
+  contextFields: [
+    { path: 'runtime.viewState', type: 'string', allowedValues: ['prompt', 'expired'] },
+  ],
+};
+```
+```vue
+<CoarPageRenderer :schema :config :runtime-context="{ runtime: { viewState } }" />
+```
+
+`allowedValues` is new: a context field that declares it gets a **dropdown** in
+the condition editor instead of a free-text box — which is what
+`availableStates` used to provide, now available to every enumerable field.
+
+Documents using `visibleWhen: { source: 'state', … }` must move to
+`{ source: 'context', path: 'runtime.viewState', operator: 'equals', value: … }`,
+or express the condition in Element Code.
+
+## 4. Preview fixtures become host chrome
+
+Removed: `config.previewFixtures` and the `PagePreviewFixture` type.
+
+A fixture was a named bundle of `{ context, state, locale, viewport }` plus a
+dropdown in the builder toolbar — but the host already owns `previewContext` and
+`previewLocale`. The only thing the config added was the builder drawing the
+picker, and the host is the one who knows what "empty" or "50 items" means for
+its own data.
+
+```vue
+<!-- your own picker, bound to the props you already pass -->
+<select v-model="sample">…</select>
+<CoarPageBuilder v-model="schema" :config :preview-context="samples[sample]" :preview-locale="locale" />
+```
+
+The preview now runs when the host supplies the inputs its own `config`
+declares (`contextFields`, `locales`), and otherwise says so rather than
+rendering against invented data.
+
+## 5. Auth presets are gone
+
+Removed: `createAuthPageConfig()` and `createAuthPageDocument()`.
+
+The package ships nothing auth-specific. An IDP owns its own `PageConfig` and
+starting documents; `apps/playground/src/views/auth-customization/` in this
+repository is a worked example of all four slots.
+
+## 6. Renamed API
+
+Mechanical, and a search-and-replace covers all of them.
+
+| Before | After |
+| --- | --- |
+| `config.fields` | `config.dataContract` |
+| `config.elements` | `config.elementTypes` |
+| `PAGE_ELEMENTS_KEY` | `PAGE_ELEMENT_TYPES_KEY` |
+| `useSchemaValidation()` | `useAuthoringFindings()` — returns `{ findings, byNodeId }`, not `{ issues, … }` |
+| `ValidationIssue` | `AuthoringFinding` |
+| `IssueSeverity` | `FindingSeverity` |
+| `@validation` event | `@findings` |
+| `PageVisualFont.source` | `PageVisualFont.src` |
+| `repeat.props.source` | `repeat.props.contextPath` *(auto-migrated)* |
+
+Each pair existed because one word covered two things: `fields` was both the DTO
+contract and the live values, `elements` was both the type registry and this
+page's nodes, `validation` covered field rules, the activation contract **and**
+the builder's authoring hints, and `source` was an enum, a context path and a
+data URL at once. `binding.source` keeps the name — it is the dominant meaning.
+
+## 7. Documents move to `schemaVersion: 6`
+
+The only document change is the repeat rename, applied by
+`migrateRepeatContextPath` on the same ingest path as every earlier migration —
+identity-preserving, idempotent, and skipped when the new key is already there.
+It runs on `v-model` assignment, on the initial value and on the JSON tab's
+Apply, so a stored v5 document opens and renders unchanged.
+
+Persist the version as-is; a document saved by 3.0 comes back stamped `6`.
+
+## Also worth knowing
+
+Not breaking, but new in the same release:
+
+- **`@findings`** mirrors the builder's authoring findings to the host, so a
+  save button can grey out on errors. `useAuthoringFindings()` is exported for
+  the same check outside a mounted builder.
+- **`previewInitialValues`** starts the embedded preview from host values,
+  merged over the authored `defaultValue`s — the edit-form case, and the case
+  where a default is computed per tenant.
+- **The page is exactly its host container.** Size values on the page root are
+  dropped and the root offers no size fields; the container owns the box. Its
+  contract is that the container must have a determinable height — for `body`,
+  `html, body { height: 100% }`. A document that set a root size is told so.
+- **Quick Properties resolve per breakpoint.** They showed the base value while
+  the canvas rendered the resolved one; an inherited value now also names the
+  override it came from.

package/skills/cocoar-vue-ui/references/guide/migration.md

@@ -0,0 +1,140 @@
+<!-- Generated from apps/docs/guide/migration.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# 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.md) (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.md) 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.md) — exactly like every other
+input — to get the label, the required `*`, validation messages and the inline
+status icon.
+
+**Before:**
+
+```vue
+<CoarPlainDatePicker
+  v-model="date"
+  label="Start date"
+  hint="When the project kicks off"
+  :error="errorMessage"
+  required
+/>
+```
+
+**After:**
+
+```vue
+<CoarFormField
+  label="Start date"
+  hint="When the project kicks off"
+  :error="errorMessage"
+  required
+>
+  <CoarPlainDatePicker v-model="date" :error="!!errorMessage" />
+</CoarFormField>
+```
+
+Notes:
+
+- `error` on the **picker** is now a boolean — pass `!!errorMessage` (or any
+  boolean). The human-readable message lives on `CoarFormField`.
+- New `id` prop on each picker (explicit input id; otherwise taken from the
+  wrapping `CoarFormField`, otherwise auto-generated) for parity with the other
+  inputs.
+
+## 2. `clearable` is now opt-in (defaults to `false`)
+
+`CoarTextInput`, `CoarPasswordInput`, `CoarNumberInput` and the three date/time
+pickers previously defaulted `clearable` to `true`. They now default to `false`,
+in line with the library rule that **every boolean prop defaults `false`** (and
+matching `CoarSelect` / `CoarMultiSelect`, which were already `false`).
+
+Nothing errors — the inline clear ✕ simply no longer appears unless you ask for it.
+
+**Before** (✕ shown automatically):
+
+```vue
+<CoarTextInput v-model="name" />
+```
+
+**After** (add `clearable` where you want the ✕):
+
+```vue
+<CoarTextInput v-model="name" clearable />
+```
+
+`@cocoar/vue-data-grid` is unaffected — its cell editors already pass `clearable`
+explicitly.
+
+## 3. Renamed / removed CSS tokens
+
+These only affect you if you **override Cocoar design tokens** in your own
+stylesheet. If you consume the components as-is, skip this section.
+
+### Renamed
+
+| Old | New |
+| --- | --- |
+| `--coar-input-padding-x` | `--coar-field-padding-x` |
+
+`--coar-field-padding-x` (`12px`) is the single source of truth for form-field
+horizontal padding. It is intentionally **off** the spacing scale and decoupled
+from it, so tuning `--coar-spacing-*` no longer moves field padding. Each control
+size scales it by `--coar-component-{xs,s,m,l}-scale`.
+
+### Removed
+
+| Removed | Use instead |
+| --- | --- |
+| `--coar-spacing-2xs` (was a duplicate of `xxs`, both `2px`) | `--coar-spacing-xxs` |
+| `--coar-spacing-xxl` (`48px`, unused in the library) | a remaining step, e.g. `--coar-spacing-xl` (`32px`) |
+| `--coar-spacing-xxxl` (`64px`, unused in the library) | a remaining step |
+
+The spacing scale is now: `3xs 1 · xxs 2 · xs 4 · s 8 · m 16 · l 24 · xl 32`.
+
+---
+
+## What did **not** change
+
+- **Public props & slots** of `CoarTextInput`, `CoarPasswordInput`,
+  `CoarNumberInput`, `CoarSelect`, `CoarMultiSelect`, `CoarTagSelect` — including
+  the `prefix` / `suffix` / `leading` / `trailing` slots. The move onto the
+  internal `CoarInputFrame` shell is invisible to consumers.
+- **Visual output** — padding, radius and sizing values were preserved. Fields
+  may differ by a sub-pixel at most; nothing reflows.
+- **Toggle, listbox and segmented controls** — `CoarCheckbox`, `CoarSwitch`,
+  `CoarRadioGroup`, `CoarListbox`, `CoarDualListbox`, `CoarSegmentedControl` got
+  token-consistency polish only, no API change. (`CoarSwitch` and
+  `CoarRadioGroup` additionally **gain** an `xs` size — additive.)