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

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

@@ -0,0 +1,200 @@
+<!-- Generated from apps/docs/components/date-or-time-picker.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Date · optional time
+
+Sometimes a field is "a date, and *maybe* a time" — a due date that's usually
+just a day but occasionally needs an hour, a reminder that can be all-day or
+timed. Instead of a separate checkbox, these pickers put a small **clock toggle
+beside the field**: off means a plain date, on means a date with time.
+
+Two variants, by whether the time carries a timezone:
+
+```ts
+import {
+  CoarZonedDateTimeOrDatePicker, // PlainDate  ⇄  ZonedDateTime (with IANA zone)
+  CoarPlainDateTimeOrDatePicker, // PlainDate  ⇄  PlainDateTime (zone-less)
+} from '@cocoar/vue-ui';
+```
+
+## Basic usage
+
+Click the clock to switch modes. The value is one of two `Temporal` types — read
+it directly to know what you got.
+
+**Demo — `date-or-time-picker/demos/BasicOptionalTime.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 420px;">
+    <CoarFormField label="Due">
+      <CoarZonedDateTimeOrDatePicker v-model="value" v-model:with-time="withTime" clearable />
+    </CoarFormField>
+    <span style="font-size: 13px; color: #64748b;">
+      {{ withTime ? 'with time' : 'date only' }} →
+      <code>{{ value ? `${value.constructor.name}: ${value.toString()}` : 'null' }}</code>
+    </span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarZonedDateTimeOrDatePicker, CoarFormField } from '@cocoar/vue-ui';
+import type { Temporal } from '@js-temporal/polyfill';
+
+// One value, two shapes: a PlainDate while the clock is off, a ZonedDateTime when on.
+const value = ref<Temporal.ZonedDateTime | Temporal.PlainDate | null>(null);
+const withTime = ref(false);
+</script>
+```
+
+## The value model
+
+A single `v-model` carries the **union** value, and `v-model:withTime` is the
+toggle. They stay in sync: a non-null value's own type *is* the mode, and while
+empty the toggle decides.
+
+```vue
+<CoarZonedDateTimeOrDatePicker v-model="value" v-model:with-time="withTime" />
+```
+
+```ts
+// value is Temporal.ZonedDateTime | Temporal.PlainDate | null
+if (value instanceof Temporal.ZonedDateTime) {
+  // time was on — persist a timestamp
+} else if (value instanceof Temporal.PlainDate) {
+  // date only — persist a calendar date
+}
+```
+
+Toggling **on** keeps the date and adds a time (the current time, rounded to
+`minuteStep`) — and, for the zoned variant, the `timeZone` (or the user's zone).
+Toggling **off** drops the time (and zone) back to the date. So flipping the
+clock never loses the day.
+
+## Zone-less variant
+
+`CoarPlainDateTimeOrDatePicker` is the same idea without timezones — the with-time
+value is a `Temporal.PlainDateTime`.
+
+**Demo — `date-or-time-picker/demos/PlainOptionalTime.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 420px;">
+    <CoarFormField label="Reminder">
+      <CoarPlainDateTimeOrDatePicker v-model="value" v-model:with-time="withTime" clearable />
+    </CoarFormField>
+    <span style="font-size: 13px; color: #64748b;">
+      {{ withTime ? 'with time' : 'date only' }} →
+      <code>{{ value ? `${value.constructor.name}: ${value.toString()}` : 'null' }}</code>
+    </span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarPlainDateTimeOrDatePicker, CoarFormField } from '@cocoar/vue-ui';
+import type { Temporal } from '@js-temporal/polyfill';
+
+// The zone-less variant: PlainDate while off, PlainDateTime when on.
+const value = ref<Temporal.PlainDateTime | Temporal.PlainDate | null>(null);
+const withTime = ref(false);
+</script>
+```
+
+## Toggle position & sizes
+
+The clock sits to the **left** by default; set `toggle-position="end"` for the
+right. Sizes match the rest of the form-control family (`xs` · `s` · `m` · `l`),
+and the toggle scales with the field.
+
+**Demo — `date-or-time-picker/demos/OptionalTimeSizes.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 16px; max-width: 460px;">
+    <div v-for="s in sizes" :key="s" style="display: flex; align-items: center; gap: 12px;">
+      <code style="width: 24px; font-size: 12px; color: #64748b;">{{ s }}</code>
+      <CoarZonedDateTimeOrDatePicker v-model="value" v-model:with-time="withTime" :size="s" />
+    </div>
+    <span style="font-size: 13px; color: #64748b;">Toggle position: <code>start</code> (default) — use <code>toggle-position="end"</code> to put the clock on the right.</span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarZonedDateTimeOrDatePicker, type CoarZonedDateTimeOrDatePickerSize } from '@cocoar/vue-ui';
+import type { Temporal } from '@js-temporal/polyfill';
+
+const sizes: CoarZonedDateTimeOrDatePickerSize[] = ['xs', 's', 'm', 'l'];
+const value = ref<Temporal.ZonedDateTime | Temporal.PlainDate | null>(null);
+const withTime = ref(false);
+</script>
+```
+
+> **Info: Composition, not reinvention**
+>
+> These are thin wrappers over [`CoarPlainDatePicker`](./date-picker.md),
+> [`CoarPlainDateTimePicker`](./date-time-picker.md) and
+> [`CoarZonedDateTimePicker`](./zoned-date-time-picker.md) — they render the
+> existing picker for the active mode and add the toggle beside it. All the
+> common props pass straight through.
+
+## Theming
+
+There's no new chrome to theme: the field is a `CoarInputFrame` and the toggle a
+`CoarButton`, both driven by the usual tokens. The toggle's roundness **tracks
+`--coar-input-radius`**, so it always matches the adjacent field (a pill theme
+gives a round toggle), and the gap uses `--coar-spacing-xs`. Nothing to register
+in the theme editor — tuning the existing input / button / spacing / accent
+tokens restyles these too.
+
+## Accessibility
+
+The clock is a toggle button: it exposes `aria-pressed` for its state and a
+state-aware tooltip + `aria-label` (**Add time** when off, **Remove time** when
+on, both overridable). The active field itself is the underlying picker, so its
+keyboard and screen-reader behaviour is identical to the standalone pickers.
+
+> Wrap the picker in a [`CoarFormField`](./form-field.md) for a label, the
+> required asterisk, validation message and status icon — exactly like the other
+> date pickers. The field auto-adopts the form field's id and error state.
+
+## API
+
+Both components share this surface (the zoned variant adds the timezone props).
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `v-model` | `PlainDate \| ZonedDateTime \| null` (zoned)<br>`PlainDate \| PlainDateTime \| null` (plain) | `null` | The union value. |
+| `v-model:withTime` | `boolean` | `false` | The clock toggle / mode. |
+| `placeholder` | `string` | `''` | Placeholder text. |
+| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Field + toggle size. |
+| `disabled` | `boolean` | `false` | Disable the field and toggle. |
+| `readonly` | `boolean` | `false` | Read-only (toggle disabled too). |
+| `required` | `boolean` | `false` | Mark as required. |
+| `error` | `boolean` | `false` | Error state. Auto-injected from a wrapping `CoarFormField`. |
+| `clearable` | `boolean` | `false` | Show the inline clear button. |
+| `locale` | `string` | — | Locale override. |
+| `min` / `max` | with-time type | `null` | Bounds; the date mode uses their date part. |
+| `minuteStep` | `1 \| 5 \| 10 \| 15` | `5` | Time-of-day step (also the default-time rounding). |
+| `togglePosition` | `'start' \| 'end'` | `'start'` | Clock side, relative to the field. |
+| `addTimeLabel` | `string` | `'Add time'` | Tooltip + label while time is off. |
+| `removeTimeLabel` | `string` | `'Remove time'` | Tooltip + label while time is on. |
+
+**Zoned variant only:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `timeZone` | `string \| null` | `null` | Default IANA zone for a value gaining a time (else the user's zone). |
+| `timezoneFilter` | `string[]` | `[]` | Wildcard filters for the timezone list (e.g. `['Europe/*']`). |
+
+### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | union value | The value changed. |
+| `update:withTime` | `boolean` | The mode changed. |
+| `opened` / `closed` | — | The calendar panel opened / closed. |

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

@@ -0,0 +1,203 @@
+<!-- Generated from apps/docs/components/date-picker.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Date Picker
+
+A calendar-backed date picker that returns a `Temporal.PlainDate` -- a date without time or timezone. Perfect for birthdays, deadlines, due dates, and any scenario where "which day" is all that matters.
+
+```ts
+import { CoarPlainDatePicker } from '@cocoar/vue-ui';
+```
+
+## Basic Usage
+
+Click the input to open a calendar dropdown. The selected value is a proper `Temporal.PlainDate`, so date math and formatting are straightforward.
+
+**Demo — `date-picker/demos/BasicDatePicker.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 320px;">
+    <CoarFormField label="Select date">
+      <CoarPlainDatePicker
+        v-model="date"
+        placeholder="DD.MM.YYYY"
+      />
+    </CoarFormField>
+    <span style="font-size: 13px; color: #64748b;">Selected: {{ date?.toString() ?? 'none' }}</span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarPlainDatePicker, CoarFormField } from '@cocoar/vue-ui';
+import type { Temporal } from '@js-temporal/polyfill';
+
+const date = ref<Temporal.PlainDate | null>(null);
+</script>
+```
+
+## Required & Error States
+
+Combine `required` and `error` props for form validation. The required asterisk and error message integrate with the same patterns as every other Cocoar input.
+
+**Demo — `date-picker/demos/DatePickerValidation.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 320px;">
+    <CoarFormField label="Birth date" hint="Enter your date of birth" required>
+      <CoarPlainDatePicker
+        placeholder="DD.MM.YYYY"
+        :required="true"
+      />
+    </CoarFormField>
+    <CoarFormField label="Expiry date" error="Date is in the past">
+      <CoarPlainDatePicker
+        placeholder="DD.MM.YYYY"
+      />
+    </CoarFormField>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarPlainDatePicker, CoarFormField } from '@cocoar/vue-ui';
+</script>
+```
+
+## Disabled & Readonly
+
+`disabled` greys out the entire picker; `readonly` lets users see the selected date but prevents changes.
+
+**Demo — `date-picker/demos/DatePickerDisabledReadonly.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 320px;">
+    <CoarFormField label="Disabled">
+      <CoarPlainDatePicker placeholder="DD.MM.YYYY" :disabled="true" />
+    </CoarFormField>
+    <CoarFormField label="Readonly">
+      <CoarPlainDatePicker placeholder="DD.MM.YYYY" :readonly="true" />
+    </CoarFormField>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarPlainDatePicker, CoarFormField } from '@cocoar/vue-ui';
+</script>
+```
+
+## Date Range (Manual)
+
+For start/end date pairs, use two pickers and pass the start date as `:min` on the end picker. This prevents users from selecting an end date before the start.
+
+**Demo — `date-picker/demos/DatePickerRange.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 320px;">
+    <CoarFormField label="Start date">
+      <CoarPlainDatePicker v-model="start" placeholder="From" />
+    </CoarFormField>
+    <CoarFormField label="End date">
+      <CoarPlainDatePicker v-model="end" placeholder="To" :min="start ?? undefined" />
+    </CoarFormField>
+    <span style="font-size: 13px; color: #64748b;">
+      Range: {{ start?.toString() ?? '?' }} &rarr; {{ end?.toString() ?? '?' }}
+    </span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarPlainDatePicker, CoarFormField } from '@cocoar/vue-ui';
+import type { Temporal } from '@js-temporal/polyfill';
+
+const start = ref<Temporal.PlainDate | null>(null);
+const end = ref<Temporal.PlainDate | null>(null);
+</script>
+```
+
+## Sizes
+
+Four sizes to stay consistent with other form controls across your layout.
+
+**Demo — `date-picker/demos/DatePickerSizes.vue`**
+
+```vue
+<template>
+  <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); gap: 12px;">
+    <CoarFormField label="Extra Small">
+      <CoarPlainDatePicker size="xs" placeholder="DD.MM.YYYY" />
+    </CoarFormField>
+    <CoarFormField label="Small">
+      <CoarPlainDatePicker size="s" placeholder="DD.MM.YYYY" />
+    </CoarFormField>
+    <CoarFormField label="Medium">
+      <CoarPlainDatePicker size="m" placeholder="DD.MM.YYYY" />
+    </CoarFormField>
+    <CoarFormField label="Large">
+      <CoarPlainDatePicker size="l" placeholder="DD.MM.YYYY" />
+    </CoarFormField>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarPlainDatePicker, CoarFormField } from '@cocoar/vue-ui';
+</script>
+```
+
+> **Info**
+>
+> **Temporal.PlainDate:** This component uses the TC39 Temporal API (`@js-temporal/polyfill`). PlainDate represents a calendar date without time or timezone -- no more wrestling with midnight UTC offsets.
+
+## Accessibility
+
+### Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Move focus to input / calendar |
+| `Enter` | Open calendar / select date |
+| `Escape` | Close calendar dropdown |
+| `Arrow Keys` | Navigate within the calendar |
+
+### Screen Reader Support
+
+- Label text announces on focus
+- Selected date is read aloud
+- Calendar navigation is keyboard accessible
+- Required and error states announced
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `v-model` | `Temporal.PlainDate \| null` | `null` | Selected date |
+| `placeholder` | `string` | `''` | Placeholder text |
+| `min` | `Temporal.PlainDate` | `undefined` | Minimum selectable date |
+| `max` | `Temporal.PlainDate` | `undefined` | Maximum selectable date |
+| `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` to get 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.
+
+## i18n Keys
+
+These keys can be translated via [`@cocoar/vue-localization`](../foundations/localization/translations.md).
+
+| Key | Default (English) | Used as |
+|-----|-------------------|---------|
+| `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.jumpToToday` | `'Jump to today\'s month'` | Scroll-to-today button `aria-label` |
+| `coar.ui.datePicker.months` | `'Months'` | Month grid `aria-label` |
+| `coar.ui.datePicker.dialog` | `'Date picker'` | Overlay dialog `aria-label` |
+| `coar.ui.datePicker.clearDate` | `'Clear date'` | Clear button `aria-label` |
+| `coar.ui.datePicker.openPicker` | `'Open picker'` | Calendar button `aria-label` |

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

@@ -0,0 +1,154 @@
+<!-- Generated from apps/docs/components/date-time-picker.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# DateTime Picker
+
+Combines a calendar date picker with a time input and returns a `Temporal.PlainDateTime` -- a date and time without any timezone attached. Use this when the timezone is implicit (the user's local time) or irrelevant (an alarm, a reminder). If you need timezone awareness, reach for the [Zoned DateTime Picker](./zoned-date-time-picker.md) instead.
+
+```ts
+import { CoarPlainDateTimePicker } from '@cocoar/vue-ui';
+```
+
+## Basic Usage
+
+Select a date from the calendar, then adjust the time. The bound value is a `Temporal.PlainDateTime` you can format, compare, or serialize as needed.
+
+**Demo — `date-time-picker/demos/BasicDateTimePicker.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 320px;">
+    <CoarFormField label="Appointment">
+      <CoarPlainDateTimePicker
+        v-model="dateTime"
+        placeholder="DD.MM.YYYY HH:mm"
+      />
+    </CoarFormField>
+    <span style="font-size: 13px; color: #64748b;">Selected: {{ dateTime?.toString() ?? 'none' }}</span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarPlainDateTimePicker, CoarFormField } from '@cocoar/vue-ui';
+import type { Temporal } from '@js-temporal/polyfill';
+
+const dateTime = ref<Temporal.PlainDateTime | null>(null);
+</script>
+```
+
+## States
+
+Supports `required`, `error`, `disabled`, and `readonly` -- the same set of states you will find on every Cocoar form control.
+
+**Demo — `date-time-picker/demos/DateTimePickerStates.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 320px;">
+    <CoarFormField label="Required" required>
+      <CoarPlainDateTimePicker placeholder="DD.MM.YYYY HH:mm" :required="true" />
+    </CoarFormField>
+    <CoarFormField label="With Error" error="Invalid date/time">
+      <CoarPlainDateTimePicker placeholder="DD.MM.YYYY HH:mm" />
+    </CoarFormField>
+    <CoarFormField label="Disabled">
+      <CoarPlainDateTimePicker placeholder="DD.MM.YYYY HH:mm" :disabled="true" />
+    </CoarFormField>
+    <CoarFormField label="Readonly">
+      <CoarPlainDateTimePicker placeholder="DD.MM.YYYY HH:mm" :readonly="true" />
+    </CoarFormField>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarPlainDateTimePicker, CoarFormField } from '@cocoar/vue-ui';
+</script>
+```
+
+## Sizes
+
+Four sizes to match surrounding inputs and keep your forms visually balanced.
+
+**Demo — `date-time-picker/demos/DateTimePickerSizes.vue`**
+
+```vue
+<template>
+  <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 12px;">
+    <CoarFormField label="Extra Small">
+      <CoarPlainDateTimePicker size="xs" placeholder="DD.MM.YYYY HH:mm" />
+    </CoarFormField>
+    <CoarFormField label="Small">
+      <CoarPlainDateTimePicker size="s" placeholder="DD.MM.YYYY HH:mm" />
+    </CoarFormField>
+    <CoarFormField label="Medium">
+      <CoarPlainDateTimePicker size="m" placeholder="DD.MM.YYYY HH:mm" />
+    </CoarFormField>
+    <CoarFormField label="Large">
+      <CoarPlainDateTimePicker size="l" placeholder="DD.MM.YYYY HH:mm" />
+    </CoarFormField>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarPlainDateTimePicker, CoarFormField } from '@cocoar/vue-ui';
+</script>
+```
+
+> **Info**
+>
+> **PlainDateTime vs ZonedDateTime:** Choose `PlainDateTime` when the timezone is always the user's local time or when it simply does not matter (alarm clocks, recurring events). Choose `ZonedDateTime` when you need to pin a specific instant in time and derive UTC for storage or sharing across timezones.
+
+## Accessibility
+
+### Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Move focus between date and time 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 and time portions are independently accessible
+- Required and error states announced
+- Calendar navigation is keyboard accessible
+
+## i18n Keys
+
+These keys can be translated via [`@cocoar/vue-localization`](../foundations/localization/translations.md).
+
+| Key | Default (English) | Used as |
+|-----|-------------------|---------|
+| `coar.ui.dateTimePicker.dialog` | `'Date time picker'` | Overlay dialog `aria-label` |
+| `coar.ui.dateTimePicker.clearDate` | `'Clear date'` | Clear button `aria-label` |
+| `coar.ui.dateTimePicker.openPicker` | `'Open picker'` | Calendar 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.increaseHours` | `'Increase hours'` | Hours increment button `aria-label` |
+| `coar.ui.timePicker.decreaseHours` | `'Decrease hours'` | Hours decrement button `aria-label` |
+| `coar.ui.timePicker.hours` | `'Hours'` | Hours spinbutton `aria-label` |
+| `coar.ui.timePicker.increaseMinutes` | `'Increase minutes'` | Minutes increment button `aria-label` |
+| `coar.ui.timePicker.decreaseMinutes` | `'Decrease minutes'` | Minutes decrement button `aria-label` |
+| `coar.ui.timePicker.minutes` | `'Minutes'` | Minutes spinbutton `aria-label` |
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `v-model` | `Temporal.PlainDateTime \| null` | `null` | Selected date+time |
+| `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.