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

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

@@ -0,0 +1,172 @@
+<!-- Generated from apps/docs/components/mermaid.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Mermaid Diagram (Preview)
+
+A standalone [Mermaid](https://mermaid.js.org/) diagram component for Vue 3.
+`<CoarMermaidDiagram :code>` renders a diagram from a Mermaid source **string** —
+Cocoar-themed, lazy-loaded, with opt-in zoom/pan.
+
+It knows **nothing about markdown** or any embedding layer — feed it a diagram
+source and it renders. To turn ` ```mermaid ` fenced code blocks inside
+`<CoarMarkdown>` into diagrams, use the thin adapter on the
+[**Markdown Diagrams**](./markdown-diagrams.md) page (it registers this
+same component as a fence renderer).
+
+> **Info: Separate package**
+>
+```bash
+pnpm add @cocoar/vue-mermaid
+```
+> `vue` is the only peer dependency. Mermaid is a regular dependency, imported
+> **lazily** on first render (its own chunk). Import the stylesheet once:
+>
+```ts
+import '@cocoar/vue-mermaid/styles';
+```
+
+**Demo — `mermaid/demos/MermaidBasic.vue`**
+
+```vue
+<script setup lang="ts">
+/**
+ * Standalone `<CoarMermaidDiagram>` — no markdown involved. Edit the source on
+ * the left; the component re-renders on the right. `zoomable` adds the
+ * +/−/⤢ controls, Ctrl/⌘+wheel zoom and drag-to-pan.
+ */
+import { ref } from 'vue';
+import { CoarMermaidDiagram } from '@cocoar/vue-mermaid';
+
+const code = ref(`sequenceDiagram
+  autonumber
+  participant C as Client
+  participant S as Server
+  C->>S: Request
+  alt cache hit
+    S-->>C: 200 (cached)
+  else miss
+    S->>S: compute
+    S-->>C: 200
+  end`);
+</script>
+
+<template>
+  <ClientOnly>
+    <div class="mmd-demo">
+      <textarea v-model="code" class="mmd-demo__code" spellcheck="false" />
+      <div class="mmd-demo__out">
+        <CoarMermaidDiagram :code="code" zoomable />
+      </div>
+    </div>
+  </ClientOnly>
+</template>
+
+<style scoped>
+.mmd-demo {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 12px;
+}
+@media (max-width: 720px) {
+  .mmd-demo { grid-template-columns: 1fr; }
+}
+.mmd-demo__code {
+  min-height: 220px;
+  resize: vertical;
+  padding: 12px;
+  border: 1px solid var(--coar-border-neutral, #e2e2e2);
+  border-radius: var(--coar-radius-xl, 12px);
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 12px;
+  line-height: 1.5;
+}
+.mmd-demo__out {
+  min-width: 0;
+}
+</style>
+```
+
+## Usage
+
+```vue
+<template>
+  <CoarMermaidDiagram :code="code" zoomable />
+</template>
+
+<script setup lang="ts">
+import { CoarMermaidDiagram } from '@cocoar/vue-mermaid';
+
+const code = `
+flowchart LR
+  A[Start] --> B{Choice}
+  B -->|yes| C[Do it]
+  B -->|no| D[Skip]
+`;
+</script>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `code` | `string` | — | The Mermaid diagram source. |
+| `language` | `string` | `'mermaid'` | Info-string label; handy when one component is reused for several fence keys. |
+| `zoomable` | `boolean` | `false` | Enable the zoom/pan viewport. |
+
+## How it works
+
+- **Rendering is client-only** — Mermaid needs a DOM to measure and lay out, so
+  nothing renders on the server or before mount. (Wrap it in `<ClientOnly>` in an
+  SSR context like VitePress.)
+- **Lazy** — Mermaid is dynamically imported on the first diagram, so pages
+  without one never pay for it.
+- **Cocoar-themed** — design tokens map onto Mermaid's `themeVariables`. Cocoar
+  color tokens are `oklch(...)`, which Mermaid's parser can't read, so they're
+  normalized to sRGB first (via a 1×1 canvas).
+- **Font-safe** — rendering waits for `document.fonts.ready`, so labels aren't
+  clipped by boxes that were measured before the web font loaded.
+- **Security** — Mermaid runs with `securityLevel: 'strict'`; author diagram text
+  is treated as untrusted (HTML in labels is sanitized).
+- **Invalid source degrades** to an error box that still shows the raw source —
+  it never throws up to the app.
+
+> **Tip: Many diagrams on one page**
+>
+> Renders are serialized internally — `mermaid.render` shares global state and
+> isn't concurrency-safe, so several diagrams mounting at once would otherwise
+> corrupt each other.
+
+## Zoom & pan
+
+With `zoomable`, the diagram sits in a fixed-height viewport with:
+
+- **+ / − / ⤢ buttons** (top-right) — the primary, touch-friendly zoom;
+- **Ctrl / ⌘ + wheel** — zoom toward the cursor;
+- **drag** — pan (mouse / pen);
+- **double-click** — reset.
+
+Plain mouse-wheel scrolling is deliberately **not** captured, so a diagram never
+traps the page scroll. On touch, one-finger scrolling still scrolls the page
+(zoom via the buttons). Set the viewport height with the `--coar-mermaid-height`
+CSS variable (default `420px`):
+
+```css
+.my-diagram { --coar-mermaid-height: 600px; }
+```
+
+## Theming
+
+Theming is applied automatically from the ambient Cocoar tokens. The mapping is
+exported as pure functions if you need to build your own Mermaid config:
+
+| Export | Description |
+|---|---|
+| `buildMermaidThemeVariables(getToken, resolveColor?)` | Cocoar token getter → Mermaid `themeVariables`. |
+| `readCssTokens(el?)` | `getComputedStyle`-backed token getter. |
+| `makeCssColorResolver()` | Canvas-backed CSS-color → sRGB resolver (handles `oklch(...)`). |
+
+## In markdown
+
+To render diagrams from ` ```mermaid ` fences inside `<CoarMarkdown>`, don't wire
+this component up by hand — install `@cocoar/vue-markdown-mermaid` and pass its
+`mermaidFenceRenderers` to the viewer's `fenceRenderers` prop. See
+[**Markdown Diagrams**](./markdown-diagrams.md).

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

@@ -0,0 +1,147 @@
+<!-- Generated from apps/docs/components/navbar.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Navbar
+
+A top-level navigation bar that anchors your application layout. It provides three flexible content slots -- start, center, and end -- so you can place a logo, navigation links, and user actions exactly where they belong. By default it uses a subtle shadow for visual elevation; switch to `bordered` for a flat look with a bottom border instead.
+
+```ts
+import { CoarNavbar } from '@cocoar/vue-ui';
+```
+
+## Basic Usage (Elevated)
+
+The default navbar casts a light shadow to separate it from the page content below. Use all three slots for a complete navigation layout: brand on the left, links in the center, and call-to-action buttons on the right.
+
+**Demo — `navbar/demos/NavbarBasic.vue`**
+
+```vue
+<template>
+  <div style="border: 1px solid var(--coar-border-neutral-secondary); border-radius: 8px; overflow: hidden;">
+    <CoarNavbar>
+      <template #start>
+        <strong style="font-size: var(--coar-body-base-size)">MyApp</strong>
+      </template>
+      <template #center>
+        <nav style="display: flex; gap: 16px;">
+          <a href="javascript:void(0)" style="color: var(--coar-text-neutral-secondary); text-decoration: none; font-size: var(--coar-body-small-base-size);">Home</a>
+          <a href="javascript:void(0)" style="color: var(--coar-text-neutral-secondary); text-decoration: none; font-size: var(--coar-body-small-base-size);">Features</a>
+          <a href="javascript:void(0)" style="color: var(--coar-text-neutral-secondary); text-decoration: none; font-size: var(--coar-body-small-base-size);">Pricing</a>
+          <a href="javascript:void(0)" style="color: var(--coar-text-neutral-secondary); text-decoration: none; font-size: var(--coar-body-small-base-size);">Docs</a>
+        </nav>
+      </template>
+      <template #end>
+        <CoarButton variant="ghost" size="s">Sign In</CoarButton>
+        <CoarButton variant="primary" size="s">Get Started</CoarButton>
+      </template>
+    </CoarNavbar>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarNavbar, CoarButton } from '@cocoar/vue-ui';
+</script>
+```
+
+## App Navbar with User Avatar
+
+A common pattern for authenticated applications. The start slot holds the brand mark, the center slot contains primary navigation, and the end slot pairs notification controls with a user avatar.
+
+**Demo — `navbar/demos/NavbarAvatar.vue`**
+
+```vue
+<template>
+  <div style="border: 1px solid var(--coar-border-neutral-secondary); border-radius: 8px; overflow: hidden;">
+    <CoarNavbar>
+      <template #start>
+        <div style="display: flex; align-items: center; gap: 6px;">
+          <div style="width: 28px; height: 28px; background: var(--coar-background-accent-primary); color: white; border-radius: 6px; display: flex; align-items: center; justify-content: center; font-weight: bold; font-size: 14px;">C</div>
+          <strong style="font-size: var(--coar-body-base-size)">cocoar</strong>
+        </div>
+      </template>
+      <template #center>
+        <nav style="display: flex; gap: 16px;">
+          <a href="javascript:void(0)" style="color: var(--coar-text-neutral-secondary); text-decoration: none; font-size: var(--coar-body-small-base-size);">Dashboard</a>
+          <a href="javascript:void(0)" style="color: var(--coar-text-neutral-secondary); text-decoration: none; font-size: var(--coar-body-small-base-size);">Projects</a>
+          <a href="javascript:void(0)" style="color: var(--coar-text-neutral-secondary); text-decoration: none; font-size: var(--coar-body-small-base-size);">Team</a>
+          <a href="javascript:void(0)" style="color: var(--coar-text-neutral-secondary); text-decoration: none; font-size: var(--coar-body-small-base-size);">Reports</a>
+        </nav>
+      </template>
+      <template #end>
+        <CoarButton variant="ghost" icon-start="triangle-alert" size="s" aria-label="Notifications" />
+        <CoarAvatar name="John Doe" size="s" />
+      </template>
+    </CoarNavbar>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarNavbar, CoarButton, CoarAvatar } from '@cocoar/vue-ui';
+</script>
+```
+
+## Logo Only (Start Slot)
+
+Not every navbar needs all three slots. For landing pages or simple tools, use just the start and end slots for a clean, minimal header.
+
+**Demo — `navbar/demos/NavbarMinimal.vue`**
+
+```vue
+<template>
+  <div style="border: 1px solid var(--coar-border-neutral-secondary); border-radius: 8px; overflow: hidden;">
+    <CoarNavbar>
+      <template #start>
+        <strong>Brand</strong>
+      </template>
+      <template #end>
+        <CoarButton variant="primary" size="s">Open App</CoarButton>
+      </template>
+    </CoarNavbar>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarNavbar, CoarButton } from '@cocoar/vue-ui';
+</script>
+```
+
+## Bordered (No Shadow)
+
+Prefer a flat aesthetic? The `bordered` prop swaps the drop shadow for a thin bottom border, giving the navbar a lighter visual weight that works well in dense dashboards.
+
+**Demo — `navbar/demos/NavbarBordered.vue`**
+
+```vue
+<template>
+  <div style="border: 1px solid var(--coar-border-neutral-secondary); border-radius: 8px; overflow: hidden;">
+    <CoarNavbar bordered>
+      <template #start>
+        <strong>App</strong>
+      </template>
+      <template #end>
+        <CoarButton variant="ghost" size="s">Menu</CoarButton>
+      </template>
+    </CoarNavbar>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarNavbar, CoarButton } from '@cocoar/vue-ui';
+</script>
+```
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `elevated` | `boolean` | `true` | Show subtle box-shadow elevation |
+| `bordered` | `boolean` | `false` | Show bottom border instead of shadow |
+
+### Slots
+
+| Slot | Description |
+|------|-------------|
+| `#start` | Left-aligned content (logo, brand name) |
+| `#center` | Centered content (navigation links) |
+| `#end` | Right-aligned content (actions, user menu) |

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

