@cocoar/vue-ui 3.2.0-beta.5 → 3.2.0-beta.7

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

@@ -0,0 +1,290 @@
+<!-- Generated from apps/docs/components/badge.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Badge
+
+Badges draw attention to counts, statuses, or short labels. Attach them to icons, avatars, or buttons to surface information that needs a quick glance -- like unread messages, plan tiers, or live/offline indicators.
+
+```ts
+import { CoarBadge } from '@cocoar/vue-ui';
+```
+
+## Variants
+
+Six semantic variants let you match the badge to its meaning -- use `success` for positive states, `error` for alerts, and so on.
+
+**Demo — `badge/demos/BadgeVariants.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 16px; align-items: center;">
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="42" variant="primary" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">PRIMARY</span>
+    </div>
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="42" variant="secondary" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">SECONDARY</span>
+    </div>
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="42" variant="success" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">SUCCESS</span>
+    </div>
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="42" variant="warning" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">WARNING</span>
+    </div>
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="42" variant="error" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">ERROR</span>
+    </div>
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="42" variant="info" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">INFO</span>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarBadge } from '@cocoar/vue-ui';
+</script>
+```
+
+## Sizes
+
+Five sizes from tiny `xs` (great for inline status) to bold `xl` (ideal for dashboard counters).
+
+**Demo — `badge/demos/BadgeSizes.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 16px; align-items: flex-end;">
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="7" size="xs" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">XS (12px)</span>
+    </div>
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="7" size="s" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">S (16px)</span>
+    </div>
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="7" size="m" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">M (20px)</span>
+    </div>
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="7" size="l" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">L (24px)</span>
+    </div>
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="7" size="xl" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">XL (32px)</span>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarBadge } from '@cocoar/vue-ui';
+</script>
+```
+
+## Text Content
+
+Badges aren't limited to numbers. Use short text labels like "New", "Beta", or "Pro" to tag features and content.
+
+**Demo — `badge/demos/BadgeText.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 12px; align-items: center;">
+    <CoarBadge content="New" variant="info" size="l" />
+    <CoarBadge content="Beta" variant="warning" size="l" />
+    <CoarBadge content="Pro" variant="success" size="l" />
+    <CoarBadge content="Hot" variant="error" size="l" />
+    <CoarBadge content="v2" variant="secondary" size="l" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarBadge } from '@cocoar/vue-ui';
+</script>
+```
+
+## Max Value
+
+Set a `max` to cap large numbers gracefully. Perfect for notification counts where "99+" is more useful than "1,247".
+
+**Demo — `badge/demos/BadgeMax.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 16px; align-items: center;">
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="5" :max="99" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">5 (max 99)</span>
+    </div>
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="99" :max="99" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">99 (max 99)</span>
+    </div>
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="100" :max="99" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">100 → "99+"</span>
+    </div>
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="999" :max="99" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">999 → "99+"</span>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarBadge } from '@cocoar/vue-ui';
+</script>
+```
+
+## Dot Mode
+
+When you only need to signal presence or status without a specific value, `dot` mode provides a minimal, color-coded indicator.
+
+**Demo — `badge/demos/BadgeDot.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 16px; align-items: center;">
+    <div style="display: flex; align-items: center; gap: 6px;">
+      <CoarBadge variant="success" dot />
+      <span style="font-size: 13px; color: #64748b;">Online</span>
+    </div>
+    <div style="display: flex; align-items: center; gap: 6px;">
+      <CoarBadge variant="error" dot />
+      <span style="font-size: 13px; color: #64748b;">Offline</span>
+    </div>
+    <div style="display: flex; align-items: center; gap: 6px;">
+      <CoarBadge variant="warning" dot />
+      <span style="font-size: 13px; color: #64748b;">Away</span>
+    </div>
+    <div style="display: flex; align-items: center; gap: 6px;">
+      <CoarBadge variant="secondary" dot />
+      <span style="font-size: 13px; color: #64748b;">Unknown</span>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarBadge } from '@cocoar/vue-ui';
+</script>
+```
+
+## Pulse Animation
+
+Add a pulse animation to catch the user's eye for time-sensitive updates like new notifications or live events.
+
+**Demo — `badge/demos/BadgePulse.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 16px; align-items: center;">
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="3" variant="error" pulse />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">PULSING BADGE</span>
+    </div>
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge variant="error" dot pulse />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">PULSING DOT</span>
+    </div>
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge content="Live" variant="error" pulse size="l" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">LIVE INDICATOR</span>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarBadge } from '@cocoar/vue-ui';
+</script>
+```
+
+## Bordered
+
+The `bordered` prop adds a ring that prevents the badge from visually merging into its parent. Especially useful when badges sit on top of avatars or colored backgrounds.
+
+**Demo — `badge/demos/BadgeBordered.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 16px; align-items: center;">
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="5" bordered />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">WITH BORDER</span>
+    </div>
+    <div style="display: flex; flex-direction: column; align-items: center; gap: 4px;">
+      <CoarBadge :content="5" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace;">WITHOUT BORDER</span>
+    </div>
+    <div style="position: relative; display: inline-flex; align-items: flex-end; gap: 6px;">
+      <CoarAvatar name="JD" size="l" />
+      <CoarBadge :content="3" variant="error" bordered style="position: absolute; top: -4px; right: -4px;" />
+      <span style="font-size: 10px; color: #64748b; font-family: monospace; align-self: center; margin-left: 6px;">ON AVATAR</span>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarBadge, CoarAvatar } from '@cocoar/vue-ui';
+</script>
+```
+
+## Interactive Demo
+
+See badges in action -- increment and reset a notification counter to observe live updates and max-capping behavior.
+
+**Demo — `badge/demos/BadgeInteractive.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 16px;">
+    <div style="position: relative; display: inline-flex; width: 40px;">
+      <span style="font-size: 24px;">&#x1F514;</span>
+      <CoarBadge :content="notifCount" :max="99" variant="error" :pulse="pulsing" style="position: absolute; top: -4px; right: -4px;" />
+    </div>
+    <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center;">
+      <CoarButton variant="primary" size="s" @click="notifCount++">Add Notification</CoarButton>
+      <CoarButton variant="secondary" size="s" @click="notifCount = 0">Clear All</CoarButton>
+    </div>
+    <label style="display: flex; align-items: center; gap: 6px; font-size: 13px; color: #64748b; cursor: pointer;">
+      <input type="checkbox" v-model="pulsing" />
+      Pulse Animation
+    </label>
+    <p style="margin: 0; font-size: 13px; color: #64748b;">Current count: {{ notifCount }}</p>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarBadge, CoarButton } from '@cocoar/vue-ui';
+
+const notifCount = ref(5);
+const pulsing = ref(true);
+</script>
+```
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `content` | `string \| number` | `''` | Badge content (text or number) |
+| `variant` | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'error' \| 'info'` | `'primary'` | Badge color variant |
+| `size` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl'` | `'m'` | Badge size |
+| `dot` | `boolean` | `false` | Show as a small dot with no content |
+| `max` | `number` | `null` | Cap numeric content (e.g. 100 becomes "99+") |
+| `pulse` | `boolean` | `false` | Add pulse animation |
+| `bordered` | `boolean` | `false` | Add white border ring |
+
+## i18n Keys
+
+These keys can be translated via [`@cocoar/vue-localization`](../foundations/localization/translations.md).
+
+| Key | Default (English) | Used as |
+|-----|-------------------|---------|
+| `coar.ui.badge.notificationIndicator` | `'Notification indicator'` | `aria-label` for dot badges (when no `content` value is set) |

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

