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

package/skills/cocoar-vue-ui/references/components/date-views.md

@@ -0,0 +1,212 @@
+<!-- Generated from apps/docs/components/date-views.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Date Views (New in 2.0)
+
+The read-only display siblings of the picker family. When you have a `Temporal.PlainDate` / `Temporal.PlainDateTime` / `Temporal.ZonedDateTime` value and just want to show it (no editor, no panel) — use these.
+
+```ts
+import {
+  CoarPlainDateView,
+  CoarPlainDateTimeView,
+  CoarZonedDateTimeView,
+} from '@cocoar/vue-ui';
+```
+
+| | Value type | Renders |
+|--|--|--|
+| **`CoarPlainDateView`** | `Temporal.PlainDate \| null` | `12.05.2026` (locale-resolved format) |
+| **`CoarPlainDateTimeView`** | `Temporal.PlainDateTime \| null` | `12.05.2026 14:30` (locale + 12h/24h auto) |
+| **`CoarZonedDateTimeView`** | `Temporal.ZonedDateTime \| null` | `12.05.2026 14:30 GMT+2` (+ short zone label) |
+
+Each view mirrors its picker's `formatValue` logic exactly — same `useDatePickerBase` for locale + date-format resolution, same `coarFormatPlainDate` + `coarFormatTime` helpers. A read-only display and the editor's resting state look identical.
+
+## Basic Usage
+
+**Demo — `date-views/demos/BasicDateViews.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 16px;">
+    <div>
+      <div style="font-size: 12px; color: #64748b; margin-bottom: 4px;">CoarPlainDateView</div>
+      <CoarPlainDateView :value="date" />
+    </div>
+    <div>
+      <div style="font-size: 12px; color: #64748b; margin-bottom: 4px;">CoarPlainDateTimeView</div>
+      <CoarPlainDateTimeView :value="dateTime" />
+    </div>
+    <div>
+      <div style="font-size: 12px; color: #64748b; margin-bottom: 4px;">CoarZonedDateTimeView</div>
+      <CoarZonedDateTimeView :value="zoned" />
+    </div>
+    <div>
+      <div style="font-size: 12px; color: #64748b; margin-bottom: 4px;">Empty value with placeholder</div>
+      <CoarPlainDateView :value="null" placeholder="No date set" />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { Temporal } from '@js-temporal/polyfill';
+import {
+  CoarPlainDateView,
+  CoarPlainDateTimeView,
+  CoarZonedDateTimeView,
+} from '@cocoar/vue-ui';
+
+const date = Temporal.PlainDate.from('2026-05-12');
+const dateTime = Temporal.PlainDateTime.from('2026-05-12T14:30:00');
+const zoned = Temporal.ZonedDateTime.from('2026-05-12T14:30:00[Europe/Vienna]');
+</script>
+```
+
+Pass a `Temporal` value via `:value`. `null` renders the placeholder text (empty string by default). Use anywhere you'd show a date without an editor — cards, dialogs, list rows, table cells. The `@cocoar/vue-data-grid` date columns wrap these viewers internally.
+
+## Locale resolution
+
+The display format reacts to the consumer-app locale via `useL10n()` — switching language at runtime updates the view automatically. Pass `:locale="..."` to override per-instance.
+
+**Demo — `date-views/demos/DateViewsLocale.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 16px;">
+    <div style="display: flex; gap: 8px; align-items: center;">
+      <span style="font-size: 13px; color: #64748b;">Locale:</span>
+      <CoarSegmentedControl v-model="locale" :options="locales" size="s" />
+    </div>
+    <div style="display: grid; grid-template-columns: 200px 1fr; gap: 8px 16px; font-size: 14px;">
+      <span style="color: #64748b;">PlainDate</span>
+      <CoarPlainDateView :value="date" :locale="locale" />
+      <span style="color: #64748b;">PlainDateTime (24h auto)</span>
+      <CoarPlainDateTimeView :value="dateTime" :locale="locale" />
+      <span style="color: #64748b;">ZonedDateTime</span>
+      <CoarZonedDateTimeView :value="zoned" :locale="locale" />
+    </div>
+    <div style="font-size: 12px; color: #64748b;">
+      The format pattern (DD.MM.YYYY vs MM/DD/YYYY) and the 12h/24h clock are both derived from the locale via <code>useDatePickerBase</code> — same resolution chain the editor pickers use.
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Temporal } from '@js-temporal/polyfill';
+import {
+  CoarPlainDateView,
+  CoarPlainDateTimeView,
+  CoarZonedDateTimeView,
+  CoarSegmentedControl,
+} from '@cocoar/vue-ui';
+
+const locale = ref('de-AT');
+const locales = [
+  { value: 'de-AT', label: 'de-AT' },
+  { value: 'de-DE', label: 'de-DE' },
+  { value: 'en-US', label: 'en-US' },
+  { value: 'en-GB', label: 'en-GB' },
+  { value: 'fr-FR', label: 'fr-FR' },
+];
+
+const date = Temporal.PlainDate.from('2026-05-12');
+const dateTime = Temporal.PlainDateTime.from('2026-05-12T14:30:00');
+const zoned = Temporal.ZonedDateTime.from('2026-05-12T14:30:00[Europe/Vienna]');
+</script>
+```
+
+## Cross-zone projection
+
+By default, each `CoarZonedDateTimeView` renders its value **in that value's own zone** — a Tokyo event shows Tokyo wallclock, a Vienna event shows Vienna wallclock. Pass `displayTimeZone="..."` to project every value into a single zone (useful for cross-zone coordination views like "show every team's meeting in my zone").
+
+**Demo — `date-views/demos/DateViewsCrossZone.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 16px;">
+    <div>
+      <div style="font-size: 13px; color: #64748b; margin-bottom: 8px;">
+        Each row's value lives in its own zone — the view renders each in its own zone by default:
+      </div>
+      <div style="display: grid; grid-template-columns: 100px 1fr; gap: 6px 16px; font-size: 14px;">
+        <span style="color: #64748b;">EU sync</span>
+        <CoarZonedDateTimeView :value="eu" />
+        <span style="color: #64748b;">US sync</span>
+        <CoarZonedDateTimeView :value="us" />
+        <span style="color: #64748b;">AP sync</span>
+        <CoarZonedDateTimeView :value="ap" />
+      </div>
+    </div>
+    <div>
+      <div style="display: flex; gap: 8px; align-items: center; margin-bottom: 8px;">
+        <span style="font-size: 13px; color: #64748b;">…or project everything into one zone via <code>displayTimeZone</code>:</span>
+        <CoarSegmentedControl v-model="projectInto" :options="zones" size="s" />
+      </div>
+      <div style="display: grid; grid-template-columns: 100px 1fr; gap: 6px 16px; font-size: 14px;">
+        <span style="color: #64748b;">EU sync</span>
+        <CoarZonedDateTimeView :value="eu" :display-time-zone="projectInto" />
+        <span style="color: #64748b;">US sync</span>
+        <CoarZonedDateTimeView :value="us" :display-time-zone="projectInto" />
+        <span style="color: #64748b;">AP sync</span>
+        <CoarZonedDateTimeView :value="ap" :display-time-zone="projectInto" />
+      </div>
+    </div>
+    <div style="font-size: 12px; color: #64748b;">
+      All three values point at the same wallclock-in-its-own-zone (10:00 / 15:00 / 09:00), but the underlying instants differ. Projecting into one zone shows the comparable wallclock for that observer.
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Temporal } from '@js-temporal/polyfill';
+import { CoarZonedDateTimeView, CoarSegmentedControl } from '@cocoar/vue-ui';
+
+const eu = Temporal.ZonedDateTime.from('2026-05-13T10:00:00[Europe/Vienna]');
+const us = Temporal.ZonedDateTime.from('2026-05-13T15:00:00[America/New_York]');
+const ap = Temporal.ZonedDateTime.from('2026-05-14T09:00:00[Asia/Tokyo]');
+
+const projectInto = ref('Europe/Vienna');
+const zones = [
+  { value: 'Europe/Vienna',    label: 'Vienna' },
+  { value: 'America/New_York', label: 'New York' },
+  { value: 'Asia/Tokyo',       label: 'Tokyo' },
+];
+</script>
+```
+
+Use `:show-time-zone="false"` to hide the trailing zone label entirely (compact contexts where the zone is already clear from surrounding UI).
+
+## Cross-realm safety
+
+All three views check the value's type via `Symbol.toStringTag` (matched against `"Temporal.PlainDate"` etc.), not `instanceof Temporal.X`. Why this matters: under pnpm's isolated dependency tree, two packages can resolve different physical copies of `@js-temporal/polyfill` — a `Temporal.PlainDate` instance constructed against one copy fails `instanceof Temporal.PlainDate` checked against another copy. The `Symbol.toStringTag` is part of the Temporal spec and identical across copies (and would be identical against the native `Temporal` once browsers ship it), so the views render correctly no matter which package created the value.
+
+Non-matching values (e.g. an ISO string, a `Date`, or a `PlainDateTime` passed into a `CoarPlainDateView`) render as the placeholder. Convert at your data layer — the views are strict by design.
+
+## API
+
+### `CoarPlainDateView`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `Temporal.PlainDate \| null` | `null` | The value to display |
+| `locale` | `string` | _consumer locale_ | BCP-47 tag override |
+| `dateFormat` | `DateFormatConfig` | _resolved_ | Format pattern override |
+| `placeholder` | `string` | `''` | Shown when value is null / wrong type |
+| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Font-size token |
+
+### `CoarPlainDateTimeView`
+
+Same as `CoarPlainDateView` plus:
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `use24Hour` | `boolean \| 'auto'` | `'auto'` | 12h/24h clock; `'auto'` derives from locale |
+
+### `CoarZonedDateTimeView`
+
+Same as `CoarPlainDateTimeView` plus:
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `displayTimeZone` | `string` | _value's own zone_ | IANA zone to project every value into |
+| `showTimeZone` | `boolean` | `true` | Append the `GMT+1`-style zone label |

