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

package/skills/cocoar-vue-ui/references/components/fragment-parser.md

@@ -0,0 +1,298 @@
+<!-- Generated from apps/docs/components/fragment-parser.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Fragment Parser & Modal Routing
+
+Parse URL fragments (hash portion) into structured routes with parameters. Combined with composables, this enables **deep-linkable modals** — open modals via URL, share links, and use browser back to close them.
+
+> **Info: Separate Package**
+>
+```bash
+pnpm add @cocoar/vue-fragment-parser
+```
+
+```ts
+import {
+  parseFragment,            // Core parser
+  useFragmentNavigation,    // navigateToModal(), closeModal()
+  useRoutedFragments,       // Reactive fragment parsing
+  useRoutedModals,          // Auto dialog/modal from URL
+  type DialogFragment,      // type: 'dialog' route config
+  type ModalFragment,       // type: 'modal' route config
+} from '@cocoar/vue-fragment-parser';
+```
+
+## Basic Usage
+
+Define routes with path patterns and parse the current URL fragment:
+
+```ts
+import { parseFragment, type RoutedFragmentBase } from '@cocoar/vue-fragment-parser';
+
+interface AppRoute extends RoutedFragmentBase {
+  type: string;
+  path: string | string[];
+  options?: { requiresAuth?: boolean };
+}
+
+const routes: AppRoute[] = [
+  { type: 'overview', path: 'overview' },
+  { type: 'details', path: 'details/:id' },
+  { type: 'edit', path: 'details/:id/edit' },
+];
+
+// URL: https://app.com/#details/42?tab=comments
+const result = parseFragment('#details/42?tab=comments', routes);
+// → [{ route: { type: 'details', ... }, params: { id: '42', tab: 'comments' }, fragment: '...' }]
+```
+
+## Path Parameters
+
+Use `:param` syntax for dynamic segments (powered by `path-to-regexp`):
+
+```ts
+const routes = [
+  { type: 'user', path: 'user/:userId' },
+  { type: 'project', path: 'project/:projectId/task/:taskId' },
+];
+
+// #user/abc → params: { userId: 'abc' }
+// #project/1/task/42 → params: { projectId: '1', taskId: '42' }
+```
+
+## Query Parameters
+
+Query parameters are parsed automatically with JSON type coercion:
+
+```ts
+// #details/5?edit=true&count=3
+// → params: { id: '5', edit: true, count: 3 }
+
+// #overview?tags=["a","b"]
+// → params: { tags: ['a', 'b'] }
+```
+
+## Multiple Fragments
+
+Chain multiple fragments with `#` for composable routing:
+
+```ts
+// #details/5#confirm?force=true
+const results = parseFragment('#details/5#confirm?force=true', routes);
+// → Two parsed routes: details + confirm
+```
+
+## Array Paths
+
+A single route can match multiple paths:
+
+```ts
+const routes = [
+  { type: 'docs', path: ['overview', 'usage', 'examples'] },
+];
+
+// #overview → matches docs route
+// #usage → matches docs route
+// #examples → matches docs route
+```
+
+## Modal Routing
+
+The fragment parser's main use case: **deep-linkable modals**. When a user double-clicks a grid row, the modal opens AND the URL updates. Copy-pasting that URL opens the same modal. Browser back closes it.
+
+```
+/todos                → just the list
+/todos#todo-42        → list + detail modal for todo-42
+/todos#todo-42?tab=2  → list + detail modal, comments tab selected
+```
+
+### How It Works
+
+Three composables work together:
+
+```
+User clicks row
+    ↓
+navigateToModal('todo-42')         ← useFragmentNavigation
+    ↓
+URL changes to /todos#todo-42
+    ↓
+useRoutedFragments detects change  ← useRoutedFragments
+    ↓
+Parses fragment against routes
+    ↓
+useRoutedModals opens dialog       ← useRoutedModals
+    ↓
+User closes dialog (or browser back)
+    ↓
+Fragment removed from URL
+```
+
+### Step 1: Define Fragment Routes
+
+Register which fragments should open components in your Vue Router config. Two types are supported:
+
+- **`type: 'dialog'`** — Opens inside a `CoarDialog` shell (header, title, close button)
+- **`type: 'modal'`** — Opens as a raw overlay (no shell, your component IS the entire modal)
+
+```ts
+// routes.ts
+import type { RoutedOverlayFragment } from '@cocoar/vue-fragment-parser';
+
+const routes = [
+  {
+    path: '/todos',
+    component: () => import('./TodoList.vue'),
+    meta: {
+      routedFragments: [
+        {
+          type: 'dialog',
+          path: ':todoId',
+          component: () => import('./TodoDetail.vue'),
+          dialogOptions: { title: 'Todo Details', size: 'l' },
+        },
+      ] satisfies RoutedOverlayFragment[],
+    },
+  },
+];
+```
+
+### Step 2: Wire Up the List View
+
+```vue
+<!-- TodoList.vue -->
+<script setup lang="ts">
+import { useFragmentNavigation, useRoutedModals } from '@cocoar/vue-fragment-parser';
+
+// Auto-open/close modals based on URL fragments
+useRoutedModals();
+
+// Navigate to modal on interaction
+const { navigateToModal } = useFragmentNavigation();
+
+builder.onRowDoubleClicked((event) => {
+  navigateToModal(event.data.id);
+});
+
+// With query params:
+// navigateToModal(event.data.id, { tab: 0 })
+// → URL: #todo-42?tab=0
+</script>
+```
+
+### Step 3: Build the Modal Content
+
+The modal component receives fragment params as props, plus a `close` function:
+
+```vue
+<!-- TodoDetail.vue -->
+<script setup lang="ts">
+const props = defineProps<{
+  todoId: string;       // from fragment path ':todoId'
+  tab?: number;         // from query params '?tab=2'
+  close: (result?: unknown) => void;
+}>();
+</script>
+
+<template>
+  <div>
+    <h3>Todo: {{ todoId }}</h3>
+    <button @click="close()">Done</button>
+  </div>
+</template>
+```
+
+### Deep-Linking
+
+Copy the URL `https://app.com/todos#todo-42?tab=2` and paste it in a new browser tab. The page loads, the fragment is parsed, and the modal opens automatically with `todoId: 'todo-42'` and `tab: 2`.
+
+### Browser Back & History
+
+The modal system integrates with browser history:
+
+- **Modal open** → creates a history entry (`/todos` → `/todos#todo-42`)
+- **Modal close** (X button) → creates another entry (`/todos#todo-42` → `/todos`)
+- **Browser Back** after close → goes back to `/todos#todo-42` → modal reopens
+- **Browser Back** while modal is open → goes back to `/todos` → modal closes
+
+This means users can navigate modal state with the browser's back/forward buttons, just like regular pages.
+
+### Multiple Modals
+
+By default, `navigateToModal` **replaces** the current fragment. Use `append: true` to open multiple modals at once:
+
+```ts
+// Opens modal, replaces any existing fragment
+navigateToModal('todo-42');
+// URL: /todos#todo-42
+
+// Opens second modal alongside the first
+navigateToModal('confirm', undefined, { append: true });
+// URL: /todos#todo-42#confirm
+```
+
+Each fragment is matched independently. Closing one modal removes only its fragment.
+
+## Composable API
+
+### `useFragmentNavigation()`
+
+```ts
+const { navigateToModal, closeModal } = useFragmentNavigation();
+```
+
+| Method | Parameters | Description |
+|--------|-----------|-------------|
+| `navigateToModal(path, params?, options?)` | `string, Record<string, ...>?, { append?: boolean }?` | Set fragment in URL, opens modal. `append: true` for multi-modal. |
+| `closeModal(path)` | `string` | Remove fragment from URL, closes modal |
+
+### `useRoutedFragments(routes?)`
+
+```ts
+const { fragments } = useRoutedFragments();
+```
+
+Reactively parses `route.hash` against routes from `route.meta.routedFragments`. Returns `computed<ParsedRoute[]>`.
+
+### `useRoutedModals()`
+
+```ts
+useRoutedModals();
+```
+
+Fire-and-forget composable. Watches fragments and manages the overlay lifecycle:
+
+- **`type: 'dialog'`** → opens via `useDialog().open()` with `DialogConfig` (shell with header/title)
+- **`type: 'modal'`** → opens via `getOverlayService().open()` with `OverlaySpec` (raw overlay, no shell)
+
+Handles:
+- Fragment appears → lazy-load component → open dialog/modal
+- Fragment removed (close button, browser back) → close
+- Closed by user → remove fragment from URL
+- Page load with fragment → deep-link: opens immediately
+
+## API
+
+### `parseFragment<T>(fragment, routes)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fragment` | `string` | URL fragment string (with or without leading `#`) |
+| `routes` | `T[]` | Array of route definitions |
+
+**Returns:** `ParsedRoute<T>[]` — array of matched routes
+
+### Types
+
+```ts
+interface RoutedFragmentBase<TOptions = unknown> {
+  type: string;
+  path: string | string[];
+  options?: TOptions;
+}
+
+interface ParsedRoute<T extends RoutedFragmentBase> {
+  params: Record<string, unknown>;  // Path + query parameters
+  route: T;                          // Matched route config
+  fragment: string;                  // Original fragment string
+}
+```

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

