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

package/skills/cocoar-vue-ui/references/components/map/index.md

@@ -0,0 +1,351 @@
+<!-- Generated from apps/docs/components/map/index.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Map (Preview)
+
+An interactive [Leaflet](https://leafletjs.com/) map for Vue 3. `<CoarMap>` is
+**standalone and data-driven**: you feed it resolved `MapData` + `MapConfig` and
+it renders pins, a route, popups and an optional legend. It has **no dependency
+on — and no knowledge of — markdown or any embedding layer**; resolving a source
+(a store, an API, a `:::map{id}` directive) into `MapData` is the consumer's job.
+
+> **Info: Separate package**
+>
+```bash
+pnpm add @cocoar/vue-map
+```
+> `leaflet` is a regular dependency, imported **lazily** at runtime — `vue` is the
+> only peer. Import the component stylesheet once (it carries the pin, legend and
+> layout styles); Leaflet's own CSS is still loaded lazily by the component:
+>
+```ts
+import '@cocoar/vue-map/styles';
+```
+
+> **Tip: Authoring maps?**
+>
+> This page is the **viewer**. To place, move and edit points visually, see
+> [**CoarMapEditor**](./editor.md) — the write counterpart, same data.
+
+**Demo — `map/demos/MapBasic.vue`**
+
+```vue
+<script setup lang="ts">
+/**
+ * `<CoarMap>` with a consumer-built point list wired to it via the interactive
+ * bridge — no markdown anywhere. The list/layout is the consumer's job (built
+ * here from the exported `fallbackEntries` helper); the map provides the hooks
+ * (`v-model:selected`, `focusPoint`, `highlightPoint`).
+ */
+import { computed, ref } from 'vue';
+import {
+  CoarMap,
+  fallbackEntries,
+  type MapConfig,
+  type MapData,
+} from '@cocoar/vue-map';
+
+const config: MapConfig = {
+  defaultBasemap: 'voyager',
+  basemaps: [
+    {
+      id: 'voyager',
+      url: 'https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}{r}.png',
+      subdomains: 'abcd',
+      attribution: '© OpenStreetMap, © CARTO',
+      maxZoom: 20,
+    },
+  ],
+  categories: [
+    { id: 'sight', label: 'Sights', emoji: '🏛️', color: '#a855f7' },
+    { id: 'food', label: 'Food', emoji: '🍽️', color: '#f97316' },
+    { id: 'nature', label: 'Nature', emoji: '🌲', color: '#16a34a' },
+  ],
+};
+
+const data: MapData = {
+  type: 'route',
+  caption: 'A sample London walk.',
+  points: [
+    { lat: 51.4995, lng: -0.1248, kind: 'stop', label: 'Westminster', note: 'Start', category: 'sight' },
+    { lat: 51.5076, lng: -0.118, kind: 'shape', label: 'Thames bend' },
+    { lat: 51.5129, lng: -0.1243, kind: 'stop', label: 'Dishoom', note: 'Lunch stop', category: 'food', icon: '🥘' },
+    { lat: 51.5194, lng: -0.127, kind: 'stop', label: 'British Museum', category: 'sight' },
+    { lat: 51.5074, lng: -0.1657, kind: 'stop', label: 'Hyde Park', category: 'nature' },
+  ],
+};
+
+const entries = computed(() => fallbackEntries(data, config));
+const selected = ref<number | null>(null);
+const showLegend = ref(true);
+const mapRef = ref<{
+  focusPoint: (index: number) => void;
+  highlightPoint: (index: number | null) => void;
+} | null>(null);
+</script>
+
+<template>
+  <ClientOnly>
+    <label class="map-d__toggle"><input v-model="showLegend" type="checkbox" /> show legend</label>
+    <div class="map-d">
+      <div class="map-d__map">
+        <CoarMap
+          ref="mapRef"
+          v-model:selected="selected"
+          :data="data"
+          :config="config"
+          :show-legend="showLegend"
+          @point-click="(e) => (selected = e.index)"
+        />
+      </div>
+      <aside class="map-d__list">
+        <div class="map-d__list-title">Points</div>
+        <ul>
+          <li
+            v-for="entry in entries"
+            :key="entry.index"
+            :class="{ 'is-active': selected === entry.index }"
+            @click="mapRef?.focusPoint(entry.index)"
+            @mouseenter="mapRef?.highlightPoint(entry.index)"
+            @mouseleave="mapRef?.highlightPoint(null)"
+          >
+            <span>{{ entry.emoji }}</span> {{ entry.label || '(unnamed)' }}
+          </li>
+        </ul>
+      </aside>
+    </div>
+  </ClientOnly>
+</template>
+
+<style scoped>
+.map-d__toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  margin-bottom: 8px;
+  font-size: 13px;
+  font-weight: 600;
+}
+.map-d {
+  display: flex;
+  gap: 12px;
+  align-items: stretch;
+}
+.map-d__map {
+  flex: 1;
+  min-width: 0;
+  --coar-map-height: 360px;
+}
+.map-d__list {
+  width: 200px;
+  flex-shrink: 0;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 10px;
+  overflow: hidden;
+}
+.map-d__list-title {
+  padding: 8px 12px;
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--vp-c-text-2);
+  border-bottom: 1px solid var(--vp-c-divider);
+}
+.map-d__list ul {
+  margin: 0;
+  padding: 4px;
+  list-style: none;
+  overflow: auto;
+  max-height: 320px;
+}
+.map-d__list li {
+  padding: 6px 8px;
+  border-radius: 6px;
+  font-size: 13px;
+  cursor: pointer;
+}
+.map-d__list li:hover {
+  background: var(--vp-c-bg-soft);
+}
+.map-d__list li.is-active {
+  background: var(--vp-c-brand-soft);
+}
+@media (max-width: 720px) {
+  .map-d { flex-direction: column; }
+  .map-d__list { width: auto; }
+}
+</style>
+```
+
+The list on the right is **not** part of `<CoarMap>` — it's built by the demo from
+the exported `fallbackEntries` helper and wired to the map via the
+[interactive bridge](#interactive-bridge). Click a row to fly to it, hover to
+highlight, click a marker to select it back.
+
+## Quick start
+
+```vue
+<template>
+  <CoarMap :data="data" :config="config" />
+</template>
+
+<script setup lang="ts">
+import { CoarMap, type MapData, type MapConfig } from '@cocoar/vue-map';
+
+const config: MapConfig = {
+  defaultBasemap: 'osm',
+  basemaps: [
+    { id: 'osm', url: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', attribution: '© OpenStreetMap' },
+  ],
+  categories: [
+    { id: 'sight', label: 'Sights', emoji: '🏛️', color: '#a855f7' },
+  ],
+};
+
+const data: MapData = {
+  type: 'route',
+  points: [
+    { lat: 51.4995, lng: -0.1248, kind: 'stop', label: 'Westminster', category: 'sight' },
+    { lat: 51.5194, lng: -0.1270, kind: 'stop', label: 'British Museum', category: 'sight' },
+  ],
+};
+</script>
+```
+
+## Data
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | `'single' \| 'multi' \| 'route'` | `route` draws a polyline through all points; others just place markers. |
+| `caption` | `string?` | Shown under the map. |
+| `basemap` | `string?` | Basemap id; falls back to `config.defaultBasemap`. |
+| `viewport` | `{ centerLat, centerLng, zoom }?` | Fixed view; when omitted the map **auto-fits** all points. |
+| `points` | `MapPoint[]` | The markers + route vertices. |
+
+A **`MapPoint`**:
+
+| Field | Type | Description |
+|---|---|---|
+| `lat` / `lng` | `number` | Position. |
+| `kind` | `'stop' \| 'shape'` | `stop` = a marker; `shape` = a route/line vertex. |
+| `label` | `string?` | Hover tooltip + popup title. |
+| `note` | `string?` | Extra line in the click popup. |
+| `category` | `string?` | _(stop only)_ category id → marker color + legend. |
+| `icon` | `string?` | _(stop only)_ emoji override (else the category's emoji). |
+
+Markers: a **stop** is a category-colored pin (emoji = `icon` or the category's);
+a **named shape** point is a small dot; an **unnamed shape** point draws no
+marker (it only contributes to the route line + auto-fit bounds).
+
+## Config
+
+| Field | Type | Description |
+|---|---|---|
+| `defaultBasemap` | `string` | Basemap id used when a map specifies none. |
+| `basemaps` | `MapBasemap[]` | Tile sources (`{ id, url, subdomains?, attribution?, maxZoom? }`). |
+| `categories` | `MapCategory[]?` | `{ id, label, emoji?, color }` — drives stop colors + the legend. |
+
+Pass it per-instance via `config`, or app-wide:
+
+```ts
+import { COAR_MAP_CONFIG_KEY } from '@cocoar/vue-map';
+app.provide(COAR_MAP_CONFIG_KEY, config); // a per-instance `config` prop still wins
+```
+
+> **Info: Google basemaps**
+>
+> Out of scope for now. A basemap flagged `google: true` is **skipped** in favour
+> of the default. The `google` / `googleType` fields are kept on `MapBasemap` so a
+> registry can carry them for a future release.
+
+## Interactive bridge
+
+The component renders the map; **the list/layout around it is the consumer's
+job** (the data is yours, and `fallbackEntries(data, config)` gives ready-made
+rows — each carrying its `index` into `data.points`). What a consumer *can't* do
+alone is drive the map from outside, so `<CoarMap>` exposes exactly that:
+
+| API | Direction | Description |
+|---|---|---|
+| `v-model:selected` | both | Selected point index. Set it to ring a marker; reads back when a marker is clicked. |
+| `@point-click` | map → out | `{ point, index }` when a marker is clicked. |
+| `focusPoint(index)` | out → map | Pan to the point, open its popup, select it. _(exposed method)_ |
+| `highlightPoint(index \| null)` | out → map | Transient hover emphasis on a marker. _(exposed method)_ |
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+import { CoarMap, fallbackEntries } from '@cocoar/vue-map';
+
+const mapRef = ref<InstanceType<typeof CoarMap>>();
+const selected = ref<number | null>(null);
+const rows = computed(() => fallbackEntries(data, config));
+</script>
+
+<template>
+  <CoarMap ref="mapRef" v-model:selected="selected" :data="data" :config="config" />
+  <ul>
+    <li
+      v-for="row in rows"
+      :key="row.index"
+      :class="{ active: selected === row.index }"
+      @click="mapRef?.focusPoint(row.index)"
+      @mouseenter="mapRef?.highlightPoint(row.index)"
+      @mouseleave="mapRef?.highlightPoint(null)"
+    >{{ row.emoji }} {{ row.label }}</li>
+  </ul>
+</template>
+```
+
+## Legend & caption
+
+The legend is **off by default**. Set `show-legend` to enable it — it then
+appears when **≥ 2 categories** are present among the stops, listing each
+category's swatch + label. The `caption` from `MapData` renders below the map.
+
+```vue
+<CoarMap :data="data" :config="config" show-legend />
+```
+
+## Lazy loading & fallback
+
+Leaflet (JS **and** CSS) is imported in `onMounted`, so it loads only on pages
+that actually render a map (your bundler code-splits it into its own chunk).
+Until the map hydrates — and if Leaflet ever fails to load, or with JS off — a
+crawlable `<ol>` of the named points is shown and then hidden once the map is
+live. The map container's height is `--coar-map-height` (default `360px`).
+
+## Security
+
+Point text (`label`, `note`, `icon`) is treated as untrusted: popups are built
+from DOM **text nodes** (never an HTML string), tooltips and the marker emoji are
+HTML-escaped, and a category color is guarded before it reaches an inline style.
+A hostile label can't break out into markup.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `MapData` | _required_ | The resolved map data. |
+| `config` | `MapConfig` | _provide_ | Basemaps + categories. Falls back to `COAR_MAP_CONFIG_KEY`. |
+| `selected` | `number \| null` | `null` | Selected point index (`v-model:selected`). |
+| `showLegend` | `boolean` | `false` | Show the legend (then needs ≥ 2 categories). |
+
+## Using it as a markdown embed
+
+`<CoarMap>` and the [markdown custom-embed](../markdown-embeds.md) system are
+fully independent. To show a map inside markdown, a consumer registers a small
+wrapper that resolves the directive's id into `MapData` and renders `<CoarMap>`:
+
+```ts
+// the wrapper is the CONSUMER's — it bridges markdown ↔ map; neither package
+// depends on the other.
+const embeds = {
+  map: {
+    viewer: defineComponent({
+      props: { id: { type: String, required: true } },
+      setup: (props) => () => h(CoarMap, { data: resolveMap(props.id), config }),
+    }),
+  },
+};
+```

package/skills/cocoar-vue-ui/references/components/markdown-diagrams.md

@@ -0,0 +1,210 @@
+<!-- Generated from apps/docs/components/markdown-diagrams.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Diagrams (Preview)
+
+Render diagrams inside markdown from a fenced code block — <code>```mermaid</code>
+— using [`@cocoar/vue-markdown-mermaid`](https://www.npmjs.com/package/@cocoar/vue-markdown-mermaid).
+The diagram source lives in the markdown as a normal code fence, so it
+round-trips losslessly and **degrades to a readable code block** anywhere the
+renderer isn't installed (strict CommonMark, a viewer-only build, a native mobile
+renderer).
+
+> **Info: Two mechanisms, two shapes**
+>
+> A **fenced code block** is for content whose *body is authored text in a DSL* —
+> diagrams, code. A [custom embed](./markdown-embeds.md) (`:::key{props}`) is
+> for a *single-line reference + a few props* rendered by a rich, visually-edited
+> component (e.g. a map). Diagrams belong in a fence; the map belongs in an embed.
+
+> **Tip: Two packages**
+>
+> The renderer lives in the standalone, markdown-free **`@cocoar/vue-mermaid`**
+> ([`<CoarMermaidDiagram :code>`](./mermaid.md) — usable anywhere).
+> **`@cocoar/vue-markdown-mermaid`** is the thin adapter that registers it as a
+> fence renderer. Rendering a diagram **outside** markdown? See the
+> [**Mermaid Diagram**](./mermaid.md) page.
+
+**Demo — `markdown-diagrams/demos/MarkdownDiagrams.vue`**
+
+````vue
+<script setup lang="ts">
+/**
+ * Live demo of the opt-in Mermaid fence renderer. The viewer is handed
+ * `mermaidFenceRenderers`, so the ` ```mermaid ` fenced code block in the source
+ * renders as a diagram. The plain ` ```ts ` block stays a normal code block — an
+ * unregistered fence language is untouched.
+ */
+import { computed, ref } from 'vue';
+import { CoarMarkdown } from '@cocoar/vue-markdown';
+import { mermaidFenceRenderers } from '@cocoar/vue-markdown-mermaid';
+import { parse } from '@cocoar/vue-markdown-core';
+
+// Note: assembled from parts so the ```mermaid fences here are never seen by the
+// docs' own vitepress-plugin-mermaid (which only scans the page's own markdown).
+const source = [
+  '# Release flow',
+  '',
+  'A `mermaid` fenced block renders as a diagram:',
+  '',
+  '```mermaid',
+  'flowchart LR',
+  '  A[Author writes markdown] --> B{Renderer registered?}',
+  '  B -->|yes| C[Diagram]',
+  '  B -->|no| D[Readable code block]',
+  '```',
+  '',
+  'Other code blocks are untouched:',
+  '',
+  '```ts',
+  'const shipped: boolean = true;',
+  '```',
+].join('\n');
+
+const doc = computed(() => parse(source));
+</script>
+
+<template>
+  <ClientOnly>
+    <div class="mmd-demo">
+      <CoarMarkdown :doc="doc" :fence-renderers="mermaidFenceRenderers" />
+    </div>
+  </ClientOnly>
+</template>
+
+<style scoped>
+.mmd-demo {
+  padding: 8px 4px;
+}
+</style>
+````
+
+## How it works
+
+The markdown packages have **no dependency on Mermaid**. `<CoarMarkdown>` exposes
+an open, language-keyed **fence-renderer registry**: register a component for a
+fence language and that language renders through it instead of as a plain code
+block. Installing `@cocoar/vue-markdown-mermaid` and registering it is the opt-in.
+
+- **On disk** a diagram is a fenced code block with the `mermaid` info string.
+  It's ordinary CommonMark — nothing custom to parse.
+- **Rendering** is client-only (Mermaid needs a DOM) and lazy — Mermaid is
+  dynamically imported on the first diagram, so viewer pages without one never
+  pay for it.
+- **Theming** maps Cocoar design tokens onto Mermaid's `themeVariables`, so
+  diagrams match the app's fonts and palette.
+- **Security**: Mermaid runs with `securityLevel: 'strict'` — author diagram text
+  is treated as untrusted (HTML in labels is sanitized).
+- **Invalid diagrams** degrade to an error box that still shows the raw source;
+  they never throw up to the app.
+
+## Install
+
+```bash
+pnpm add @cocoar/vue-markdown-mermaid
+```
+
+`vue` and `@cocoar/vue-markdown` are peer dependencies; `@cocoar/vue-mermaid`
+(which carries Mermaid, dynamically imported on first render) comes along as a
+regular dependency. Import its stylesheet once (diagram wrapper, error box, zoom
+viewport):
+
+```ts
+import '@cocoar/vue-mermaid/styles';
+```
+
+## Usage
+
+Pass the ready-made registry fragment to the viewer's `fenceRenderers` prop:
+
+```vue
+<template>
+  <CoarMarkdown :doc="doc" :fence-renderers="mermaidFenceRenderers" />
+</template>
+
+<script setup lang="ts">
+import { parse } from '@cocoar/vue-markdown-core';
+import { CoarMarkdown } from '@cocoar/vue-markdown';
+import { mermaidFenceRenderers } from '@cocoar/vue-markdown-mermaid';
+
+const doc = parse(source);
+</script>
+```
+
+A diagram in the source is just a fenced code block (shown here inside a wider
+fence so it isn't rendered):
+
+````text
+```mermaid
+flowchart LR
+  A[Start] --> B{Choice}
+  B -->|yes| C[Do it]
+  B -->|no| D[Skip]
+```
+````
+
+An app-wide default works too — `app.provide(MARKDOWN_FENCE_RENDERERS_KEY, mermaidFenceRenderers)`.
+A per-instance `fence-renderers` prop wins over the provided value.
+
+## Zoom & pan
+
+Per-diagram options are configured on the **registry** (the fence contract only
+passes `{ code, language }` to a component), via `createMermaidFenceRenderers`:
+
+```ts
+import { createMermaidFenceRenderers } from '@cocoar/vue-markdown-mermaid';
+
+const fenceRenderers = createMermaidFenceRenderers({ zoomable: true });
+```
+
+Each diagram then sits in a fixed-height viewport with **+ / − / ⤢** controls,
+**Ctrl/⌘ + wheel** zoom, **drag** to pan and **double-click** to reset. Plain
+wheel and one-finger touch scrolling are left to the page, so a diagram never
+traps the scroll. Set the height with the `--coar-mermaid-height` CSS variable
+(default `420px`).
+
+## Registering your own fence renderer
+
+The registry is open — any language can be mapped to any component. Register your
+own (e.g. a Graphviz renderer) alongside Mermaid, or replace Mermaid entirely:
+
+```ts
+import type { FenceRegistry } from '@cocoar/vue-markdown';
+import { mermaidFenceRenderers } from '@cocoar/vue-markdown-mermaid';
+import MyGraphviz from './MyGraphviz.vue';
+
+// Component receives `{ code, language }` (FenceRendererProps).
+const fenceRenderers: FenceRegistry = {
+  ...mermaidFenceRenderers,
+  dot: MyGraphviz,
+};
+```
+
+A registered component receives the fence's raw text as `code` and the info
+string as `language`. This is the same seam a future BPMN or PlantUML renderer
+would plug into — no change to the markdown core.
+
+## API reference
+
+### `@cocoar/vue-markdown`
+
+| Export | Description |
+|---|---|
+| `FenceRegistry` | `Record<string, Component>` — fence language → renderer component. Keys match case-insensitively. |
+| `FenceRendererProps` | `{ code: string; language: string }` — props a registered renderer receives. |
+| `MARKDOWN_FENCE_RENDERERS_KEY` | Inject key for an app-wide registry. |
+| `resolveFenceRenderer(registry, language)` | The case-insensitive lookup used by `DefaultCodeBlock`. |
+
+### `@cocoar/vue-markdown-mermaid` (the fence adapter)
+
+| Export | Description |
+|---|---|
+| `mermaidFenceRenderers` | Ready-to-spread `FenceRegistry` fragment (`{ mermaid }`), no zoom. |
+| `createMermaidFenceRenderers(options?)` | Build a registry with options baked in — `{ zoomable }`. |
+
+### `@cocoar/vue-mermaid` (the standalone renderer)
+
+| Export | Description |
+|---|---|
+| `CoarMermaidDiagram` | The renderer component (`{ code, language, zoomable }` props). Use directly to render diagrams outside markdown. |
+| `buildMermaidThemeVariables(getToken, resolveColor?)` | Pure Cocoar-token → Mermaid-theme mapping. |
+| `makeCssColorResolver()` / `readCssTokens(el?)` | Browser-backed color/token resolvers for the bridge. |