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

package/skills/cocoar-vue-ui/references/components/document-viewer/coar-document-viewer.md

@@ -0,0 +1,327 @@
+<!-- Generated from apps/docs/components/document-viewer/coar-document-viewer.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# CoarDocumentViewer
+
+The all-in-one viewer component. One required prop — `source` — plus a handful of toggles for chrome, panels, and the annotation surface.
+
+```ts
+import { CoarDocumentViewer } from '@cocoar/vue-document-viewer';
+import '@cocoar/vue-document-viewer/styles';
+```
+
+For PDFs, also pull `pdfSource` from the [`/pdf` subpath](./index.md#worker-setup-pdf-consumers-only) and wire the worker once at app bootstrap.
+
+## Minimal usage
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue';
+import { CoarDocumentViewer, imageSource } from '@cocoar/vue-document-viewer';
+import '@cocoar/vue-document-viewer/styles';
+
+const source = computed(() => imageSource({ url: '/attachments/diagram.png' }));
+</script>
+
+<template>
+  <CoarDocumentViewer :source="source" />
+</template>
+```
+
+That's it. Toolbar on, sidebars and annotations panel off, default 'view' annotation mode. Wrap the viewer in a sized container — the component fills 100% of its parent.
+
+## Props
+
+### Source
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `source` | `DocumentSource` | _required_ | Build via `pdfSource()`, `imageSource()`, or `imageGallerySource()`. Returns a frozen object — build it inside `computed` to avoid unnecessary rebinds. |
+
+Switching the `source` keeps the surrounding chrome mounted; only the inner page renderer rebinds, so users see toolbar / panels stay still across document changes.
+
+### Chrome toggles
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `showToolbar` | `boolean` | `true` | Top/side/bottom toolbar — see `toolbarPosition`. |
+| `toolbarPosition` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Where the toolbar sits. Horizontal at top/bottom, vertical at sides. |
+| `showThumbnails` | `boolean` | `false` | Left-rail Thumbnails tab. Works for every source (per-page mini canvas). |
+| `showOutline` | `boolean` | `false` | Left-rail Outline (TOC) tab. PDF-only; auto-hides when the doc has no outline. |
+| `showAnnotationsPanel` | `boolean` | `false` | Right-rail panel: Info section + annotation list with filter/sort/search. |
+| `showInfoSection` | `boolean` | `true` | Top section of the annotations panel surfacing source metadata. Only active when the panel is open. |
+| `showSearch` | `boolean` | `true` | Search input (button + bar). Disabled when the source can't search (e.g. images). |
+| `showPrintDownload` | `boolean` | `false` | Print + Download buttons in the toolbar. |
+| `showAnnotationModes` | `boolean` | `true` | The drawing-mode button group (marker / note / draw / text). |
+
+Two convenience props — `showThumbnails || showOutline` controls the left-rail toggle button; `showAnnotationsPanel` controls the right-rail toggle. The user can collapse either rail from inside the viewer; these props gate whether the toggle is even present in the toolbar.
+
+#### Panel open state (`v-model`)
+
+By default, the left and right rails start closed and their open/closed state lives inside the component — fine for stand-alone viewers. If you embed the viewer inside a parent that mounts/unmounts it (e.g. a tab bar in a file explorer where the user switches between a Markdown file and a PDF and back), use `v-model` to hold the state on the parent so it **persists across remounts**.
+
+| Prop / Event | Type | Notes |
+|---|---|---|
+| `:sidebar-open` + `@update:sidebar-open` (`v-model:sidebar-open`) | `boolean` | Left rail (thumbnails / outline). Default `false`. |
+| `:annotations-panel-open` + `@update:annotations-panel-open` (`v-model:annotations-panel-open`) | `boolean` | Right rail (info section + annotations list). Default `false`. |
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+const sidebarOpen = ref(false);
+const panelOpen = ref(false);
+</script>
+
+<template>
+  <CoarDocumentViewer
+    :source="source"
+    :show-thumbnails="true"
+    :show-annotations-panel="true"
+    v-model:sidebar-open="sidebarOpen"
+    v-model:annotations-panel-open="panelOpen"
+  />
+</template>
+```
+
+Without `v-model`, the state is purely internal — same behavior as before, no breaking change.
+
+### Position memory
+
+```ts
+interface CoarDocumentViewerPosition {
+  page: number;                   // 0-based page index in view
+  pageOffset: number;             // fractional scroll inside the page, 0..1
+  zoom: number;                   // 1 = 100%
+  rotation: 0 | 90 | 180 | 270;
+}
+```
+
+Two compatible mechanisms:
+
+| Prop / Event | Use when |
+|---|---|
+| `storageKey: string` | You want the viewer to persist position in `localStorage` automatically. Different keys per document (e.g. include the file ID) so each document remembers its own view. |
+| `:position` + `@update:position` (`v-model:position`) | You own persistence (server, IndexedDB, your existing state manager). Two-way binding — the viewer reads on mount, writes on every change. |
+
+Both mechanisms can coexist; when both are present, the bound `position` wins on mount.
+
+### Toolbar layout
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `tools` | `CoarDocumentViewerTool[]` | `undefined` (= `COAR_DOCUMENT_VIEWER_ALL_TOOLS`) | Array drives BOTH the visible set AND the order. See [Toolbar customization](./toolbar.md). |
+
+### Annotations
+
+| Prop / Event | Type | Notes |
+|---|---|---|
+| `annotations` | `CoarPdfAnnotation[]` | Consumer-owned. The viewer never mutates this array. |
+| `:annotation-mode` + `@update:annotationMode` (`v-model:annotation-mode`) | `'view' \| 'select' \| 'eraser' \| 'marker' \| 'comment' \| 'ink' \| 'freetext'` | The active pointer mode. `'view'` is read-only (existing annotations clickable, no new ones created). |
+| `annotationColors` | `string[]` | Palette for the color picker. Defaults to a 7-color pastel + neon set. |
+| `@annotation:create` | `(payload: CoarPdfAnnotationCreatePayload) => void` | Consumer assigns `id` + `createdAt` (+ optionally `createdBy`), pushes to `annotations`. |
+| `@annotation:update` | `(payload: { id: string; patch: Partial<CoarPdfAnnotation> }) => void` | Consumer merges the patch into the matching annotation. |
+| `@annotation:delete` | `(id: string) => void` | Consumer removes by id. |
+
+See [Annotations](./annotations.md) for the full lifecycle, schema, and a worked example.
+
+### Labels
+
+```ts
+interface CoarDocumentViewerLabels {
+  // Loading / error overlays
+  loading?: string;
+  errorTitle?: string;
+  errorRetry?: string;
+
+  // Page navigation
+  pageOf?: string;                  // "Page {current} of {total}"
+  pageJumpAria?: string;
+  prevPage?: string;
+  nextPage?: string;
+
+  // Zoom
+  zoomIn?: string;
+  zoomOut?: string;
+  resetZoom?: string;
+  zoomLevel?: string;
+  fitWidth?: string;
+  fitPage?: string;
+  resetView?: string;
+  pan?: string;
+
+  // Rotation
+  rotateCw?: string;
+  rotateCcw?: string;
+
+  // Search
+  search?: string;
+  searchNext?: string;
+  searchPrev?: string;
+  searchMatchOf?: string;           // "{current} of {total}"
+
+  // Panels + sidebar tabs
+  thumbnails?: string;
+  outline?: string;
+  annotationsPanel?: string;
+
+  // Document actions
+  print?: string;
+  download?: string;
+
+  // Annotation modes
+  modeView?: string;
+  modeSelect?: string;
+  modeEraser?: string;
+  modeMarker?: string;
+  modeNote?: string;
+  modeInk?: string;
+  modeFreetext?: string;
+  strokeWidth?: string;
+
+  // Annotation panel
+  noAnnotations?: string;
+  noMatchingAnnotations?: string;
+  searchAnnotations?: string;
+  filterBy?: string;
+  sortBy?: string;
+  sortByPage?: string;
+  sortChronological?: string;
+  pagePrefix?: string;
+  justNow?: string;
+  moreActions?: string;
+  annotationDelete?: string;
+  annotationEditComment?: string;
+  annotationColor?: string;
+
+  // Capability tooltip suffix — appended when a tool isn't supported by the source.
+  notAvailableForSource?: string;
+
+  // Info section
+  infoSection?: string;             // "Info"
+  infoFormat?: string;
+  infoPages?: string;
+  infoPage?: string;                // "Page {n}"
+  infoSize?: string;
+  infoTitle?: string;
+  infoAuthor?: string;
+  infoSubject?: string;
+  infoKeywords?: string;
+  infoCreator?: string;
+  infoProducer?: string;
+  infoCreated?: string;
+  infoModified?: string;
+  infoPdfVersion?: string;
+}
+```
+
+English defaults are baked in. Pass any subset to override individual strings — keys you omit fall back to the default. `{current}`, `{total}`, `{n}` placeholders are substituted at render time.
+
+## Events
+
+| Event | Payload | When |
+|---|---|---|
+| `update:position` | `CoarDocumentViewerPosition` | Page / scroll / zoom / rotation change. Used for `v-model:position`. |
+| `update:annotationMode` | `CoarPdfAnnotationMode` | User picks a different mode in the toolbar. Used for `v-model:annotation-mode`. |
+| `update:sidebarOpen` | `boolean` | User toggles the left rail (thumbnails / outline). Used for `v-model:sidebar-open`. |
+| `update:annotationsPanelOpen` | `boolean` | User toggles the right rail (annotations panel). Used for `v-model:annotations-panel-open`. |
+| `annotation:create` | `CoarPdfAnnotationCreatePayload` | New annotation drawn. Consumer assigns id + timestamp. |
+| `annotation:update` | `{ id, patch }` | Existing annotation edited (color / comment / position). |
+| `annotation:delete` | `string` (id) | Existing annotation removed (via panel menu or eraser tool). |
+| `error` | `CoarDocumentViewerErrorEvent` | Source failed to load. `{ error: unknown, src?: string }`. |
+
+## Slots
+
+| Slot | Props | When |
+|---|---|---|
+| `loading` | _none_ | Replaces the default `"Loading…"` text shown while the source is fetching/parsing. |
+| `error` | `{ error: unknown; retry: () => void }` | Replaces the default error overlay. Call `retry()` to re-trigger the load. |
+
+```vue
+<CoarDocumentViewer :source="source">
+  <template #loading>
+    <CoarSpinner /> Fetching document…
+  </template>
+  <template #error="{ error, retry }">
+    <div>
+      <strong>{{ String(error) }}</strong>
+      <CoarButton @click="retry">Try again</CoarButton>
+    </div>
+  </template>
+</CoarDocumentViewer>
+```
+
+## Sizing
+
+The viewer fills 100% of its parent and uses internal flexbox to allocate space across toolbar, panels, and the page area. Put it inside a sized container:
+
+```vue
+<div style="height: 80vh">
+  <CoarDocumentViewer :source="source" />
+</div>
+```
+
+Splitters between the columns are draggable — users can resize the left rail (thumbnails) and right rail (annotations panel) on the fly.
+
+## Position memory example
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarDocumentViewer, type CoarDocumentViewerPosition } from '@cocoar/vue-document-viewer';
+import { pdfSource } from '@cocoar/vue-document-viewer/pdf';
+
+const source = pdfSource({ url: '/files/manual.pdf' });
+
+// v-model:position — server-side persistence
+const position = ref<CoarDocumentViewerPosition>({
+  page: 0, pageOffset: 0, zoom: 1, rotation: 0,
+});
+watchDebounced(position, savePositionToServer, { debounce: 300 });
+
+// OR — storageKey for automatic localStorage persistence
+</script>
+
+<template>
+  <CoarDocumentViewer
+    :source="source"
+    v-model:position="position"
+    storage-key="manual.pdf"
+  />
+</template>
+```
+
+Use one OR the other in practice — both is fine, just pick the priority. When both are present, the bound `position` wins on mount; afterwards both stay in sync.
+
+## Common configurations
+
+### Read-only PDF viewer with thumbnails
+
+```vue
+<CoarDocumentViewer
+  :source="source"
+  :show-thumbnails="true"
+  :show-outline="true"
+  :show-print-download="true"
+  :show-annotation-modes="false"
+/>
+```
+
+### Annotation tool with persistence
+
+```vue
+<CoarDocumentViewer
+  :source="source"
+  :show-annotations-panel="true"
+  v-model:annotation-mode="mode"
+  :annotations="annotations"
+  storage-key="contract-2024"
+  @annotation:create="handleCreate"
+  @annotation:update="handleUpdate"
+  @annotation:delete="handleDelete"
+/>
+```
+
+### Minimal embedded preview (no toolbar)
+
+```vue
+<CoarDocumentViewer :source="source" :show-toolbar="false" />
+```

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

@@ -0,0 +1,234 @@
+<!-- Generated from apps/docs/components/document-viewer/index.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Document Viewer (Preview)
+
+`@cocoar/vue-document-viewer` is a generic, source-agnostic document viewer for Vue 3. One component — [`<CoarDocumentViewer>`](./coar-document-viewer.md) — renders **PDFs**, **single images**, and **multi-page image galleries**, with shared toolbar chrome, side panels, and an annotation layer.
+
+You pick the source kind with a small factory (`pdfSource(...)`, `imageSource(...)`, `imageGallerySource(...)`); the viewer dispatches internally. The toolbar greys out tools the active source doesn't support — e.g. search and outline are PDF-only — rather than hiding them, so users don't see UI moving around when they switch documents.
+
+```ts
+import {
+  CoarDocumentViewer,
+  imageSource,
+  imageGallerySource,
+} from '@cocoar/vue-document-viewer';
+import { pdfSource } from '@cocoar/vue-document-viewer/pdf';
+import '@cocoar/vue-document-viewer/styles';
+```
+
+`pdfjs-dist` is an **optional peer dependency**. PDF consumers import `pdfSource` from the `/pdf` subpath; image-only consumers never pay the pdfjs bundle cost.
+
+## Three source factories
+
+```ts
+// PDF — pdfjs subpath
+pdfSource({ url, headers?, withCredentials? })
+
+// Single-page raster / vector image (JPG / PNG / SVG / WebP / AVIF / GIF / blob: / data:)
+imageSource({ url })
+
+// Multi-page image document — pages may mix orientations
+imageGallerySource({ urls })
+```
+
+Each factory returns a frozen `DocumentSource`. Build it inside a `computed` so the viewer rebinds only when something actually changes — switching sources keeps the toolbar, panels, and viewport mounted; only the inner page renderer rebinds.
+
+## Single image
+
+**Demo — `document-viewer/demos/ImageSourceDemo.vue`**
+
+```vue
+<template>
+  <ClientOnly>
+    <div style="height: 520px; border: 1px solid var(--vp-c-divider); border-radius: 8px; overflow: hidden;">
+      <component
+        :is="Viewer"
+        v-if="Viewer && source"
+        :source="source"
+        :show-thumbnails="true"
+        :show-annotations-panel="true"
+      />
+      <div v-else class="dv-loading">Loading viewer…</div>
+    </div>
+  </ClientOnly>
+</template>
+
+<script setup lang="ts">
+import { computed, onMounted, ref, shallowRef, type Component } from 'vue';
+import { SINGLE_IMAGE_URL } from './_shared';
+
+const Viewer = shallowRef<Component | null>(null);
+const imageSource = shallowRef<((opts: { url: string }) => unknown) | null>(null);
+
+const source = computed(() => imageSource.value?.({ url: SINGLE_IMAGE_URL }) ?? null);
+
+onMounted(async () => {
+  const mod = await import('@cocoar/vue-document-viewer');
+  await import('@cocoar/vue-document-viewer/styles');
+  imageSource.value = mod.imageSource;
+  Viewer.value = mod.CoarDocumentViewer;
+});
+</script>
+
+<style scoped>
+.dv-loading {
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--coar-text-neutral-tertiary, #6b7280);
+  font-size: 13px;
+}
+</style>
+```
+
+Toolbar tools the source doesn't support stay visible but disabled — e.g. **Search**, **Previous/Next page**, and **Outline** are off for a single-page image. Their tooltips append the `notAvailableForSource` label so the user understands the state.
+
+## Image gallery
+
+**Demo — `document-viewer/demos/GallerySourceDemo.vue`**
+
+```vue
+<template>
+  <ClientOnly>
+    <div style="height: 520px; border: 1px solid var(--vp-c-divider); border-radius: 8px; overflow: hidden;">
+      <component
+        :is="Viewer"
+        v-if="Viewer && source"
+        :source="source"
+        :show-thumbnails="true"
+        :show-annotations-panel="true"
+      />
+      <div v-else class="dv-loading">Loading viewer…</div>
+    </div>
+  </ClientOnly>
+</template>
+
+<script setup lang="ts">
+import { computed, onMounted, shallowRef, type Component } from 'vue';
+import { GALLERY_URLS } from './_shared';
+
+const Viewer = shallowRef<Component | null>(null);
+const galleryFactory = shallowRef<((opts: { urls: readonly string[] }) => unknown) | null>(null);
+
+const source = computed(() => galleryFactory.value?.({ urls: GALLERY_URLS }) ?? null);
+
+onMounted(async () => {
+  const mod = await import('@cocoar/vue-document-viewer');
+  await import('@cocoar/vue-document-viewer/styles');
+  galleryFactory.value = mod.imageGallerySource;
+  Viewer.value = mod.CoarDocumentViewer;
+});
+</script>
+
+<style scoped>
+.dv-loading {
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--coar-text-neutral-tertiary, #6b7280);
+  font-size: 13px;
+}
+</style>
+```
+
+Pages can mix orientations (landscape page 1, portrait page 2, wide page 3 above). Every page's intrinsic dimensions are read from its own image, so the viewer never letter-boxes or stretches. Sidebar thumbnails track the active page.
+
+## PDF source
+
+The PDF demo runs in the playground at [`localhost:5188/pdf-viewer`](http://localhost:5188/pdf-viewer) — it's omitted here because the pdfjs worker has to be configured by the consumer (one-line setup, below).
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue';
+import { CoarDocumentViewer } from '@cocoar/vue-document-viewer';
+import { pdfSource } from '@cocoar/vue-document-viewer/pdf';
+import '@cocoar/vue-document-viewer/styles';
+
+const source = computed(() => pdfSource({
+  url: '/api/files/contract.pdf',
+  withCredentials: true,         // forward cookies / HTTP auth
+  headers: { 'X-Tenant': 'acme' }, // arbitrary request headers
+}));
+</script>
+
+<template>
+  <CoarDocumentViewer
+    :source="source"
+    :show-thumbnails="true"
+    :show-outline="true"
+    :show-annotations-panel="true"
+    :show-print-download="true"
+  />
+</template>
+```
+
+### Worker setup (PDF consumers only)
+
+pdfjs needs a worker to parse the binary off the main thread. Wire it once at app bootstrap — Vite/webpack/Rollup all support the `?worker` query:
+
+```ts
+// main.ts
+import * as pdfjs from 'pdfjs-dist';
+import PdfWorker from 'pdfjs-dist/build/pdf.worker.min.mjs?worker';
+
+pdfjs.GlobalWorkerOptions.workerPort = new PdfWorker();
+```
+
+If you skip this step, pdfjs will try to fetch the worker over the network and fall back to a slow inline mode — both viable, but not what you want in production.
+
+## Source capabilities
+
+Every source advertises what it can do. The toolbar reads these flags to enable/disable individual tools; consumers can inspect them too:
+
+```ts
+interface DocumentSourceCapabilities {
+  multiPage: boolean;     // Prev / Next / page input
+  textLayer: boolean;     // Text selection, Ctrl+C copy
+  search: boolean;        // Search button
+  outline: boolean;       // Outline (TOC) sidebar tab
+  print: boolean;         // Print button
+}
+```
+
+The factories pre-populate the right values: PDFs get all-true, images get a single-page no-text profile, galleries get the same with `multiPage: true`. Adding a future source kind (e.g. OCR'd images) is a matter of providing a new factory that flips the relevant flags.
+
+> **Tip: Why disabled, not hidden?**
+>
+> Tools that vanish when the source changes make the toolbar layout shift — buttons jump positions, muscle memory breaks. Greying out keeps positions stable and surfaces the capability constraint to the user via tooltip.
+
+## Info panel
+
+When the right-side annotations panel is open, a collapsible **Info** section at the top surfaces source metadata:
+
+- Format string (`"PDF · v1.7"`, `"Image · PNG"`, `"Image gallery · SVG"`)
+- Total page count
+- Current page dimensions (live — updates as the user flips pages)
+- PDF-only fields: title / author / subject / keywords / creator / producer / created / modified / PDF version (empty fields are skipped)
+- File size in bytes (PDFs only — pdfjs exposes `contentLength`)
+
+Disable with `:show-info-section="false"` if you want a minimal annotations-only panel.
+
+## Architecture
+
+```
+<CoarDocumentViewer :source="…">
+  useDocumentLoader(sourceRef)             ← internal dispatcher, watches source.kind
+    usePdfDocumentAdapter(pdfSourceRef)
+    useImageDocumentAdapter(imgSourceRef)
+    useImageGalleryAdapter(gallerySourceRef)
+        each publishes { status, pageProviders, info, error, retry, destroy }
+  usePageRenderer({ pageProviders, … })    ← source-agnostic, owns canvas + textLayer DOM
+  DocumentToolbar, DocumentSidebar, DocumentAnnotationPanel, DocumentSearchBar
+```
+
+The seam between formats is `PageProvider` — every page (PDF page proxy, image element, future kinds) materializes through the same interface (`render(canvas, opts)`, `cancel()`, optional `getTextLayer()`). The renderer never imports `pdfjs-dist`.
+
+## What's next
+
+| Page | Covers |
+|------|--------|
+| [CoarDocumentViewer](./coar-document-viewer.md) | Full props / emits / slots reference, labels, position memory |
+| [Toolbar customization](./toolbar.md) | Order-driven `tools` array, separator pseudo-tool, section toggles |
+| [Annotations](./annotations.md) | Modes, types, lifecycle events, schema, color picker |