npm package: @postnikdaniil/vue-annotator
Description: Visual annotation tool for Vue 2.7+/3 apps
Latest version: 0.1.9

# @postnikdaniil/vue-annotator

Dev-only visual annotation tool for Vue 2.7+ / Vue 3 apps. Click any element, leave a comment, export as markdown. No server required — everything stays in localStorage.

## Install

```bash
npm install @postnikdaniil/vue-annotator
```

## Quick Start

### Plugin (recommended)

Auto-mounts the toolbar into `document.body`:

```ts
// main.ts
import { createApp } from 'vue'
import { VueAnnotatorPlugin } from '@postnikdaniil/vue-annotator'
import App from './App.vue'

const app = createApp(App)

if (import.meta.env.DEV) {
  app.use(VueAnnotatorPlugin)
}

app.mount('#app')
```

### Component

If you need more control over placement:

```vue
<script setup>
import { VueAnnotator } from '@postnikdaniil/vue-annotator'
</script>

<template>
  <VueAnnotator />
</template>
```

### Vue 2.7

Works the same way via `vue-demi`:

```js
// main.js
import Vue from 'vue'
import { VueAnnotatorPlugin } from '@postnikdaniil/vue-annotator'

if (process.env.NODE_ENV === 'development') {
  Vue.use(VueAnnotatorPlugin)
}
```

## How It Works

1. Click the inspect button (target icon) in the toolbar
2. Hover over any element — it highlights with component name tooltip
3. Click an element to select it
4. Type your annotation in the popup, press **Cmd/Ctrl+Enter** or click **Add**
5. Numbered markers appear on annotated elements
6. Click **Export** to copy all annotations as markdown

### Toolbar Buttons

| Button | Action |
|--------|--------|
| Target | Toggle inspect mode |
| Clipboard | Export annotations to clipboard as markdown |
| Trash | Clear all annotations on current page |
| Minus | Hide toolbar (click eye icon to restore) |

### Keyboard Shortcuts

- **Escape** — cancel inspect mode or close popup
- **Cmd/Ctrl+Enter** — submit annotation

## Export Format

Annotations are exported as markdown:

```markdown
## Annotations (2)

1. <ProductCard> (div.product-card, section.catalog > div.product-card:nth-child(1)): "increase bottom padding"
2. <AddToCartButton> (button.btn-primary "Buy", div.product > button.btn-primary): "make it green"
```

Each line includes: component name, element description, CSS selector, and your comment.

## Features

- **Vue 2.7+ and Vue 3** — uses `vue-demi` for compatibility
- **Component detection** — shows Vue component names and hierarchy (`<App> -> <ProductPage> -> <AddToCartButton>`)
- **Unique selectors** — generates CSS selectors with `:nth-child()` for disambiguation
- **localStorage persistence** — annotations survive page reload
- **SPA navigation** — annotations are scoped per route (pathname + hash)
- **Detached annotations** — if an annotated element disappears from DOM, annotations are shown in a separate panel
- **Self-contained** — CSS-in-JS, no external stylesheets needed
- **Dev-only** — designed to be tree-shaken in production builds

## API

### Exports

```ts
import { VueAnnotator, VueAnnotatorPlugin } from '@postnikdaniil/vue-annotator'
import type { Annotation, InspectorTarget } from '@postnikdaniil/vue-annotator'
```

### `VueAnnotatorPlugin`

Vue plugin. Call `app.use(VueAnnotatorPlugin)` to auto-mount the toolbar.

### `VueAnnotator`

The toolbar Vue component. Use directly if you need manual control over mounting.

### Types

```ts
interface Annotation {
  id: string
  comment: string
  element: string        // "button.btn-primary"
  elementPath: string    // unique CSS selector
  componentName: string  // "<AddToCartButton>"
  componentChain: string // "<App> -> <ProductPage> -> <AddToCartButton>"
  timestamp: number
}

interface InspectorTarget {
  el: HTMLElement
  element: string
  elementPath: string
  componentName: string
  componentChain: string
  rect: DOMRect
}
```

## Requirements

- Vue >= 2.7 or Vue >= 3.0
- Browser with `localStorage` support
- **Dev mode only** — Vue component detection relies on internal properties (`__vueParentComponent`, `__vue__`) that are stripped in production builds

## License

MIT