package/skills/cocoar-vue-ui/references/components/dialog.md

@@ -0,0 +1,148 @@
+<!-- Generated from apps/docs/components/dialog.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Dialog
+
+Modal dialogs demand attention. They block interaction with the rest of the page until the user makes a decision, making them the right choice for destructive actions, important confirmations, and messages that must be acknowledged before proceeding. Use them sparingly -- when the stakes are high enough to justify interrupting the user's flow.
+
+```ts
+import { useDialog } from '@cocoar/vue-ui';
+```
+
+## Confirm Dialog
+
+Use `dialog.confirm()` when you need an explicit yes-or-no decision before proceeding. The returned promise resolves with `true` (confirmed) or `false` / `undefined` (cancelled / dismissed).
+
+**Demo — `dialog/demos/ConfirmDialog.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center;">
+    <CoarButton variant="danger" icon-start="trash-2" @click="openConfirm">Delete Item</CoarButton>
+    <CoarButton variant="primary" @click="openConfirmPrimary">Publish Changes</CoarButton>
+    <CoarButton variant="secondary" @click="openLarge">Terms & Conditions</CoarButton>
+  </div>
+  <p style="margin-top: 8px; font-size: 13px; color: var(--coar-text-neutral-secondary);">
+    Last result: {{ lastResult || 'none' }}
+  </p>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarButton, useDialog } from '@cocoar/vue-ui';
+
+const dialog = useDialog();
+const lastResult = ref('');
+
+function openConfirm() {
+  dialog.confirm({
+    title: 'Delete item?',
+    message: 'This action cannot be undone. Are you sure you want to delete this item?',
+    confirmText: 'Delete',
+    cancelText: 'Cancel',
+    confirmVariant: 'danger',
+  }).result.then((confirmed) => {
+    lastResult.value = confirmed ? 'deleted' : 'cancelled';
+  });
+}
+
+function openConfirmPrimary() {
+  dialog.confirm({
+    title: 'Publish changes?',
+    message: 'This will make your changes visible to all users.',
+    confirmText: 'Publish',
+    cancelText: 'Not yet',
+    confirmVariant: 'primary',
+  }).result.then((confirmed) => {
+    lastResult.value = confirmed ? 'published' : 'kept draft';
+  });
+}
+
+function openLarge() {
+  dialog.confirm({
+    title: 'Terms & Conditions',
+    message: 'By continuing, you agree to our Terms of Service and Privacy Policy. Please review the full terms before accepting. This agreement governs your use of the platform and all associated services.',
+    confirmText: 'I Agree',
+    cancelText: 'Decline',
+    size: 'm',
+  }).result.then((confirmed) => {
+    lastResult.value = confirmed ? 'agreed' : 'declined';
+  });
+}
+</script>
+```
+
+## Alert Dialog
+
+Use `dialog.alert()` for one-way messages that require acknowledgement -- session expirations, permission errors, or completion notices. The user can only dismiss it; there is no secondary action.
+
+**Demo — `dialog/demos/AlertDialog.vue`**
+
+```vue
+<template>
+  <CoarButton variant="secondary" @click="openAlert">Show Alert</CoarButton>
+</template>
+
+<script setup lang="ts">
+import { CoarButton, useDialog } from '@cocoar/vue-ui';
+
+const dialog = useDialog();
+
+function openAlert() {
+  dialog.alert('Session expired', 'Your session has expired. Please sign in again to continue.');
+}
+</script>
+```
+
+## Setup
+
+Register the overlay plugin once in your app entry point:
+
+```ts
+// main.ts
+import { CoarOverlayPlugin } from '@cocoar/vue-ui';
+
+createApp(App)
+  .use(CoarOverlayPlugin)
+  .mount('#app');
+```
+
+> **Warning: Dialog vs Popconfirm**
+>
+> Use **Dialog** for modal confirmations that block the entire UI. Use **Popconfirm** for lightweight inline confirmations anchored near the trigger element. Dialogs are appropriate for higher-stakes, less frequent actions.
+
+## API
+
+### `useDialog()` Methods
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `dialog.confirm(options)` | `ConfirmOptions` | `DialogRef<boolean>` | Show a confirm/cancel dialog |
+| `dialog.alert(title, message)` | `string, string` | `DialogRef<void>` | Show an acknowledgement dialog |
+| `dialog.open(component, config?, props?)` | `Component, DialogConfig?, Record?` | `DialogRef<T>` | Open a custom component inside the dialog |
+
+### `ConfirmOptions`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `title` | `string` | — | Dialog title |
+| `message` | `string` | — | Confirmation message body |
+| `confirmText` | `string` | `'Confirm'` | Confirm button label |
+| `cancelText` | `string` | `'Cancel'` | Cancel button label |
+| `confirmVariant` | `'primary' \| 'danger'` | `'primary'` | Confirm button color variant |
+| `size` | `'s' \| 'm' \| 'l'` | `'s'` | Dialog width |
+
+### `DialogRef`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `result` | `Promise<T \| undefined>` | Resolves when the dialog closes |
+| `close(result?)` | `(val?: T) => void` | Programmatically close the dialog |
+
+## i18n Keys
+
+These keys can be translated via [`@cocoar/vue-localization`](../foundations/localization/translations.md).
+
+| Key | Default (English) | Used as |
+|-----|-------------------|---------|
+| `coar.ui.dialog.close` | `'Close dialog'` | Close button `aria-label` |
+| `coar.ui.dialog.dialog` | `'Dialog'` | Fallback dialog `aria-label` (when no title) |