@@ -0,0 +1,96 @@
+<!-- Generated from apps/docs/components/note.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Note
+
+Notes call attention to supplementary information without interrupting the main content flow. Use them for tips, requirements, deprecation warnings, or any contextual message that readers should notice but shouldn't be blocked by. A colored left border and tinted background create just enough contrast to stand out.
+
+```ts
+import { CoarNote } from '@cocoar/vue-ui';
+```
+
+## Color Variants
+
+Six semantic variants communicate intent at a glance: `info` for tips, `success` for confirmations, `warning` for cautions, `error` for critical issues, `neutral` for general remarks, and `accent` for brand-specific callouts.
+
+**Demo — `note/demos/NoteVariants.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <CoarNote variant="info"><strong>Info:</strong> Informational message for guidance or context.</CoarNote>
+    <CoarNote variant="success"><strong>Success:</strong> Action completed successfully.</CoarNote>
+    <CoarNote variant="warning"><strong>Warning:</strong> Pay attention, potential issue ahead.</CoarNote>
+    <CoarNote variant="error"><strong>Error:</strong> Something went wrong. Action required.</CoarNote>
+    <CoarNote variant="neutral">Neutral note for general content without semantic meaning.</CoarNote>
+    <CoarNote variant="accent">Accent-colored note for brand-specific or promotional callouts.</CoarNote>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarNote } from '@cocoar/vue-ui';
+</script>
+```
+
+## Padding Sizes
+
+Use `m` (the default) for standalone callouts, `s` inside compact layouts like cards or sidebars, and `l` for more prominent call-to-action notes.
+
+**Demo — `note/demos/NotePadding.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <CoarNote variant="info" padding="s">Small padding — compact notes in tight spaces.</CoarNote>
+    <CoarNote variant="info" padding="m">Medium padding (default) — standard note spacing.</CoarNote>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarNote } from '@cocoar/vue-ui';
+</script>
+```
+
+## Rich Content
+
+The default slot accepts any HTML, so you can include links, bold text, inline code, and multi-line content without limitations.
+
+**Demo — `note/demos/NoteRichContent.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <CoarNote variant="info">
+      <strong>Did you know?</strong> The Temporal API is the modern JavaScript standard for date/time handling.
+      It provides <code>PlainDate</code>, <code>PlainDateTime</code>, and <code>ZonedDateTime</code> types
+      for precise date and time manipulation without timezone ambiguity.
+    </CoarNote>
+    <CoarNote variant="warning">
+      <strong>Breaking Change in v2.0:</strong> The <code>value</code> prop has been renamed to <code>modelValue</code>
+      to align with Vue 3's composition API conventions. Update your code before upgrading.
+    </CoarNote>
+    <CoarNote variant="success">
+      <strong>Migration Complete:</strong> Your project has been successfully upgraded to the latest version.
+      All components have been updated and tests are passing.
+    </CoarNote>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarNote } from '@cocoar/vue-ui';
+</script>
+```
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'error' \| 'accent'` | `'neutral'` | Note color variant |
+| `padding` | `'s' \| 'm' \| 'l'` | `'m'` | Internal padding size |
+
+### Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Note content (supports rich HTML) |

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

@@ -0,0 +1,131 @@
+<!-- Generated from apps/docs/components/notice.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Notice
+
+Notices communicate short, timely status information. They are deliberately more compact than [Notes](./note.md): use a Notice for a sentence near a control or directly below an application header, and a Note for rich supporting content inside a page.
+
+```ts
+import { CoarNotice } from '@cocoar/vue-ui';
+```
+
+## Variants
+
+Every variant has its own semantic color and default icon. The icon can be replaced with the `icon` prop.
+
+**Demo — `notice/demos/NoticeVariants.vue`**
+
+```vue
+<script setup lang="ts">
+import { CoarNotice } from '@cocoar/vue-ui';
+</script>
+
+<template>
+  <div class="notice-stack">
+    <CoarNotice variant="info" label="Information">A newer version is available.</CoarNotice>
+    <CoarNotice variant="success" label="Saved">All changes were stored successfully.</CoarNotice>
+    <CoarNotice variant="warning" label="Temporary storage">Uploaded files are removed on restart.</CoarNotice>
+    <CoarNotice variant="error" label="Connection failed">The service could not be reached.</CoarNotice>
+    <CoarNotice variant="neutral">Scheduled maintenance starts tonight at 22:00.</CoarNotice>
+    <CoarNotice variant="accent" label="New">Explore the updated workspace experience.</CoarNotice>
+  </div>
+</template>
+
+<style scoped>
+.notice-stack {
+  display: grid;
+  gap: 8px;
+}
+</style>
+```
+
+## Banner
+
+`placement="banner"` removes the radius and side borders so the Notice can sit flush below a header. The component is not sticky by itself—the surrounding application layout decides where it stays.
+
+**Demo — `notice/demos/NoticeBanner.vue`**
+
+```vue
+<script setup lang="ts">
+import { CoarLink, CoarNotice } from '@cocoar/vue-ui';
+</script>
+
+<template>
+  <div class="banner-frame">
+    <div class="fake-header">Application header</div>
+    <CoarNotice placement="banner" variant="warning" label="Temporary storage">
+      Uploaded files are retained until the next restart.
+      <template #cta>
+        <CoarLink size="s">Configure storage →</CoarLink>
+      </template>
+    </CoarNotice>
+    <div class="fake-content">Application content</div>
+  </div>
+</template>
+
+<style scoped>
+.banner-frame {
+  overflow: hidden;
+  border: 1px solid var(--coar-border-neutral-secondary);
+  border-radius: var(--coar-radius-s);
+}
+
+.fake-header {
+  padding: 14px 24px;
+  background: var(--coar-background-semantic-info-bold);
+  color: var(--coar-text-on-bold);
+  font-weight: 600;
+}
+
+.fake-content {
+  min-height: 92px;
+  padding: 24px;
+  color: var(--coar-text-neutral-secondary);
+}
+</style>
+```
+
+Banner text always wraps. For compact inline use, `truncate` can deliberately keep a message on one line.
+
+## Details and actions
+
+Keep the primary message short. Optional long-form information belongs in the `details` slot and opens in a popover. Put links or buttons in the `cta` slot; the Notice itself is intentionally not clickable.
+
+**Demo — `notice/demos/NoticeActions.vue`**
+
+```vue
+<script setup lang="ts">
+import { CoarLink, CoarNotice } from '@cocoar/vue-ui';
+</script>
+
+<template>
+  <CoarNotice variant="info" label="Indexing">
+    Three files are still being processed.
+    <template #details>
+      Search results may be incomplete until all uploaded files have been indexed.
+    </template>
+    <template #cta>
+      <CoarLink size="s">View files</CoarLink>
+    </template>
+  </CoarNotice>
+</template>
+```
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'error' \| 'accent'` | `'info'` | Semantic color and default icon |
+| `placement` | `'inline' \| 'banner'` | `'inline'` | Bordered callout or edge-to-edge banner |
+| `label` | `string` | — | Bold lead-in; a colon is added |
+| `icon` | `string` | variant default | Custom icon name |
+| `truncate` | `boolean` | `false` | Single-line inline content; ignored for banners |
+
+### Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Short primary message |
+| `details` | Long-form content shown in a popover |
+| `cta` | Link or button aligned to the right |