@@ -0,0 +1,235 @@
+<!-- Generated from apps/docs/components/link.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Link
+
+Styled anchor elements for in-page navigation, external references, and any clickable text that isn't a button action. Two equivalent APIs:
+
+- **`<CoarLink>` SFC** (recommended) — `to` for router navigation, `href` for external links, automatic `rel="noopener"` for new-tab safety, disabled handling.
+- **CSS classes** — `<a class="coar-link">` with hand-written `href` / `<RouterLink>` for consumers who want zero abstraction.
+
+Both layers share the same CSS in `@cocoar/vue-ui/styles`. Mix them freely.
+
+```ts
+import { CoarLink } from '@cocoar/vue-ui';
+```
+
+## Basic usage
+
+```vue
+<!-- Router navigation (when vue-router is installed) -->
+<CoarLink to="/docs">Documentation</CoarLink>
+
+<!-- External link with safe new-tab default -->
+<CoarLink href="https://docs.cocoar.dev" target="_blank">
+  Cocoar Docs
+</CoarLink>
+
+<!-- mailto / tel still works via href -->
+<CoarLink href="mailto:hi@example.com">hi@example.com</CoarLink>
+```
+
+The default style applies an accent color with an underline on hover, making links instantly recognizable in any context.
+
+**Demo — `link/demos/LinkBasic.vue`**
+
+```vue
+<template>
+  <CoarLink to="/getting-started">Default link</CoarLink>
+</template>
+
+<script setup lang="ts">
+import { CoarLink } from '@cocoar/vue-ui';
+</script>
+```
+
+## Variants
+
+Use the `accent` variant (default) for primary navigation and calls to action. Switch to `subtle` when the link should blend into surrounding body text.
+
+```vue
+<CoarLink to="/docs" variant="subtle">Read the docs</CoarLink>
+```
+
+**Demo — `link/demos/LinkVariants.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <div><CoarLink to="/getting-started">Accent link (default)</CoarLink> — Primary interactive text</div>
+    <div><CoarLink to="/changelog" variant="subtle">Subtle link</CoarLink> — Secondary actions, less emphasis</div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarLink } from '@cocoar/vue-ui';
+</script>
+```
+
+## Sizes
+
+Three size modifiers align with the typography scale, so links stay proportional whether they appear in footnotes or headings.
+
+```vue
+<CoarLink href="#" size="s">Small</CoarLink>
+<CoarLink href="#" size="m">Medium (default)</CoarLink>
+<CoarLink href="#" size="l">Large</CoarLink>
+```
+
+**Demo — `link/demos/LinkSizes.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <div><CoarLink to="/changelog" size="s">Small link</CoarLink> — Compact contexts</div>
+    <div><CoarLink to="/getting-started" size="m">Default link</CoarLink> — Body text size</div>
+    <div><CoarLink to="/components/button" size="l">Large link</CoarLink> — Prominent CTAs</div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarLink } from '@cocoar/vue-ui';
+</script>
+```
+
+## Disabled state
+
+Pass `disabled` to deactivate the link visually and semantically. The component sets `aria-disabled="true"`, `tabindex="-1"`, and intercepts clicks — navigation and `@click` emit are both suppressed.
+
+```vue
+<CoarLink to="/admin" disabled>Admin (insufficient permissions)</CoarLink>
+```
+
+**Demo — `link/demos/LinkDisabled.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <div><CoarLink to="/getting-started">Active link</CoarLink></div>
+    <div><CoarLink to="/components/button" disabled>Disabled link</CoarLink></div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarLink } from '@cocoar/vue-ui';
+</script>
+```
+
+## Inline usage
+
+Links are designed to sit naturally inside running prose without disrupting line height or text flow.
+
+**Demo — `link/demos/LinkInline.vue`**
+
+```vue
+<template>
+  <p style="margin: 0; font-size: 14px; line-height: 1.6;">
+    The COAR Design System is built on top of
+    <CoarLink href="https://vuejs.org" target="_blank">Vue 3</CoarLink> and uses the
+    <CoarLink href="https://tc39.es/proposal-temporal/docs/" target="_blank">Temporal API</CoarLink> for date/time handling.
+    See the <CoarLink to="/getting-started">Getting Started guide</CoarLink> or
+    browse the <CoarLink to="/components/button" variant="subtle">full component reference</CoarLink>
+    for more details.
+  </p>
+</template>
+
+<script setup lang="ts">
+import { CoarLink } from '@cocoar/vue-ui';
+</script>
+```
+
+## Router Integration
+
+When `to` is set, the link renders via `<RouterLink>` (if `vue-router` is installed and `app.use(router)` has registered the plugin) for SPA navigation. Without a router, it falls back to a plain `<a href={String(to)}>` that works for absolute URLs. The router detection uses `resolveDynamicComponent('RouterLink')` — no hard dependency, no peerDependency requirement.
+
+```vue
+<!-- SPA navigation when router available -->
+<CoarLink to="/docs">Documentation</CoarLink>
+
+<!-- Object-shaped routes work too (with router) -->
+<CoarLink :to="{ name: 'docs', params: { section: 'intro' } }">
+  Intro
+</CoarLink>
+```
+
+`aria-current="page"` is applied automatically when the current route matches `to` (via `RouterLink.isActive`).
+
+> **Warning: Object `to` without router**
+>
+> Passing an object literal (`{ name: 'docs' }`) 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 call site to make this loud. Pass a string path for the no-router case.
+
+## External Links
+
+For absolute URLs and `mailto:` / `tel:` schemes, use `href` instead of `to`. The component skips the router entirely and renders a plain `<a>`. When `target="_blank"` is set, `rel="noopener"` is added automatically as a tab-nabbing defence (browsers do this by default since 2021, but the explicit attribute documents intent and works in older browsers).
+
+```vue
+<CoarLink href="https://github.com/cocoar-dev" target="_blank">
+  GitHub
+</CoarLink>
+<!-- Renders: <a href="..." target="_blank" rel="noopener" class="coar-link"> -->
+```
+
+You can override the auto-rel by passing your own:
+
+```vue
+<CoarLink
+  href="https://untrusted.example.com"
+  target="_blank"
+  rel="noopener noreferrer external"
+>
+  External (extra-cautious)
+</CoarLink>
+```
+
+## CSS-only usage (no SFC)
+
+If you only need the styling and want to wire the link element yourself (typically inside a `<RouterLink>` slot, breadcrumb, or templated context), apply the CSS classes directly to a native `<a>`:
+
+```vue
+<RouterLink to="/docs" custom v-slot="{ href, navigate, isActive }">
+  <a
+    :href="href"
+    class="coar-link"
+    :class="{ 'coar-link--disabled': !canVisit }"
+    @click="navigate"
+  >
+    Documentation
+  </a>
+</RouterLink>
+```
+
+This is the original API and stays supported indefinitely — the SFC is purely additive.
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `to` | `RouteLocationRaw \| string` | `undefined` | Vue Router target. Takes precedence over `href`. Renders via `<RouterLink>` if installed, else falls back to plain `<a href={String(to)}>`. |
+| `href` | `string` | `undefined` | External URL. Used when `to` is not set. Works for `https:`, `mailto:`, `tel:`, etc. |
+| `variant` | `'accent' \| 'subtle'` | `'accent'` | Visual variant. `accent` for primary links, `subtle` for blending into body text. |
+| `size` | `'s' \| 'm' \| 'l'` | `'m'` | Typography size. |
+| `disabled` | `boolean` | `false` | Disabled state (aria-disabled, tabindex=-1, click suppressed). |
+| `target` | `string` | `undefined` | Anchor target attribute. Only applied to the plain `<a>` branches (not via `<RouterLink>`). |
+| `rel` | `string` | *(see below)* | Anchor rel attribute. Auto-fills to `noopener` when `target="_blank"` is set and no explicit `rel` is provided. |
+
+### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `click` | `MouseEvent` | Emitted on every plain click (not when disabled). Modifier-clicks (Ctrl/Cmd/Middle) pass through to the browser. |
+
+### Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Link content (text, icons, anything inline). |
+
+### CSS Classes (legacy / advanced)
+
+| Class | Description |
+|-------|-------------|
+| `.coar-link` | Base link style — accent color, underline on hover |
+| `.coar-link--subtle` | Subtle variant with less color emphasis |
+| `.coar-link--s` / `--m` / `--l` | Typography size |
+| `.coar-link--disabled` | Disabled appearance (combine with `aria-disabled="true"`) |