package/skills/cocoar-vue-ui/references/components/divider.md

@@ -0,0 +1,157 @@
+<!-- Generated from apps/docs/components/divider.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Divider
+
+Dividers create clear visual breaks between sections of content. They're especially useful in forms, settings panels, and feeds where distinct groups of information sit close together. Add an optional text label to give the break semantic meaning.
+
+```ts
+import { CoarDivider } from '@cocoar/vue-ui';
+```
+
+## Basic Divider
+
+A clean horizontal line that separates content blocks. Drop it between any two sections to improve scannability.
+
+**Demo — `divider/demos/DividerBasic.vue`**
+
+```vue
+<template>
+  <div>
+    <p style="margin: 0 0 8px; font-size: 14px;">Content above the divider</p>
+    <CoarDivider />
+    <p style="margin: 8px 0 0; font-size: 14px;">Content below the divider</p>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarDivider } from '@cocoar/vue-ui';
+</script>
+```
+
+## With Content
+
+Embed text directly in the divider line via the default slot -- common in forms ("or continue with") and settings pages.
+
+**Demo — `divider/demos/DividerLabel.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px;">
+    <CoarDivider>Or continue with</CoarDivider>
+    <CoarDivider>Section Title</CoarDivider>
+    <CoarDivider>More options</CoarDivider>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarDivider } from '@cocoar/vue-ui';
+</script>
+```
+
+## Alignment
+
+Position the content to the `left`, `center`, or `right` of the line to match your layout's reading flow.
+
+**Demo — `divider/demos/DividerAlignment.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px;">
+    <CoarDivider align="left">Left</CoarDivider>
+    <CoarDivider align="center">Center (default)</CoarDivider>
+    <CoarDivider align="right">Right</CoarDivider>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarDivider } from '@cocoar/vue-ui';
+</script>
+```
+
+## Variants
+
+Two visual weights: `subtle` (the default) for light separation within a card, and `strong` for more prominent visual breaks.
+
+**Demo — `divider/demos/DividerVariants.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px;">
+    <CoarDivider>Subtle (default)</CoarDivider>
+    <CoarDivider variant="strong">Strong</CoarDivider>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarDivider } from '@cocoar/vue-ui';
+</script>
+```
+
+## Real-world Usage
+
+A classic login form pattern where a labeled divider separates OAuth sign-in buttons from the traditional email/password fields.
+
+**Demo — `divider/demos/DividerRealWorld.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px; max-width: 360px;">
+    <button class="oauth-btn">Continue with Google</button>
+    <button class="oauth-btn">Continue with GitHub</button>
+    <CoarDivider>or sign in with email</CoarDivider>
+    <div style="display: flex; flex-direction: column; gap: 4px;">
+      <label style="font-size: 14px;">Email</label>
+      <input type="email" placeholder="you@example.com" class="native-input" />
+    </div>
+    <div style="display: flex; flex-direction: column; gap: 4px;">
+      <label style="font-size: 14px;">Password</label>
+      <input type="password" placeholder="••••••••" class="native-input" />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarDivider } from '@cocoar/vue-ui';
+</script>
+
+<style scoped>
+.oauth-btn {
+  padding: 8px 16px;
+  border: 1px solid var(--coar-border-neutral-secondary);
+  border-radius: 6px;
+  background: var(--coar-background-neutral-primary);
+  color: var(--coar-text-neutral-primary);
+  font-size: 14px;
+  cursor: pointer;
+}
+.oauth-btn:hover {
+  background: var(--coar-background-neutral-tertiary);
+}
+.native-input {
+  padding: 6px 10px;
+  border: 1px solid var(--coar-border-neutral-secondary);
+  border-radius: 6px;
+  background: var(--coar-background-neutral-primary);
+  color: var(--coar-text-neutral-primary);
+  font-size: 14px;
+}
+</style>
+```
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `align` | `'left' \| 'center' \| 'right'` | `'center'` | Content alignment |
+| `variant` | `'subtle' \| 'strong'` | `'subtle'` | Line visual weight |
+| `width` | `number` | `90` | Divider width as a percentage (0–100) |
+| `spacingTop` | `number` | `0` | Top spacing in pixels |
+| `spacingBottom` | `number` | `0` | Bottom spacing in pixels |
+
+### Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Optional content displayed centered on the line |