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

package/skills/cocoar-vue-ui/references/components/virtual-list.md

@@ -0,0 +1,212 @@
+<!-- Generated from apps/docs/components/virtual-list.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Virtual List
+
+`useVirtualList` is a framework-agnostic composable that returns the slice of rows currently inside the viewport (plus an overscan buffer). Use it to render very large lists without putting thousands of DOM nodes in the tree. It's the primitive behind [`CoarListbox`'s virtual mode](./listbox.md#virtual-scrolling), but is independently exported and usable in any Vue component that scrolls.
+
+```ts
+import { useVirtualList } from '@cocoar/vue-ui';
+```
+
+## Standalone example
+
+The demo below is a plain `<div>` scroller — **no listbox involved**. 50,000 synthetic log lines are described by data, but only ~20 rows are ever in the DOM:
+
+**Demo — `virtual-list/demos/StandaloneVirtualLog.vue`**
+
+```vue
+<template>
+  <div>
+    <div class="toolbar">
+      <button type="button" @click="scrollToMiddle">Scroll to 25,000</button>
+      <button type="button" @click="scrollToEnd">Scroll to end</button>
+      <span class="muted">Rendered: {{ virtualRows.length }} / {{ logs.length.toLocaleString() }} rows</span>
+    </div>
+    <div ref="scrollRef" class="log">
+      <!-- Spacer provides the full virtual height so the browser's native scrollbar is accurate. -->
+      <div class="spacer" :style="{ height: totalSize + 'px' }">
+        <div
+          v-for="row in virtualRows"
+          :key="row.index"
+          class="line"
+          :class="`line--${logs[row.index].level}`"
+          :style="{ transform: `translateY(${row.start}px)`, height: row.size + 'px' }"
+        >
+          <span class="idx">{{ String(row.index + 1).padStart(5, '0') }}</span>
+          <span class="lvl">{{ logs[row.index].level.toUpperCase() }}</span>
+          <span class="msg">{{ logs[row.index].message }}</span>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { useTemplateRef } from 'vue';
+import { useVirtualList } from '@cocoar/vue-ui';
+
+interface LogLine { level: 'info' | 'warn' | 'error'; message: string }
+
+const LEVELS: LogLine['level'][] = ['info', 'info', 'info', 'info', 'warn', 'error'];
+const MSG_POOL = [
+  'Served GET /api/principals in 14ms',
+  'Cache miss on token-introspect; re-fetching',
+  'Scheduled cleanup tick — no candidates',
+  'POST /teams/42/members (batch 12)',
+  'Upstream 502 — retry 2/3 queued',
+  'Rate limit 4/sec threshold reached',
+  'Invalidated cache segment users:42',
+  'WS heartbeat latency 83ms',
+  'Released connection back to pool (id=17)',
+  'User alice.mueller logged in from 10.0.3.22',
+];
+
+const logs: LogLine[] = Array.from({ length: 50_000 }, (_, i) => ({
+  level: LEVELS[i % LEVELS.length],
+  message: `${MSG_POOL[i % MSG_POOL.length]} — seq ${i}`,
+}));
+
+const scrollRef = useTemplateRef<HTMLElement>('scrollRef');
+
+const { virtualRows, totalSize, scrollToIndex } = useVirtualList({
+  count: logs.length,
+  itemSize: 22,
+  overscan: 8,
+  scrollElement: scrollRef,
+});
+
+function scrollToMiddle() { scrollToIndex(25000, 'start'); }
+function scrollToEnd() { scrollToIndex(logs.length - 1, 'end'); }
+</script>
+
+<style scoped>
+.toolbar {
+  display: flex; align-items: center; gap: 10px;
+  margin-bottom: 8px; font-size: 12px;
+}
+.toolbar button {
+  border: 1px solid #d1d5db; background: white;
+  padding: 4px 10px; border-radius: 3px; cursor: pointer;
+  font-size: 12px;
+}
+.toolbar button:hover { background: #f3f4f6; }
+.muted { color: #64748b; margin-left: auto; }
+.log {
+  height: 300px;
+  overflow-y: auto;
+  border: 1px solid #d1d5db;
+  border-radius: 4px;
+  background: #0f172a;
+  color: #cbd5e1;
+  font-family: 'Cascadia Code', Consolas, Monaco, monospace;
+  font-size: 12px;
+  line-height: 22px;
+}
+.spacer { position: relative; }
+.line {
+  position: absolute;
+  left: 0; right: 0;
+  display: flex; gap: 10px; padding: 0 10px;
+  white-space: nowrap;
+  overflow: hidden;
+}
+.idx { color: #475569; flex-shrink: 0; }
+.lvl { flex-shrink: 0; font-weight: 600; width: 48px; }
+.line--info .lvl { color: #60a5fa; }
+.line--warn .lvl { color: #fbbf24; }
+.line--error .lvl { color: #f87171; }
+.msg { overflow: hidden; text-overflow: ellipsis; }
+</style>
+```
+
+## When to reach for it
+
+- Pre-loaded catalogs of a few thousand+ items that would otherwise jank the browser
+- Chat history, timelines, command logs
+- Large custom tables you build yourself (not for `CoarDataGrid`, which handles this internally)
+- Any component with a scroll container where DOM-node count is the bottleneck
+
+If your data is backend-paginated and can be filtered server-side, virtual scrolling is rarely necessary — the DOM stays small on its own.
+
+## Usage
+
+```ts
+import { useTemplateRef } from 'vue';
+import { useVirtualList } from '@cocoar/vue-ui';
+
+const scrollRef = useTemplateRef<HTMLElement>('scrollRef');
+
+const { virtualRows, totalSize, scrollToIndex } = useVirtualList({
+  count: () => items.value.length,
+  itemSize: 32,
+  overscan: 5,
+  scrollElement: scrollRef,
+});
+```
+
+Template skeleton — a spacer establishes the full scroll height and each visible row is absolutely positioned at its offset:
+
+```vue
+<div ref="scrollRef" style="overflow: auto; height: 400px;">
+  <div :style="{ height: totalSize + 'px', position: 'relative' }">
+    <div
+      v-for="row in virtualRows"
+      :key="row.index"
+      :style="{
+        position: 'absolute', left: 0, right: 0,
+        transform: `translateY(${row.start}px)`,
+        height: row.size + 'px',
+      }"
+    >
+      {{ items[row.index] }}
+    </div>
+  </div>
+</div>
+```
+
+## Variable item heights
+
+`itemSize` accepts either a fixed number or a per-index callback. Groups, headings, or mixed content get different heights while the cumulative-offset math stays O(log n) per scroll event:
+
+```ts
+useVirtualList({
+  count: () => entries.value.length,
+  itemSize: (index) => entries.value[index].isHeading ? 28 : 44,
+  scrollElement: scrollRef,
+});
+```
+
+## API
+
+### `UseVirtualListOptions`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `count` | `MaybeRefOrGetter<number>` | — | Total item count. Reactive — changes trigger a recomputation of the offset table. |
+| `itemSize` | `MaybeRefOrGetter<number \| (index) => number>` | — | Fixed pixel height, or a per-index function for variable heights. |
+| `overscan` | `MaybeRefOrGetter<number>` | `5` | Extra rows rendered above/below the viewport as a scroll buffer. |
+| `scrollElement` | `Ref<HTMLElement \| null>` | — | The scrolling container. Attach via `useTemplateRef`. |
+
+### Return value
+
+| Field | Type | Description |
+|---|---|---|
+| `virtualRows` | `ComputedRef<VirtualRow[]>` | The rows currently in the viewport + overscan window. |
+| `totalSize` | `ComputedRef<number>` | Sum of all item heights — bind this to your spacer's `height`. |
+| `scrollToIndex` | `(index, align?) => void` | Programmatically scroll an index into view. `align`: `'auto'` (default), `'start'`, `'center'`, `'end'`. |
+| `offsetFor` | `(index) => number` | Debug/test helper — returns the cumulative pixel offset for an index. |
+
+### `VirtualRow`
+
+| Field | Type | Description |
+|---|---|---|
+| `index` | `number` | Position in the underlying list (0-based). |
+| `start` | `number` | Pixel offset from the top of the spacer. Use `translateY(start)`. |
+| `size` | `number` | Row height in pixels. |
+
+## Behavior notes
+
+- **Fixed viewport:** the composable tracks the container's `clientHeight` on every scroll event and — when available — via a `ResizeObserver`. In environments without `ResizeObserver`, it falls back to the `window.resize` event.
+- **SSR-safe:** the `ResizeObserver` and DOM access are all guarded; the composable returns empty rows until the scroll element is mounted.
+- **Binary-search offset table:** `count` and `itemSize` are reactive. Changing them rebuilds the cumulative offset array (`O(n)` once); scroll events then binary-search (`O(log n)`) for the visible window.
+- **Dynamic measurement** (rendering items and measuring their actual heights) is *not* supported — pick an `itemSize` or function that matches your row heights. For the common "some rows are 32px, some are 48px" case, per-index function is enough.

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

@@ -0,0 +1,251 @@
+<!-- Generated from apps/docs/components/wizard.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Wizard (Preview)
+
+A multi-step flow shell — built to live **inside a modal** (it renders no modal of its own). Three things make it a wizard rather than a plain stepper:
+
+- **Animated body resize.** Only the active step is mounted, and the body smoothly animates its height between steps — so the surrounding modal grows / shrinks to fit each page.
+- **A scrollable indicator that follows you.** The step indicator can be far wider (or taller) than the modal; it scrolls and auto-centers the active step on every move.
+- **Edge-placeable indicator.** `indicatorPosition` puts the progress strip on any of the four edges.
+
+```ts
+import { CoarWizard, type CoarWizardStep } from '@cocoar/vue-ui';
+```
+
+> **Warning: Preview**
+>
+> `CoarWizard` is new and on the `0.0.x` line. The API (props, slots, events) may still change before it stabilises — pin a version if you depend on it.
+
+## Basic Usage
+
+Pass an ordered `steps` array — each step's `id` is the name of its content slot, and only the active step is rendered. Bind the active step with `v-model:step`. Try the **Top / Right / Bottom / Left** toggle, and watch the modal resize as you move between the short and tall steps. Step 1 gates **Next** via `canAdvance` until a name is entered.
+
+**Demo — `wizard/demos/WizardBasic.vue`**
+
+```vue
+<template>
+  <div class="wiz-demo">
+    <div class="wiz-demo__controls">
+      <span class="wiz-demo__label">Indicator:</span>
+      <CoarSegmentedControl v-model="pos" :options="positions" size="xs" />
+    </div>
+
+    <!-- A bounded frame standing in for a routed modal. The wizard resizes it
+         per step (animated); the indicator scrolls inside its own width. -->
+    <div class="wiz-modal">
+      <div class="wiz-modal__header">Create OAuth API</div>
+      <div class="wiz-modal__body">
+        <CoarWizard
+          :steps="steps"
+          v-model:step="step"
+          :indicator-position="pos"
+          finish-label="Create"
+          @finish="created = true"
+        >
+          <template #basics>
+            <div class="wiz-page">
+              <p class="wiz-page__hint">Name your API client. Next is blocked until a name is entered.</p>
+              <CoarTextInput v-model="form.name" placeholder="My API client" />
+              <CoarTextInput v-model="form.desc" placeholder="Description (optional)" />
+            </div>
+          </template>
+
+          <template #type>
+            <div class="wiz-page">
+              <p class="wiz-page__hint">What kind of client is this?</p>
+              <label v-for="t in types" :key="t.id" class="wiz-radio">
+                <input type="radio" :value="t.id" v-model="form.type" />
+                <span><strong>{{ t.label }}</strong><br /><small>{{ t.desc }}</small></span>
+              </label>
+            </div>
+          </template>
+
+          <template #redirects>
+            <div class="wiz-page">
+              <p class="wiz-page__hint">Allowed redirect URIs (this step is intentionally tall).</p>
+              <CoarTextInput
+                v-for="(_, i) in form.redirects"
+                :key="i"
+                v-model="form.redirects[i]"
+                placeholder="https://app.example.com/callback"
+              />
+              <button class="wiz-add" type="button" @click="form.redirects.push('')">+ Add URI</button>
+            </div>
+          </template>
+
+          <template #scopes>
+            <div class="wiz-page">
+              <p class="wiz-page__hint">Pick the scopes this client may request.</p>
+              <label v-for="s in scopeList" :key="s" class="wiz-check">
+                <input type="checkbox" :value="s" v-model="form.scopes" /> {{ s }}
+              </label>
+            </div>
+          </template>
+
+          <template #review>
+            <div class="wiz-page">
+              <p class="wiz-page__hint">Review — a short step again, so the modal shrinks back.</p>
+              <ul class="wiz-review">
+                <li><b>Name:</b> {{ form.name || '—' }}</li>
+                <li><b>Type:</b> {{ form.type }}</li>
+                <li><b>Redirects:</b> {{ form.redirects.filter(Boolean).length }}</li>
+                <li><b>Scopes:</b> {{ form.scopes.length }}</li>
+              </ul>
+              <p v-if="created" class="wiz-done">✓ Created!</p>
+            </div>
+          </template>
+        </CoarWizard>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, reactive, ref } from 'vue';
+import {
+  CoarWizard,
+  CoarSegmentedControl,
+  CoarTextInput,
+  type CoarWizardStep,
+  type WizardIndicatorPosition,
+  type CoarSegmentedControlOption,
+} from '@cocoar/vue-ui';
+
+const pos = ref<WizardIndicatorPosition>('top');
+const positions: CoarSegmentedControlOption<WizardIndicatorPosition>[] = [
+  { value: 'top', label: 'Top' },
+  { value: 'right', label: 'Right' },
+  { value: 'bottom', label: 'Bottom' },
+  { value: 'left', label: 'Left' },
+];
+
+const step = ref('basics');
+const created = ref(false);
+
+const form = reactive({
+  name: '',
+  desc: '',
+  type: 'spa',
+  redirects: ['', '', ''],
+  scopes: [] as string[],
+});
+
+const types = [
+  { id: 'spa', label: 'Single-page app', desc: 'Public client, PKCE' },
+  { id: 'web', label: 'Web server', desc: 'Confidential client with a secret' },
+  { id: 'machine', label: 'Machine-to-machine', desc: 'Client credentials grant' },
+];
+const scopeList = ['openid', 'profile', 'email', 'offline_access', 'api:read', 'api:write', 'admin'];
+
+// `canAdvance` on the first step gates Next until a name is typed.
+const steps = computed<CoarWizardStep[]>(() => [
+  { id: 'basics', label: 'Basics', description: 'Name', canAdvance: form.name.trim().length > 0 },
+  { id: 'type', label: 'Client type' },
+  { id: 'redirects', label: 'Redirect URIs', optional: true },
+  { id: 'scopes', label: 'Scopes' },
+  { id: 'review', label: 'Review' },
+]);
+</script>
+
+<style scoped>
+.wiz-demo { display: flex; flex-direction: column; gap: 12px; }
+.wiz-demo__controls { display: flex; align-items: center; gap: 8px; }
+.wiz-demo__label { font-size: 13px; color: var(--coar-text-neutral-secondary); }
+
+/* Modal stand-in: fixed width, content-driven height (so the resize shows). */
+.wiz-modal {
+  width: 460px;
+  max-width: 100%;
+  border: 1px solid var(--coar-border-neutral);
+  border-radius: var(--coar-radius-xl);
+  background: var(--coar-background-neutral-primary);
+  box-shadow: var(--coar-shadow-m, 0 8px 24px rgba(0, 0, 0, 0.12));
+  overflow: hidden;
+}
+.wiz-modal__header {
+  padding: 14px 18px;
+  font-weight: 600;
+  border-bottom: 1px solid var(--coar-border-neutral);
+}
+.wiz-modal__body { padding: 18px; }
+
+.wiz-page { display: flex; flex-direction: column; gap: 10px; }
+.wiz-page__hint { margin: 0; font-size: 13px; color: var(--coar-text-neutral-secondary); }
+
+.wiz-radio, .wiz-check {
+  display: flex; gap: 8px; align-items: flex-start;
+  font-size: 14px; cursor: pointer;
+}
+.wiz-check { align-items: center; }
+.wiz-add {
+  align-self: flex-start; border: none; background: transparent; cursor: pointer;
+  color: var(--coar-text-accent-primary); font: inherit; padding: 2px 0;
+}
+.wiz-review { margin: 0; padding-left: 1.1em; font-size: 14px; line-height: 1.7; }
+.wiz-done { margin: 4px 0 0; color: var(--coar-text-semantic-success-bold, #16a34a); font-weight: 600; }
+</style>
+```
+
+```vue
+<template>
+  <CoarWizard :steps="steps" v-model:step="step" @finish="create">
+    <template #basics>…</template>
+    <template #scopes>…</template>
+    <template #review>…</template>
+  </CoarWizard>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarWizard, type CoarWizardStep } from '@cocoar/vue-ui';
+
+const step = ref('basics');
+const steps: CoarWizardStep[] = [
+  { id: 'basics', label: 'Basics', canAdvance: true },
+  { id: 'scopes', label: 'Scopes' },
+  { id: 'review', label: 'Review' },
+];
+</script>
+```
+
+> **Tip: Designed for modals**
+>
+> The wizard renders no modal — drop it into your modal / routed-modal body. Give that modal a **content-driven height** (and a `max-height` for very tall steps) so the per-step resize animation is visible.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `steps` | `CoarWizardStep[]` | — | Ordered steps. Each `id` names that step's content slot. |
+| `step` (`v-model:step`) | `string` | _first step_ | The active step id. Uncontrolled (defaults to the first step) when not bound. |
+| `indicatorPosition` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Which edge the indicator sits on. `top`/`bottom` scroll horizontally; `left`/`right` vertically. |
+| `freeNavigation` | `boolean` | `false` | Allow jumping to any non-disabled step from the indicator (default: only completed steps are clickable). |
+| `hideFooter` | `boolean` | `false` | Hide the built-in Back / Next / Finish footer. |
+| `disableAnimation` | `boolean` | `false` | Skip the height + content transition (also auto-skipped under `prefers-reduced-motion`). |
+| `backLabel` / `nextLabel` / `finishLabel` | `string` | `Back` / `Next` / `Finish` | Built-in button labels. |
+
+### `CoarWizardStep`
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string` | Stable id + content slot name. |
+| `label` | `string` | Indicator label. |
+| `description` | `string?` | Optional second line under the label. |
+| `optional` | `boolean?` | Marks the step optional in the indicator. |
+| `canAdvance` | `boolean?` | When `false`, the built-in Next is disabled on this step (per-step gate). Defaults to allowed. |
+| `disabled` | `boolean?` | Prevents navigating to this step from the indicator. |
+
+## Slots
+
+| Slot | Props | Description |
+|---|---|---|
+| `<step id>` | `{ step, index }` | Content for that step. Only the active step's slot is rendered. |
+| `footer` | `{ next, back, goTo, isFirst, isLast, canAdvance, activeStep, activeIndex }` | Replace the built-in footer with your own controls. |
+
+## Events
+
+| Event | Payload | Description |
+|---|---|---|
+| `update:step` | `string` | Active step id changed. |
+| `step-change` | `(id, index)` | Active step changed. |
+| `finish` | — | Next pressed on the last step. |

package/skills/cocoar-vue-ui/references/components/zoned-date-time-picker.md

@@ -0,0 +1,177 @@
+<!-- Generated from apps/docs/components/zoned-date-time-picker.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Zoned DateTime Picker
+
+The full-featured datetime picker for timezone-aware values. It captures a date, time, and IANA timezone as a single `Temporal.ZonedDateTime`, making it easy to derive UTC instants for storage while preserving the user's original intent.
+
+```ts
+import { CoarZonedDateTimePicker } from '@cocoar/vue-ui';
+```
+
+> **Info**
+>
+> **Store intent, derive math.** Persist the user's chosen local time and timezone. You can always recalculate the UTC instant later -- and if DST rules change in the future, the recalculation will still be correct.
+
+## Basic Usage
+
+The picker defaults to the user's system timezone. Select a date, adjust the time, and optionally change the timezone. The bound value carries all three pieces of information.
+
+**Demo — `zoned-date-time-picker/demos/BasicZonedDateTimePicker.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 360px;">
+    <CoarFormField label="Meeting Time">
+      <CoarZonedDateTimePicker
+        v-model="value"
+        placeholder="DD.MM.YYYY HH:mm"
+      />
+    </CoarFormField>
+    <span style="font-size: 13px; color: #64748b;">
+      ZonedDateTime: {{ value?.toString() ?? 'none' }}
+    </span>
+    <span v-if="value" style="font-size: 13px; color: #64748b;">
+      UTC Instant: {{ value.toInstant().toString() }}
+    </span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarZonedDateTimePicker, CoarFormField } from '@cocoar/vue-ui';
+import type { Temporal } from '@js-temporal/polyfill';
+
+const value = ref<Temporal.ZonedDateTime | null>(null);
+</script>
+```
+
+## Working with UTC
+
+Converting to a UTC instant for API calls or database storage is a one-liner:
+
+```ts
+// Get UTC instant from ZonedDateTime
+const utcInstant = value.value?.toInstant().toString();
+// → "2024-03-15T14:30:00Z"
+
+// Get ISO string with offset
+const isoString = value.value?.toString();
+// → "2024-03-15T15:30:00+01:00[Europe/Berlin]"
+```
+
+## States
+
+All standard form states are supported: `required`, `error`, `disabled`, and `readonly`.
+
+**Demo — `zoned-date-time-picker/demos/ZonedDateTimePickerStates.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 360px;">
+    <CoarFormField label="Required" required>
+      <CoarZonedDateTimePicker placeholder="DD.MM.YYYY HH:mm" :required="true" />
+    </CoarFormField>
+    <CoarFormField label="With Error" error="Invalid date/time">
+      <CoarZonedDateTimePicker placeholder="DD.MM.YYYY HH:mm" />
+    </CoarFormField>
+    <CoarFormField label="Disabled">
+      <CoarZonedDateTimePicker placeholder="DD.MM.YYYY HH:mm" :disabled="true" />
+    </CoarFormField>
+    <CoarFormField label="Readonly">
+      <CoarZonedDateTimePicker placeholder="DD.MM.YYYY HH:mm" :readonly="true" />
+    </CoarFormField>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarZonedDateTimePicker, CoarFormField } from '@cocoar/vue-ui';
+</script>
+```
+
+## Sizes
+
+Four sizes that stay visually aligned with every other Cocoar input component.
+
+**Demo — `zoned-date-time-picker/demos/ZonedDateTimePickerSizes.vue`**
+
+```vue
+<template>
+  <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 12px;">
+    <CoarFormField label="Extra Small">
+      <CoarZonedDateTimePicker size="xs" placeholder="DD.MM.YYYY HH:mm" />
+    </CoarFormField>
+    <CoarFormField label="Small">
+      <CoarZonedDateTimePicker size="s" placeholder="DD.MM.YYYY HH:mm" />
+    </CoarFormField>
+    <CoarFormField label="Medium">
+      <CoarZonedDateTimePicker size="m" placeholder="DD.MM.YYYY HH:mm" />
+    </CoarFormField>
+    <CoarFormField label="Large">
+      <CoarZonedDateTimePicker size="l" placeholder="DD.MM.YYYY HH:mm" />
+    </CoarFormField>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarZonedDateTimePicker, CoarFormField } from '@cocoar/vue-ui';
+</script>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Move focus between date, time, and timezone inputs |
+| `Enter` | Open calendar / confirm selection |
+| `Escape` | Close calendar dropdown |
+| `Arrow Keys` | Navigate within the calendar |
+
+### Screen Reader Support
+
+- Label text announces on focus
+- Date, time, and timezone portions are independently accessible
+- Selected timezone is announced
+- Required and error states announced
+
+## i18n Keys
+
+These keys can be translated via [`@cocoar/vue-localization`](../foundations/localization/translations.md).
+
+| Key | Default (English) | Used as |
+|-----|-------------------|---------|
+| `coar.ui.zonedDateTimePicker.dialog` | `'Date, time and timezone picker'` | Overlay dialog `aria-label` |
+| `coar.ui.zonedDateTimePicker.clearValue` | `'Clear value'` | Clear button `aria-label` |
+| `coar.ui.zonedDateTimePicker.openPicker` | `'Open date and time picker'` | Calendar button `aria-label` |
+| `coar.ui.zonedDateTimePicker.timezoneIndicator` | `'Timezone: {tz}'` | Timezone indicator `aria-label` |
+| `coar.ui.zonedDateTimePicker.clickToToggle` | `'Click to toggle.'` | Timezone indicator `aria-label` suffix |
+| `coar.ui.zonedDateTimePicker.searchTimezone` | `'Search timezone...'` | Timezone search placeholder |
+| `coar.ui.zonedDateTimePicker.closeTimezoneSearch` | `'Close timezone search'` | Close search button `aria-label` |
+| `coar.ui.zonedDateTimePicker.displayTimezone` | `'Display Timezone'` | Display timezone section label |
+| `coar.ui.zonedDateTimePicker.eventTimezone` | `'Event timezone'` | Footer placeholder text |
+| `coar.ui.zonedDateTimePicker.cancelTimezoneEdit` | `'Cancel timezone edit'` | Cancel button `aria-label` |
+| `coar.ui.zonedDateTimePicker.changeEventTimezone` | `'Change event timezone'` | Settings button `aria-label` |
+| `coar.ui.datePicker.jumpToToday` | `'Jump to today\'s month'` | Scroll-to-today button `aria-label` |
+| `coar.ui.datePicker.previousYear` | `'Previous year'` | Previous year button `aria-label` |
+| `coar.ui.datePicker.nextYear` | `'Next year'` | Next year button `aria-label` |
+| `coar.ui.datePicker.months` | `'Months'` | Month grid `aria-label` |
+| `coar.ui.timePicker.*` | *(see DateTime Picker)* | Time picker spinbutton labels |
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `v-model` | `Temporal.ZonedDateTime \| null` | `null` | Selected zoned datetime |
+| `timezone` | `string` | user's timezone | IANA timezone ID (e.g. `'Europe/Berlin'`) |
+| `placeholder` | `string` | `''` | Placeholder text |
+| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Input size |
+| `disabled` | `boolean` | `false` | Disable the picker |
+| `readonly` | `boolean` | `false` | Make read-only |
+| `required` | `boolean` | `false` | Mark as required |
+| `error` | `boolean` | `false` | Error state (red border + `aria-invalid`). Auto-injected from a wrapping [`CoarFormField`](./form-field.md). |
+| `id` | `string` | `''` | Explicit input id (else taken from `CoarFormField`, else auto). |
+
+> **Label, hint, error message and the status icon live on the wrapping [`CoarFormField`](./form-field.md)** — not on the picker. Wrap the picker in a `CoarFormField` for a label, the required asterisk, validation messages and the inline status indicator; the picker auto-adopts the field's id, error state and `aria-describedby` via injection.