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

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

@@ -0,0 +1,221 @@
+<!-- Generated from apps/docs/components/document-viewer/toolbar.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Toolbar customization
+
+The toolbar is **order-driven**: the `tools` prop is an array of tool identifiers in the order you want them to render. Want zoom buttons on the left and page navigation on the right? Just reorder the array. Want a custom layout with only the four buttons you actually need? Pass that subset.
+
+When `tools` is omitted, the viewer falls back to `COAR_DOCUMENT_VIEWER_ALL_TOOLS` — the canonical 8-group layout with separators at the original group boundaries.
+
+## Minimal toolbar
+
+The canonical "nav + zoom" layout — page navigation, separator, zoom controls:
+
+**Demo — `document-viewer/demos/MinimalToolbarDemo.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"
+        :tools="MINIMAL_TOOLS"
+      />
+      <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';
+
+/**
+ * Order-driven `tools` prop. Leading + trailing separators are auto-trimmed
+ * and consecutive separators collapse to one — see Toolbar customization.
+ */
+const MINIMAL_TOOLS = [
+  'prev-page',
+  'page-input',
+  'next-page',
+  'separator',
+  'zoom-out',
+  'zoom-reset',
+  'zoom-in',
+] as const;
+
+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>
+```
+
+```ts
+import type { CoarDocumentViewerTool } from '@cocoar/vue-document-viewer';
+
+const MINIMAL_TOOLS: CoarDocumentViewerTool[] = [
+  'prev-page',
+  'page-input',
+  'next-page',
+  'separator',
+  'zoom-out',
+  'zoom-reset',
+  'zoom-in',
+];
+```
+
+```vue
+<CoarDocumentViewer :source="source" :tools="MINIMAL_TOOLS" />
+```
+
+## The `'separator'` pseudo-tool
+
+`'separator'` doesn't render an action — it renders a `CoarSidebarDivider` between groups. Place it anywhere in the array to visually break up clusters.
+
+Three convenience behaviors save you from edge-case handling:
+
+| Input | Output |
+|---|---|
+| Leading `'separator'` | Trimmed |
+| Trailing `'separator'` | Trimmed |
+| Consecutive `'separator'`s | Collapsed to one |
+
+This matters because **section toggles** (e.g. `showSearch: false`) filter tools _before_ the trim/collapse. So a `tools` array like `['prev-page', 'separator', 'search', 'separator', 'next-page']` with `showSearch: false` doesn't leave you two adjacent orphan separators — the collapse step turns it into `['prev-page', 'separator', 'next-page']` automatically.
+
+## All available tools
+
+The full `CoarDocumentViewerTool` union:
+
+| Identifier | What it does | Default group |
+|---|---|---|
+| `sidebar-toggle` | Toggle the left rail (thumbnails / outline) | Panels |
+| `annotations-panel` | Toggle the right rail | Panels |
+| `prev-page` | Previous page | Navigation |
+| `page-input` | "Page N of M" number input | Navigation |
+| `next-page` | Next page | Navigation |
+| `zoom-out` | Zoom out one step | Zoom |
+| `zoom-reset` | Editable zoom-percent readout (click to reset to 100%) | Zoom |
+| `zoom-in` | Zoom in one step | Zoom |
+| `fit-width` | Fit page width to viewport | View |
+| `fit-page` | Fit whole page to viewport | View |
+| `reset-view` | Reset zoom + rotation | View |
+| `rotate-ccw` | Rotate -90° | Rotation |
+| `rotate-cw` | Rotate +90° | Rotation |
+| `pan` | Hand tool — drag the page | Pointer |
+| `select` | Select / move existing annotations | Pointer |
+| `eraser` | Erase strokes from marker / ink annotations | Pointer |
+| `marker` | Draw highlighter strokes | Drawing |
+| `note` | Place comment pin | Drawing |
+| `ink` | Free-hand ink strokes | Drawing |
+| `freetext` | Place free-text box | Drawing |
+| `search` | Open search bar | Actions |
+| `print` | Print document | Actions |
+| `download` | Download source file | Actions |
+| `separator` | Visual divider between groups | _pseudo-tool_ |
+
+## Default layout
+
+`COAR_DOCUMENT_VIEWER_ALL_TOOLS` — the canonical 8-group layout, importable so you can derive variants by filtering:
+
+```ts
+import { COAR_DOCUMENT_VIEWER_ALL_TOOLS } from '@cocoar/vue-document-viewer';
+
+// Hide just the print + download buttons
+const tools = COAR_DOCUMENT_VIEWER_ALL_TOOLS.filter(
+  (t) => t !== 'print' && t !== 'download',
+);
+```
+
+## Filtering layers
+
+Three independent layers decide which buttons render and how:
+
+```
+                user's `tools` array (or COAR_DOCUMENT_VIEWER_ALL_TOOLS)
+                                │
+                                ▼
+   ┌─────────────────────────────────────────────────────┐
+   │  1. Section toggles strip whole categories          │
+   │     showSearch:false       → drop 'search'          │
+   │     showPrintDownload:false → drop 'print','download' │
+   │     showAnnotationModes:false → drop drawing tools  │
+   │     (no Thumbnails/Outline?) → drop 'sidebar-toggle'│
+   │     (no AnnotationsPanel?)   → drop 'annotations-panel' │
+   └─────────────────────────────────────────────────────┘
+                                │
+                                ▼
+   ┌─────────────────────────────────────────────────────┐
+   │  2. Separator normalization                         │
+   │     trim leading / trailing → collapse consecutive  │
+   └─────────────────────────────────────────────────────┘
+                                │
+                                ▼
+   ┌─────────────────────────────────────────────────────┐
+   │  3. Capability gating (per-tool, runtime)            │
+   │     source.capabilities.search:false → 'search' disabled │
+   │     source.capabilities.multiPage:false → page-nav disabled │
+   │     source.capabilities.outline:false → outline tab hidden │
+   │     (disabled tools STAY VISIBLE with a tooltip suffix) │
+   └─────────────────────────────────────────────────────┘
+                                │
+                                ▼
+                  Final rendered toolbar
+```
+
+Layers 1 and 2 happen in pure-function form (`computeEffectiveTools` in `internal/effective-tools.ts`) and remove items from the array. Layer 3 happens per-button at render time — it never removes anything, just toggles the `disabled` state and appends `notAvailableForSource` to the tooltip.
+
+This is the **stable-position rule**: switching sources never makes buttons jump around, because layer 3 doesn't touch positions.
+
+## Section toggles vs `tools` array
+
+If you want to drop a whole category, either path works:
+
+```ts
+// A) Shorthand — section toggle
+<CoarDocumentViewer :source="src" :show-print-download="false" />
+
+// B) Explicit — omit from tools array
+<CoarDocumentViewer
+  :source="src"
+  :tools="COAR_DOCUMENT_VIEWER_ALL_TOOLS.filter(t => t !== 'print' && t !== 'download')"
+/>
+```
+
+Use the section toggle when you want to drop a category cleanly. Use `tools` when you need precise positional control — e.g. moving search to the start, or placing the page-input between zoom and rotation.
+
+## Toolbar position
+
+`toolbarPosition` controls where the toolbar sits relative to the page area:
+
+```vue
+<CoarDocumentViewer :source="src" toolbar-position="left" />
+```
+
+| Value | Layout |
+|---|---|
+| `'top'` (default) | Horizontal bar above the page area |
+| `'bottom'` | Horizontal bar below the page area |
+| `'left'` | Vertical rail to the left of the page area |
+| `'right'` | Vertical rail to the right of the page area |
+
+Vertical rails ('left' / 'right') still use the same `tools` array — buttons just stack vertically and the `'separator'` pseudo-tool renders as a horizontal divider instead of a vertical one.