@@ -0,0 +1,238 @@
+<!-- Generated from apps/docs/components/breadcrumb.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Breadcrumb
+
+Show users exactly where they are within a page hierarchy and give them a quick path back to any parent level. Breadcrumbs are especially valuable in applications with deep navigation structures, where the sidebar alone does not make the current location obvious.
+
+```ts
+import { CoarBreadcrumb, CoarBreadcrumbItem } from '@cocoar/vue-ui';
+```
+
+## Basic Usage
+
+Pass `to` to render each crumb as a link. The library handles the `<a>` element for you — no need to wrap content in a manual anchor. Mark the last item `active` to indicate the current page; it renders as a non-interactive `<span aria-current="page">` (current page is not a link to itself, per WAI-ARIA convention).
+
+```vue
+<CoarBreadcrumb>
+  <CoarBreadcrumbItem to="/projects" icon="folder">Projects</CoarBreadcrumbItem>
+  <CoarBreadcrumbItem to="/projects/alpha">Alpha</CoarBreadcrumbItem>
+  <CoarBreadcrumbItem to="/projects/alpha/issues">Issues</CoarBreadcrumbItem>
+  <CoarBreadcrumbItem active>#142 Fix date picker</CoarBreadcrumbItem>
+</CoarBreadcrumb>
+```
+
+**Demo — `breadcrumb/demos/BreadcrumbBasic.vue`**
+
+```vue
+<template>
+  <CoarBreadcrumb>
+    <CoarBreadcrumbItem to="/admin" icon="home">Home</CoarBreadcrumbItem>
+    <CoarBreadcrumbItem to="/admin/users" icon="users">Users</CoarBreadcrumbItem>
+    <CoarBreadcrumbItem active>John Doe</CoarBreadcrumbItem>
+  </CoarBreadcrumb>
+</template>
+
+<script setup lang="ts">
+import { CoarBreadcrumb, CoarBreadcrumbItem } from '@cocoar/vue-ui';
+</script>
+```
+
+## Deep Hierarchy
+
+Breadcrumbs scale naturally for deeply nested content. Even a five-level trail remains compact and readable, giving users confidence about their location.
+
+**Demo — `breadcrumb/demos/BreadcrumbDeep.vue`**
+
+```vue
+<template>
+  <CoarBreadcrumb>
+    <CoarBreadcrumbItem to="/shop" icon="home">Home</CoarBreadcrumbItem>
+    <CoarBreadcrumbItem to="/shop/products" icon="folder">Products</CoarBreadcrumbItem>
+    <CoarBreadcrumbItem to="/shop/products/electronics" icon="layout-grid">Electronics</CoarBreadcrumbItem>
+    <CoarBreadcrumbItem to="/shop/products/electronics/laptops" icon="file-text">Laptops</CoarBreadcrumbItem>
+    <CoarBreadcrumbItem active>MacBook Pro 16"</CoarBreadcrumbItem>
+  </CoarBreadcrumb>
+</template>
+
+<script setup lang="ts">
+import { CoarBreadcrumb, CoarBreadcrumbItem } from '@cocoar/vue-ui';
+</script>
+```
+
+## App Navigation
+
+Here are several breadcrumb paths you might encounter in a real application -- from a simple two-level dashboard path to a four-level project issue drill-down.
+
+**Demo — `breadcrumb/demos/BreadcrumbApp.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 16px;">
+    <!-- Simple 2-level dashboard path -->
+    <CoarBreadcrumb>
+      <CoarBreadcrumbItem to="/dashboard" icon="layout-grid">Dashboard</CoarBreadcrumbItem>
+      <CoarBreadcrumbItem active>Overview</CoarBreadcrumbItem>
+    </CoarBreadcrumb>
+
+    <!-- Settings drilldown -->
+    <CoarBreadcrumb>
+      <CoarBreadcrumbItem to="/settings" icon="settings">Settings</CoarBreadcrumbItem>
+      <CoarBreadcrumbItem to="/settings/account" icon="user">Account</CoarBreadcrumbItem>
+      <CoarBreadcrumbItem active>Security</CoarBreadcrumbItem>
+    </CoarBreadcrumb>
+
+    <!-- Project / issue drill-down -->
+    <CoarBreadcrumb>
+      <CoarBreadcrumbItem to="/projects" icon="folder">Projects</CoarBreadcrumbItem>
+      <CoarBreadcrumbItem to="/projects/alpha">Alpha</CoarBreadcrumbItem>
+      <CoarBreadcrumbItem to="/projects/alpha/issues" icon="bookmark">Issues</CoarBreadcrumbItem>
+      <CoarBreadcrumbItem active>#142 Fix date picker</CoarBreadcrumbItem>
+    </CoarBreadcrumb>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarBreadcrumb, CoarBreadcrumbItem } from '@cocoar/vue-ui';
+</script>
+```
+
+## Three render modes
+
+`CoarBreadcrumbItem` picks its render strategy automatically from the props:
+
+| Mode | Trigger | Renders as |
+|------|---------|------------|
+| **Active** | `:active="true"` | `<span aria-current="page">` — non-interactive, current page |
+| **Router-aware link** | `:to="..."` and `vue-router` installed | `<a href>` via `<RouterLink>` (SPA navigation, middle-click new-tab, etc.) |
+| **Plain link** | `:to="..."` without router, or `:href="..."` | `<a href>` with browser-native navigation |
+| **Bare slot (escape hatch)** | none of the above | Whatever the slot contains (custom dropdown, button, plain text…) |
+
+**Active wins over `to`**: you can pass `to` on every crumb (including the last) without filtering — the `active` flag is the single source of truth for "this is the current page". Useful when generating the trail programmatically from `router.matched`.
+
+```vue
+<!-- All four crumbs in one loop, no special-case for the last item -->
+<CoarBreadcrumb>
+  <CoarBreadcrumbItem
+    v-for="(crumb, i) in trail"
+    :key="crumb.path"
+    :to="crumb.path"
+    :icon="crumb.icon"
+    :active="i === trail.length - 1"
+  >
+    {{ crumb.label }}
+  </CoarBreadcrumbItem>
+</CoarBreadcrumb>
+```
+
+## Icons
+
+Pass `icon` for a Lucide-style leading icon, or use the `#icon` slot for custom content (avatar, badge, coloured icon).
+
+```vue
+<CoarBreadcrumb>
+  <!-- Named icon via prop -->
+  <CoarBreadcrumbItem to="/" icon="home">Home</CoarBreadcrumbItem>
+
+  <!-- Custom icon via #icon slot — overrides icon prop -->
+  <CoarBreadcrumbItem to="/teams/alpha">
+    <template #icon>
+      <CoarAvatar :src="team.avatarUrl" size="xs" />
+    </template>
+    {{ team.name }}
+  </CoarBreadcrumbItem>
+
+  <CoarBreadcrumbItem active>Settings</CoarBreadcrumbItem>
+</CoarBreadcrumb>
+```
+
+The icon renders inside the `<a>` / `<span>` so it shares the link's hit-area and styling (hover, focus, disabled states all apply uniformly).
+
+## Custom content (dropdown, picker, etc.)
+
+When `to` / `href` / `active` are all omitted, the item falls back to rendering the bare slot. Use this for inline UI like a project-switcher dropdown embedded in the trail:
+
+```vue
+<CoarBreadcrumb>
+  <CoarBreadcrumbItem to="/projects">Projects</CoarBreadcrumbItem>
+
+  <!-- Bare-slot mode: library renders just the <li>, you control the rest -->
+  <CoarBreadcrumbItem>
+    <CoarSelect
+      v-model="currentProject"
+      :options="availableProjects"
+      size="s"
+      variant="ghost"
+    />
+  </CoarBreadcrumbItem>
+
+  <CoarBreadcrumbItem active>Settings</CoarBreadcrumbItem>
+</CoarBreadcrumb>
+```
+
+This also covers the legacy CSS-only pattern (`<CoarBreadcrumbItem><a href="/x">Foo</a></CoarBreadcrumbItem>`) — consumer-slotted anchors keep working without changes.
+
+## Router Integration
+
+When `to` is set and `vue-router` is registered (`app.use(router)`), the item renders via `<RouterLink>` in custom-slot mode for SPA navigation. Without a router, it falls back to a plain `<a href={String(to)}>`. The detection uses `resolveDynamicComponent('RouterLink')` — no hard dependency on `vue-router`.
+
+> **Info**
+>
+> `vue-router` is declared as an **optional `peerDependenciesMeta`** entry. Install it for SPA routing, omit it for static / `href`-only / bare-slot use.
+
+> **Warning: Object `to` without router**
+>
+> Passing an object literal (`:to="{ name: 'projects' }"`) when no router is installed falls back to `String(to)`, producing `href="[object Object]"` — a broken link. The component logs a DEV-only `console.warn` once per component instance. Pass a string path for the no-router case.
+
+## Sizes
+
+Two sizes:
+
+- **`m`** (default, 14 px) — primary navigation. Sits at the top of a page above the page title.
+- **`s`** (13 px) — secondary chrome. File-explorer paths, settings trails, address-bar style indicators sitting above other content.
+
+```vue
+<CoarBreadcrumb separator="›" size="s" aria-label="File path">
+  <CoarBreadcrumbItem>src</CoarBreadcrumbItem>
+  <CoarBreadcrumbItem>components</CoarBreadcrumbItem>
+  <CoarBreadcrumbItem active>Button.tsx</CoarBreadcrumbItem>
+</CoarBreadcrumb>
+```
+
+Pass items without `to` / `href` to render as plain text (the slot-only escape hatch) — useful for path indicators where the segments aren't independently navigable.
+
+## Accessibility
+
+### Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Move between breadcrumb links |
+| `Enter` | Activate the focused link |
+| `Shift + Tab` | Move focus backward |
+
+## API
+
+### CoarBreadcrumb Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `separator` | `string` | `'/'` | Separator character between items |
+| `ariaLabel` | `string` | `'Breadcrumb'` | Accessible label for the nav landmark |
+| `size` | `'m' \| 's'` | `'m'` | Visual density. `'s'` (13 px) for secondary chrome — file-explorer paths, settings trails, etc. Drives only the font-size token; spacing + colors stay identical to `'m'` so both sizes look consistent in the same UI. |
+
+### CoarBreadcrumbItem Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `to` | `RouteLocationRaw \| string` | `undefined` | Vue Router target. Library renders an `<a>` (via `<RouterLink>` if available, plain `<a>` otherwise). Ignored when `active` is true. |
+| `href` | `string` | `undefined` | External URL. Used when `to` is not set. |
+| `icon` | `string` | `undefined` | Leading icon name. Rendered inside the link / active span. |
+| `active` | `boolean` | `false` | Mark as the current/active page — renders as `<span aria-current="page">`, NOT a link to itself. Takes precedence over `to` / `href`. |
+| `disabled` | `boolean` | `false` | Disabled link (only meaningful in link modes): `aria-disabled`, `tabindex=-1`, navigation suppressed. |
+
+### CoarBreadcrumbItem Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Item content — text for the common case, or any custom content (dropdown, button, etc.) in bare-slot mode |
+| `icon` | Custom icon content. Overrides the `icon` prop when both are provided. Use for avatars, badges, coloured icons. |