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

package/skills/cocoar-vue-ui/references/components/calendar/work-week-view.md

@@ -0,0 +1,145 @@
+<!-- Generated from apps/docs/components/calendar/work-week-view.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# `<CoarWorkWeekView>` — Work Week View (Preview)
+
+The week view with weekend columns filtered out. Configurable working-day set via `builder.workDays(...)` — defaults to Mon–Fri but adapts to 6-day operations (Mon–Sat), 4-day weeks (Mon–Thu), Sun–Thu Middle-East work weeks, or any other DayOfWeek subset.
+
+Mechanically the work-week view is a preset of the one time-grid model shared with [`<CoarDayView>`](./day-view.md#one-model-for-every-time-grid) and [`<CoarWeekView>`](./week-view.md): anchor `weekStart`, span 7, filter `workDays`, step 7. Same time-grid, same DnD pipeline, same slot rendering, same all-day band, same touch paging. The visible-range `ViewWindow` stays the full Mon–Sun span — only the columns rendered differ. Loaders see weekend events the same way they do for the full week.
+
+```html
+<CoarWorkWeekView :builder="builder" />
+```
+
+## Standalone usage
+
+```ts
+import { ref } from 'vue';
+import { Temporal } from '@js-temporal/polyfill';
+import {
+  CoarWorkWeekView,
+  useWorkWeekView,
+  type CalendarEvent,
+} from '@cocoar/vue-calendar';
+
+const events = ref<CalendarEvent[]>([
+  {
+    id: 'standup',
+    start: Temporal.ZonedDateTime.from('2026-04-15T09:00:00[Europe/Vienna]'),
+    end:   Temporal.ZonedDateTime.from('2026-04-15T09:30:00[Europe/Vienna]'),
+  },
+]);
+const date = ref('2026-04-15');
+
+const { builder } = useWorkWeekView();
+builder
+  .events(events)
+  .date(date)
+  .timezone('Europe/Vienna')
+  .firstDayOfWeek(1)            // Monday — overrides locale default
+  .workDays([1, 2, 3, 4, 5]);   // Mon–Fri (default — shown for clarity)
+```
+
+```html
+<CoarWorkWeekView :builder="builder" />
+```
+
+## Working-day conventions
+
+`workDays(d)` accepts any subset of `0..6` (`0` = Sunday, `6` = Saturday). The order in the array doesn't matter — internally it's used as a Set. The rendered columns appear in calendar order, anchored to `firstDayOfWeek`.
+
+```ts
+builder.workDays([1, 2, 3, 4, 5]);        // Mon–Fri (default)
+builder.workDays([1, 2, 3, 4, 5, 6]);     // Mon–Sat (retail / hospitality)
+builder.workDays([1, 2, 3, 4]);           // Mon–Thu (4-day week experiments)
+builder.workDays([0, 1, 2, 3, 4]);        // Sun–Thu (Middle East, parts of South Asia)
+```
+
+> **Tip: Reactive `workDays`**
+>
+> `workDays(d)` accepts `MaybeRefOrGetter`, so a `ref<DayOfWeek[]>` flips the rendered columns live. Useful for "show Saturday too" toggles in operations dashboards without a full reload.
+
+## Window vs render set
+
+`builder.api.getVisibleRange()` for the work-week view returns the **full Mon–Sun span**, not the filtered weekday subset. Two reasons:
+
+- **`eventsLoader(window)` and `seriesLoader(window)`** should fetch weekend events too. Consumers may want to keep them in the database, filter them in the data layer, or rely purely on the view to suppress weekend columns; the loader doesn't need to know the column set.
+- **`api.getVisibleEvents()`** returns events that touch any day in the full span, including weekends. A Saturday client demo still shows up in the event list (e.g. for "what did we work on this week?" summaries), just not as a rendered pill in the grid.
+
+If your use case needs the rendered-columns date set, call `workWeekDates(cursor, firstDayOfWeek, workDays)` from `@cocoar/vue-calendar` directly.
+
+## Navigation
+
+`prev()` / `next()` step by 7 days, same as the [Week view](./week-view.md) — *not* by the count of working days. Stepping by 5 days would leave the cursor on a weekend on alternate clicks, breaking the "this week / next week" mental model. The workday filter is a render concern, not a navigation one.
+
+## Inside `<CoarCalendar>`
+
+When `<CoarCalendar>` is active and the user clicks the "Work week" view-switcher button, the shell mounts `<CoarWorkWeekView>` and the same builder feeds it — view-specific settings (`timeRange`, `slotDuration`, `pixelsPerHour`) apply identically to Week and WorkWeek.
+
+```ts
+const { builder } = useCalendar();
+builder
+  .timeRange({ startMinutes: 8 * 60, endMinutes: 18 * 60 })
+  .workDays([1, 2, 3, 4, 5]);
+```
+
+The shell's default `availableViews` includes `'workWeek'`, so the view-switcher gets a "Work week" button automatically. Hide it by setting your own list:
+
+```ts
+builder.availableViews(['month', 'week', 'day', 'agenda']);
+```
+
+## `useWorkWeekView<TMeta>()`
+
+```ts
+function useWorkWeekView<TMeta>(): {
+  builder: CalendarBuilder<TMeta>;
+  api: CalendarApi<TMeta>;
+};
+```
+
+Returns a fresh standalone builder + its imperative api. Pre-sets `view: 'workWeek'` and `availableViews: ['workWeek']` so the standalone view doesn't render an inactive view-switcher.
+
+## Builder setters
+
+Full reference: see [the composer's API reference](./coar-calendar.md#api-reference). Highlights specific to the work-week view:
+
+| Setter | Argument | Default | Notes |
+|---|---|---|---|
+| `workDays(d)` | `MaybeRefOrGetter<readonly DayOfWeek[]>` | `[1, 2, 3, 4, 5]` | `0` = Sunday … `6` = Saturday. Empty array renders zero columns. |
+| `firstDayOfWeek(d)` | `0..6 \| undefined` | locale-aware | Affects the underlying week's anchor; the workDays filter is applied on top. |
+| `timeRange(r)` | `MaybeRefOrGetter<{ startMinutes, endMinutes }>` | `{0, 1440}` | Visible hour range, in minutes from midnight. |
+| `slotDuration(d)` | `MaybeRefOrGetter<number>` | `30` | Slot subdivision (minutes). Also the snap step when dragging. |
+| `pixelsPerHour(p)` | `MaybeRefOrGetter<number>` | `60` | Vertical density. |
+| `dayHeaderRenderer(r)` | `DayHeaderRenderer` | — | Per-day column header — same slot as Week. |
+| `eventRenderer(r)` | `EventRenderer<TMeta>` | — | Universal renderer. Same `ctx.layout?.kind` discriminator as Week (`'positioned'` for time-grid events, `'allDayBar'` for the all-day band). |
+
+## `workWeekDates(date, firstDayOfWeek, workDays)`
+
+Pure helper exported from `@cocoar/vue-calendar`. Returns the subset of `weekDates(date, firstDayOfWeek)` whose day-of-week is in `workDays`, in calendar order.
+
+```ts
+import { workWeekDates, Temporal } from '@cocoar/vue-calendar';
+
+const dates = workWeekDates(
+  Temporal.PlainDate.from('2026-06-10'),
+  1,                                          // Monday-first
+  [1, 2, 3, 4, 5],                            // Mon–Fri
+);
+// → [2026-06-08, 2026-06-09, 2026-06-10, 2026-06-11, 2026-06-12]
+```
+
+## Imperative API
+
+Same surface as the Week view — see [`<CoarWeekView>` Imperative API](./week-view.md#imperative-api). `next()` / `prev()` step by 7 days; `getVisibleRange()` returns the full Mon–Sun window.
+
+## `<CoarWorkWeekView>` props + slots
+
+| Prop | Type | Description |
+|---|---|---|
+| `builder` | `CalendarBuilder` | **Required.** From `useWorkWeekView()` (or share the one from `useCalendar()`). |
+
+| Slot | Scope | Purpose |
+|---|---|---|
+| `event` | `{ event, layout }` | Per-event renderer. `layout` is the `PositionedEvent` (lane / startMinutes / endMinutes / clipping flags). |
+| `allDayEvent` | `{ event, layout }` | All-day band renderer. `layout` is the `AllDayBar`. |
+| `dayHeader` | `{ date, isToday, isWeekend }` | Per-day column header. `isWeekend` is true for Sat/Sun columns *even if hidden by `workDays`* — useful for custom renderers that compute their own styling. |

package/skills/cocoar-vue-ui/references/components/calendar/year-view.md

@@ -0,0 +1,63 @@
+<!-- Generated from apps/docs/components/calendar/year-view.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# `<CoarYearView>` — Year View (Preview)
+
+Responsive twelve-month overview. The grid automatically chooses how many month cards fit across the available width, uses the configured locale / first weekday, and marks today. Selecting a month title or a day updates the builder cursor and drills into Month.
+
+The Year view intentionally shows date structure rather than event density. It does not render event pills or occurrence markers. Loader and range-change consumers still receive the ordinary year `ViewWindow`, so applications can decide whether to return data for that surface.
+
+## In `<CoarCalendar>`
+
+Year is part of the default primary hierarchy. Include both `year` and `month` when filtering views so drill-in has a visible destination:
+
+```ts
+import { Temporal } from '@js-temporal/polyfill';
+import { useCalendar } from '@cocoar/vue-calendar';
+
+const { builder, api } = useCalendar();
+builder
+  .view('year')
+  .date(Temporal.PlainDate.from('2026-08-06'))
+  .timezone('Europe/Vienna')
+  .locale('de-AT')
+  .availableViews(['year', 'month']);
+
+api.next(); // 2027
+api.prev(); // 2026
+```
+
+```html
+<CoarCalendar :builder="builder" />
+```
+
+## Standalone
+
+`<CoarYearView>` consumes the same flat `CalendarBuilder`. There is no separate year builder because the view needs the ordinary cursor and `api.setView('month')` drill-in contract.
+
+```ts
+import { CoarYearView, useCalendar } from '@cocoar/vue-calendar';
+
+const { builder } = useCalendar();
+builder.view('year').availableViews(['year', 'month']);
+```
+
+```html
+<CoarYearView :builder="builder" />
+```
+
+## Configuration
+
+| Setter | Default | Purpose |
+|---|---|---|
+| `date(d)` | today in the display zone | Selects the visible year. |
+| `timezone(tz)` | browser zone | Determines which date receives the today marker. |
+| `locale(loc)` | `'en-US'` | Month and weekday labels. |
+| `firstDayOfWeek(d)` | locale-derived | Overrides weekday order (`0` = Sunday … `6` = Saturday). |
+
+`next()` and `prev()` move by one calendar year while Year is active. Clicking a day keeps that exact date as the Month cursor; clicking a month title selects the first day of that month.
+
+## Prop
+
+| Prop | Type | Description |
+|---|---|---|
+| `builder` | `CalendarBuilder` | **Required.** Usually from `useCalendar()`. |

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

@@ -0,0 +1,151 @@
+<!-- Generated from apps/docs/components/card.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Card
+
+Cards group related content into a visually distinct container, making it easy for users to scan and interact with discrete chunks of information. Use them for dashboards, content feeds, settings panels, or anywhere you need clear visual boundaries.
+
+```ts
+import { CoarCard } from '@cocoar/vue-ui';
+```
+
+## Basic Usage
+
+A straightforward card with a title and body text. Cards provide structure without imposing rigid layout rules -- just slot in whatever content you need.
+
+**Demo — `card/demos/CardBasic.vue`**
+
+```vue
+<template>
+  <CoarCard elevated>
+    <h4 style="margin: 0 0 4px;">Card Title</h4>
+    <p style="margin: 0; font-size: 14px;">This is a basic card with default settings. Cards help organize content into distinct sections.</p>
+  </CoarCard>
+</template>
+
+<script setup lang="ts">
+import { CoarCard } from '@cocoar/vue-ui';
+</script>
+```
+
+## Elevated vs Outlined
+
+Choose `elevated` for cards that need to stand out from the page (primary content), or `outlined` for a subtler border-based style that sits flatter in the layout.
+
+**Demo — `card/demos/CardElevatedOutlined.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px;">
+    <CoarCard elevated>
+      <span style="font-size: 14px;">Elevated — box shadow for depth</span>
+    </CoarCard>
+    <CoarCard variant="outlined">
+      <span style="font-size: 14px;">Outlined — border without shadow</span>
+    </CoarCard>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarCard } from '@cocoar/vue-ui';
+</script>
+```
+
+## Color Variants
+
+Semantic color variants add a tinted background to convey meaning at a glance -- info for tips, success for confirmations, warning and error for alerts.
+
+**Demo — `card/demos/CardVariants.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <CoarCard variant="info" elevated><span style="font-size: 14px;">Info — tips, guidance, neutral context</span></CoarCard>
+    <CoarCard variant="success" elevated><span style="font-size: 14px;">Success — positive results</span></CoarCard>
+    <CoarCard variant="warning" elevated><span style="font-size: 14px;">Warning — caution, attention needed</span></CoarCard>
+    <CoarCard variant="error" elevated><span style="font-size: 14px;">Error — problems, validation failures</span></CoarCard>
+    <CoarCard variant="neutral" elevated><span style="font-size: 14px;">Neutral — default, no semantic meaning</span></CoarCard>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarCard } from '@cocoar/vue-ui';
+</script>
+```
+
+## Padding Sizes
+
+Adjust internal spacing to suit your content density. Use `s` for compact data cards, `m` for general use, and `l` when the card is the primary focus of the page.
+
+**Demo — `card/demos/CardPadding.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px;">
+    <CoarCard elevated padding="s">
+      <span style="font-size: 14px;">Small padding (s)</span>
+    </CoarCard>
+    <CoarCard elevated padding="m">
+      <span style="font-size: 14px;">Medium padding (m) — default</span>
+    </CoarCard>
+    <CoarCard elevated padding="l">
+      <span style="font-size: 14px;">Large padding (l)</span>
+    </CoarCard>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarCard } from '@cocoar/vue-ui';
+</script>
+```
+
+## Rich Content Example
+
+Cards shine when combining multiple elements. Here a header, tags, body text, and action buttons work together inside a single card.
+
+**Demo — `card/demos/CardRichContent.vue`**
+
+```vue
+<template>
+  <CoarCard elevated style="max-width: 400px;">
+    <div style="display: flex; justify-content: space-between; align-items: flex-start; margin-bottom: 4px;">
+      <h4 style="margin: 0;">New Feature Release</h4>
+      <span style="font-size: 14px; color: #64748b;">2 hours ago</span>
+    </div>
+    <p style="margin: 8px 0; font-size: 14px;">
+      We've just released a major update to the date picker component. It now supports timezone-aware datetime selection using the Temporal API.
+    </p>
+    <div style="display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 12px;">
+      <CoarTag variant="info">New</CoarTag>
+      <CoarTag variant="success">Stable</CoarTag>
+    </div>
+    <div style="display: flex; flex-wrap: wrap; gap: 8px;">
+      <CoarButton variant="primary" size="s">Read More</CoarButton>
+      <CoarButton variant="ghost" size="s">Dismiss</CoarButton>
+    </div>
+  </CoarCard>
+</template>
+
+<script setup lang="ts">
+import { CoarCard, CoarTag, CoarButton } from '@cocoar/vue-ui';
+</script>
+```
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'neutral' \| 'outlined' \| 'info' \| 'success' \| 'warning' \| 'error' \| 'accent'` | `'neutral'` | Card color/style variant |
+| `padding` | `'none' \| 's' \| 'm' \| 'l'` | `'m'` | Internal padding size |
+| `elevated` | `boolean` | `false` | Add box shadow for elevation |
+| `borderless` | `boolean` | `false` | Hide the border |
+
+### Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Card content |
+| `#header` | Fixed header area |
+| `#footer` | Fixed footer area |
+| `#inset` | Full-width inset area (negative margins) |

package/skills/cocoar-vue-ui/references/components/checkbox-group.md

@@ -0,0 +1,103 @@
+<!-- Generated from apps/docs/components/checkbox-group.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Checkbox Group
+
+`CoarCheckboxGroup` turns multiple keyed checkboxes into one field value. Each child keeps its own visible label and DOM id; the group owns selection state, layout, shared form name, disabled/error state, and accessibility semantics.
+
+```ts
+import { CoarCheckbox, CoarCheckboxGroup } from '@cocoar/vue-ui';
+```
+
+## Array and Object Models
+
+Use `value` as the stable domain key of each checkbox. An array model contains the selected keys. Object mode contains every registered key with an explicit Boolean value. External model changes immediately update the visible checkboxes in both modes.
+
+**Demo — `checkbox-group/demos/CheckboxGroupModels.vue`**
+
+```vue
+<template>
+  <div class="group-models">
+    <CoarFormField label="Array model" hint="The model contains only selected values.">
+      <CoarCheckboxGroup v-model="arrayValue" name="array-permissions">
+        <CoarCheckbox value="read" label="Read" />
+        <CoarCheckbox value="write" label="Write" />
+        <CoarCheckbox value="admin" label="Admin" />
+      </CoarCheckboxGroup>
+    </CoarFormField>
+    <pre>{{ arrayValue }}</pre>
+
+    <CoarFormField
+      label="Object model"
+      hint="Every registered value is represented by an explicit Boolean."
+    >
+      <CoarCheckboxGroup v-model="objectValue" model-type="object" name="object-permissions">
+        <CoarCheckbox value="read" label="Read" />
+        <CoarCheckbox value="write" label="Write" />
+        <CoarCheckbox value="admin" label="Admin" />
+      </CoarCheckboxGroup>
+    </CoarFormField>
+    <pre>{{ objectValue }}</pre>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarCheckbox, CoarCheckboxGroup, CoarFormField } from '@cocoar/vue-ui';
+
+const arrayValue = ref<string[]>(['read']);
+const objectValue = ref<Record<string, boolean>>({
+  read: true,
+  write: false,
+  admin: false,
+});
+</script>
+
+<style scoped>
+.group-models {
+  display: grid;
+  gap: var(--coar-spacing-m);
+}
+
+.group-models pre {
+  margin: 0;
+  padding: var(--coar-spacing-s) var(--coar-spacing-m);
+  border-radius: var(--coar-radius-xs);
+  background: var(--coar-background-neutral-secondary);
+  font-size: 12px;
+}
+</style>
+```
+
+## With Form Field
+
+Wrap the complete group in one `CoarFormField`. The FormField label describes the group; the child labels describe the individual options.
+
+```vue
+<CoarFormField
+  label="Permissions"
+  hint="Select every permission this role should receive."
+>
+  <CoarCheckboxGroup v-model="permissions">
+    <CoarCheckbox value="read" label="Read" />
+    <CoarCheckbox value="write" label="Write" />
+  </CoarCheckboxGroup>
+</CoarFormField>
+```
+
+## API
+
+### CoarCheckboxGroup props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `v-model` | `readonly string[] \| Readonly<Record<string, boolean>>` | `undefined` | Complete group value |
+| `modelType` | `'array' \| 'object'` | inferred, then `'array'` | Output shape, especially useful before a model has a value |
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Child layout |
+| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Size inherited by every child checkbox |
+| `name` | `string` | `undefined` | Native form name shared by all child inputs |
+| `disabled` | `boolean` | `false` | Disables all children |
+| `error` | `boolean` | `false` | Marks the group and all children invalid |
+
+> **Info: Group keys**
+>
+> Inside a group, every `CoarCheckbox` must have a non-empty, unique `value`. `id` remains a DOM/accessibility identifier and is never used as application data.