package/skills/cocoar-vue-ui/references/components/drag-drop.md

@@ -0,0 +1,267 @@
+<!-- Generated from apps/docs/components/drag-drop.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Drag & Drop
+
+`useDragDrop` is a small, framework-agnostic composable wrapping HTML5 drag-and-drop with the same group / accept / canDrop semantics used by [`CoarListbox`](./listbox.md#drag-drop-between-lists) — but usable from any Vue component. It takes care of the fiddly bits (module-level payload registry, group matching, directional whitelists, source-side cleanup on accept) so your component only needs to wire events.
+
+```ts
+import { useDragDrop } from '@cocoar/vue-ui';
+```
+
+## Standalone example — custom Kanban board
+
+The demo below is built from plain `<div>` columns + cards, using `useDragDrop` directly — **no Listbox involved**. Cards flow **Backlog → In progress → Done**; Backlog accepts no drops (not a target), Done accepts from everywhere, In progress only accepts from Backlog:
+
+**Demo — `drag-drop/demos/StandaloneKanban.vue`**
+
+```vue
+<template>
+  <div class="board">
+    <KanbanColumn
+      v-for="col in columns"
+      :key="col.id"
+      :title="col.title"
+      :cards="col.cards"
+      :column-id="col.id"
+      :drag-accept="col.dragAccept"
+      @items-add="(p) => onAdd(col.id, p)"
+      @items-remove="(p) => onRemove(col.id, p)"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import KanbanColumn from './KanbanColumn.vue';
+
+export interface Card { id: string; title: string; priority: 'low' | 'med' | 'high' }
+
+const columns = ref([
+  {
+    id: 'backlog',
+    title: 'Backlog',
+    // Empty whitelist = accept nothing. Keeps Backlog as a source-only column.
+    dragAccept: [] as string[] | undefined,
+    cards: [
+      { id: 'c1', title: 'Research virtualization', priority: 'med' },
+      { id: 'c2', title: 'Audit type coverage', priority: 'low' },
+      { id: 'c3', title: 'Drop indicator UX', priority: 'med' },
+    ] as Card[],
+  },
+  {
+    id: 'doing',
+    title: 'In progress',
+    dragAccept: ['backlog'],
+    cards: [{ id: 'c4', title: 'Release Listbox v2', priority: 'high' }] as Card[],
+  },
+  {
+    id: 'done',
+    title: 'Done',
+    dragAccept: ['backlog', 'doing'],
+    cards: [{ id: 'c5', title: 'Ship Virtual List page', priority: 'med' }] as Card[],
+  },
+]);
+
+function onAdd(colId: string, p: { items: readonly Card[] }) {
+  const col = columns.value.find((c) => c.id === colId);
+  if (!col) return;
+  col.cards = [...col.cards, ...p.items];
+}
+
+function onRemove(colId: string, p: { items: readonly Card[] }) {
+  const col = columns.value.find((c) => c.id === colId);
+  if (!col) return;
+  const removing = new Set(p.items.map((i) => i.id));
+  col.cards = col.cards.filter((c) => !removing.has(c.id));
+}
+</script>
+
+<style scoped>
+.board { display: flex; gap: 16px; min-height: 340px; }
+</style>
+```
+
+Each column is one component that wires the composable's `startDrag` / `endDrag` to its cards and `onDragOver` / `onDragLeave` / `onDrop` to itself:
+
+```vue
+<script setup lang="ts">
+import { useDragDrop } from '@cocoar/vue-ui'
+
+const dnd = useDragDrop<Card>({
+  dragId: () => props.columnId,
+  dragGroup: 'kanban',
+  dragAccept: () => props.dragAccept,  // whitelist of upstream columns
+  onDropAccept: ({ items }) => emit('items-add', { items }),
+  onItemsRemove: ({ items }) => emit('items-remove', { items }),
+})
+</script>
+
+<template>
+  <div
+    :class="{ 'over': dnd.isDragOver.value }"
+    @dragover="dnd.onDragOver"
+    @dragleave="dnd.onDragLeave"
+    @drop="dnd.onDrop($event)"
+  >
+    <div
+      v-for="card in cards"
+      draggable="true"
+      @dragstart="dnd.startDrag($event, [card])"
+      @dragend="dnd.endDrag($event)"
+    >{{ card.title }}</div>
+  </div>
+</template>
+```
+
+## Matching rules
+
+A drop is accepted iff **all** of the following pass:
+
+1. **`dragGroup`** on source and target is equal (or both unset). This is the fast coarse-matching layer.
+2. **`dragAccept`** — if set on the target, the source's `dragId` must be in the list.
+3. **`canDrop`** — if provided on the target, it must return `true` for the incoming payload.
+
+Self-drops (drag within the same surface) bypass the group check but still honour `dragAccept` and `canDrop`. They also skip `onItemsRemove` — the source of truth already holds the item.
+
+Visual feedback: when any rule fails during `dragover`, the composable sets `dropEffect = 'none'` (cursor shows "not allowed") and leaves `isDragOver` false — wire that ref to a CSS class for accurate hover highlighting.
+
+## API
+
+### `UseDragDropOptions<T>`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `dragId` | `MaybeRefOrGetter<string \| undefined>` | — | Public identifier for this surface. Pair with another surface's `dragAccept` for directional flow. |
+| `dragGroup` | `MaybeRefOrGetter<string \| undefined>` | — | Shared name linking compatible surfaces. Only surfaces sharing a group exchange items. |
+| `dragAccept` | `MaybeRefOrGetter<string[] \| undefined>` | — | Whitelist of source `dragId`s this surface accepts. Unset = accept any source in the same `dragGroup`. |
+| `canDrop` | `(payload) => boolean` | — | Runtime drop validation. `payload = { items, fromId, fromGroup, fromSelf }`. |
+| `onDragStart` | `(items) => void` | — | Called after `startDrag` registers a drag. |
+| `onDragEnd` | `({ items, dropped }) => void` | — | Called on `dragend` — `dropped: true` if a target consumed the payload. |
+| `onDropAccept` | `(payload & { insertIndex }) => void` | — | Called on **this** surface when it accepts a drop. Update your source of truth here. |
+| `onItemsRemove` | `({ items, toGroup }) => void` | — | Called on the **source** surface when another target consumed its payload — fires synchronously inside the target's `drop`. Update your source of truth here. |
+
+### Return value
+
+| Field | Type | Description |
+|---|---|---|
+| `instanceId` | `string` | Stable per-instance identifier (auto-generated). |
+| `isDragOver` | `Ref<boolean>` | `true` while a compatible drag is hovering this surface. Wire to a CSS class. |
+| `isDragging` | `Ref<boolean>` | `true` while this surface is the source of an in-flight drag. |
+| `startDrag` | `(event, items) => boolean` | Call from `@dragstart` on a draggable element. Returns `false` for empty payloads. |
+| `endDrag` | `(event) => void` | Call from `@dragend`. Cleans up the session and fires `onDragEnd`. |
+| `onDragOver` | `(event) => void` | Call from the drop container's `@dragover`. |
+| `onDragLeave` | `(event) => void` | Call from `@dragleave`. Ignores events whose relatedTarget is still inside the container. |
+| `onDrop` | `(event, ctx?) => void` | Call from `@drop`. Optional `ctx.insertIndex` is forwarded to `onDropAccept`. |
+
+## Engines
+
+The same contract runs on two input engines. Pick one per surface with `engine`; the matching rules, `onDropAccept` / `onItemsRemove` and the registry are shared, so a source on one engine simply cannot reach a target on the other — but everything else stays identical.
+
+| Engine | Input | Targets | Use when |
+|---|---|---|---|
+| `'native'` (default) | HTML5 drag events | any HTML5 drop target: other Cocoar components, the OS, other apps | desktop |
+| `'pointer'` | Pointer Events — mouse, pen, touch (long-press) | surfaces using `useDragDrop` with the pointer engine | tablets, touch-first views |
+| `'auto'` | picks `'pointer'` on coarse-pointer devices | — | one setting for both |
+
+```ts
+const dnd = useDragDrop<Row>({
+  engine: 'auto',
+  dragGroup: 'rows',
+  pointer: {
+    target: containerRef,                       // registered as a pointer drop surface
+    onHover: (point, payload) => { insertAt.value = indexAt(point) },
+    onLeave: () => { insertAt.value = null },
+    onDrop: () => insertAt.value,               // becomes onDropAccept's insertIndex
+  },
+  onDropAccept, onItemsRemove,
+})
+```
+
+```vue
+<!-- source: wire pointerdown next to the native handlers; the engine decides which one acts -->
+<div :draggable="dnd.engine.value === 'native' || undefined"
+     @dragstart="dnd.startDrag($event, [row])" @dragend="dnd.endDrag"
+     @pointerdown="dnd.onPointerDown($event, [row])">
+```
+
+`onPointerDown` accepts a getter for the items, resolved when the drag actually starts (after the mouse threshold or the touch long-press). Drags never start from interactive children (buttons, inputs, links). A ghost cloned from the source follows the pointer; pass `pointer.ghost` for your own element or `false` for none. `Escape` cancels. Accepting OS files is a plain `drop` listener and is unaffected by the engine. Components exposing this choice: `CoarDataList` (`dragEngine`), `CoarListbox` / `CoarDualListbox` (`dragEngine`).
+
+## Patterns
+
+**Two-way exchange** — both surfaces draggable + droppable + same `dragGroup`:
+
+```ts
+useDragDrop({ dragGroup: 'items', onDropAccept, onItemsRemove })
+```
+
+**One-way flow** — give each source a unique `dragId`, whitelist on the target:
+
+```ts
+// source (box1)
+useDragDrop({ dragId: 'box1', dragGroup: 'flow' })
+// target (box2) — only accepts from box1
+useDragDrop({ dragGroup: 'flow', dragAccept: ['box1'], onDropAccept })
+```
+
+**Capacity limits** — reject in `canDrop`:
+
+```ts
+useDragDrop({
+  dragGroup: 'roles',
+  canDrop: ({ items }) => admins.value.length + items.length <= 5,
+  onDropAccept,
+})
+```
+
+**Integration with existing components** — `CoarListbox` uses this composable internally. If you're building a new component that needs the same drag semantics, reach for `useDragDrop` rather than reimplementing the registry.
+
+## Custom drag ghosts
+
+The browser's default drag image is a semi-transparent snapshot of the dragged element. That looks fine for small items but turns into a giant faded blob for a large card or a nested tree node. Two tiny helpers attached to the same package give you a styled ghost next to the cursor without the boilerplate of cloning, off-screen mounting, and cleanup.
+
+```ts
+import {
+  setCoarDragImageFromElement,
+  setCoarDragImageFromHtml,
+} from '@cocoar/vue-ui';
+
+function onDragStart(event: DragEvent) {
+  setCoarDragImageFromElement(event, event.currentTarget as HTMLElement);
+}
+```
+
+The helper clones the source element, sizes the clone to match the source's bounding box, mounts it off-screen (horizontally, because Chromium skips rendering elements that are entirely outside the viewport — and an unrendered ghost captures as an empty bitmap), calls `dataTransfer.setDragImage`, and removes the clone on the next macrotask so the browser has time to rasterise it.
+
+For a free-form ghost that doesn't mirror an existing element, use the HTML variant:
+
+```ts
+setCoarDragImageFromHtml(event, `
+  <div style="padding: 6px 10px; font-size: 12px;">
+    Moving 3 items
+  </div>
+`);
+```
+
+### API
+
+#### `setCoarDragImageFromElement(event, source, options?)`
+
+| Argument | Type | Description |
+|---|---|---|
+| `event` | `DragEvent` | The `dragstart` event. Called synchronously inside the handler. |
+| `source` | `HTMLElement` | Element to clone as the ghost. The live element is not visually disturbed. |
+| `options` | `CoarDragImageOptions` | Optional styling overrides. See below. |
+
+#### `setCoarDragImageFromHtml(event, html, options?)`
+
+Same contract, but builds the ghost from a raw HTML string instead of cloning an element. Useful for "drag summary" previews (e.g. "Moving 3 items") that don't correspond to a single DOM node.
+
+#### `CoarDragImageOptions`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `offsetX` | `number` | `12` | Cursor offset within the ghost, in px. |
+| `offsetY` | `number` | `12` | Cursor offset within the ghost, in px. |
+| `className` | `string` | — | CSS class applied to the generated wrapper so consumers can theme the ghost. |
+| `style` | `Partial<CSSStyleDeclaration>` | — | Inline styles merged onto the wrapper. Prefer `className` when possible. |
+| `applyDefaultStyle` | `boolean` | `true` | Apply the default rounded-corner, drop-shadow, 0.9 opacity treatment. Set to `false` when the caller handles all styling via `className`. |