vue-pointing-bubble 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexey Murz Korepov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,418 @@
-# Temporary Holding Version
+# vue-pointing-bubble
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Vue 3 callout for a speech bubble, speech balloon, popover with arrow,
+annotated popover, or coachmark. The tail tip points **exactly** at an absolute
+`(x, y)` coordinate or at the center of a DOM element.
+
+The box is a regular element that you style with CSS. The tail is a small SVG
+triangle in the same colors that covers the box border where it attaches, so there
+is no seam, and its tip lands on the target pixel with zero offset.
+
+![Screenshot of the pointing bubble simple demo layout.](docs/screenshot.png)
+
+**[Live demo](https://murznn.github.io/vue-pointing-bubble/)**
+
+## Features
+
+- Point at absolute coordinates (`{ x, y }`) or at a DOM element / component instance.
+- Automatic quadrant placement that keeps the bubble inside the container and the visible viewport, a fixed quadrant, or a box positioned by your own CSS.
+- Seamless tail with rounded box corners and an optional drop shadow that covers both.
+- Any content through the default slot. The bubble resizes to fit it.
+- Style the bubble with regular `class` and `style`, including Tailwind CSS or UnoCSS utility classes: size, padding, position, background, border, corner radius, and `z-index`.
+- Glides smoothly to a new target, and to a new size when its content changes.
+- Follows window resize, scrolling, and container resize.
+- No CSS file to import and no dependency on Tailwind or any other CSS framework.
+- Ships as an ES module, a UMD bundle for `<script>` tags, the raw `.vue` SFC, and a [shadcn-vue](https://www.shadcn-vue.com/docs/registry) registry item. Includes TypeScript declarations.
+
+## Installation
+
+```bash
+npm install vue-pointing-bubble
+```
+
+You can also install it straight from GitHub:
+
+```bash
+npm install github:MurzNN/vue-pointing-bubble
+```
+
+Vue `^3.3` is a peer dependency.
+
+### shadcn-vue
+
+This repository is a shadcn-vue registry. In a project that already has `components.json`, install the component with:
+
+```bash
+pnpm dlx shadcn-vue@latest add MurzNN/vue-pointing-bubble/pointing-bubble
+```
+
+The CLI reads [`registry.json`](registry.json) from the default branch and writes the component into the project's UI directory. With the default alias, that is `src/components/ui/pointing-bubble`:
+
+```vue
+<script setup>
+import { PointingBubble } from '@/components/ui/pointing-bubble'
+</script>
+
+<template>
+  <PointingBubble :target="{ x: 320, y: 180 }">
+    Look here.
+  </PointingBubble>
+</template>
+```
+
+Append `#ref` to install from a branch, tag, or commit, for example `MurzNN/vue-pointing-bubble/pointing-bubble#v0.1.0`.
+
+The same item is also published with the demo, so you can register a short name in `components.json`:
+
+```json
+{
+  "registries": {
+    "@vue-pointing-bubble": "https://murznn.github.io/vue-pointing-bubble/r/{name}.json"
+  }
+}
+```
+
+```bash
+pnpm dlx shadcn-vue@latest add @vue-pointing-bubble/pointing-bubble
+```
+
+List what the repository publishes with `pnpm dlx shadcn-vue@latest search MurzNN/vue-pointing-bubble`.
+
+## Usage
+
+The component fills its nearest **positioned** ancestor (`position: relative`,
+`absolute`, or `fixed`) with an overlay. Coordinates are measured relative to
+that ancestor.
+
+### Pointing at page coordinates
+
+To point at absolute coordinates on the page, wrap the bubble in a layer that
+covers the page. Because the layer is `position: absolute`, it takes no space in
+the layout, so the page content stays where it is. Add `pointer-events: none` so the
+layer doesn't block clicks on the elements under it.
+
+```vue
+<script setup>
+import { PointingBubble } from 'vue-pointing-bubble'
+</script>
+
+<template>
+  <div style="position: absolute; inset: 0; pointer-events: none">
+    <PointingBubble :target="{ x: 320, y: 180 }">
+      <strong>Look here!</strong>
+      <p>The tail tip is exactly at (320, 180) on the page.</p>
+    </PointingBubble>
+  </div>
+</template>
+```
+
+The coordinates are measured from the top-left corner of the document, the same way
+as `event.pageX` and `event.pageY`, and the bubble scrolls together with the page.
+This works only if none of the layer's ancestors is positioned. Otherwise, the
+coordinates are measured from that ancestor. To be safe, render the layer with
+`<Teleport to="body">`.
+
+If you want viewport coordinates instead (`event.clientX` and `event.clientY`), with
+the bubble staying in place while the page scrolls, use `position: fixed` for the
+layer.
+
+### Pointing at coordinates inside a container
+
+To point at a spot inside a specific element, such as an image or a chart, put the
+bubble into a positioned container. The coordinates are then measured from the
+container's top-left corner, so they stay correct wherever the container is on the
+page.
+
+```vue
+<template>
+  <div style="position: relative; width: 600px">
+    <img src="/floor-plan.png" width="600" height="400" alt="Floor plan">
+
+    <PointingBubble :target="{ x: 420, y: 150 }">
+      The kitchen is here.
+    </PointingBubble>
+  </div>
+</template>
+```
+
+Here, `(420, 150)` is a point on the image. If the image moves, for example because
+of text added above it, the bubble moves with it.
+
+### Pointing at an element
+
+Pass a template ref, either a DOM element or a component instance. The tip
+attaches to the center of the element. This is the usual setup for a coachmark
+or a popover with arrow next to a control.
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { PointingBubble } from 'vue-pointing-bubble'
+
+const button = ref(null)
+</script>
+
+<template>
+  <div style="position: relative; height: 400px">
+    <button ref="button">Save</button>
+
+    <PointingBubble :target="button" placement="bottom-right">
+      Click here to save your changes.
+    </PointingBubble>
+  </div>
+</template>
+```
+
+By default the tip lands on the element's center. To stop it at the element's
+border instead, so it doesn't cover the button's label, add `target-anchor="edge"`:
+
+```vue
+<PointingBubble :target="button" target-anchor="edge">
+  Click here to save your changes.
+</PointingBubble>
+```
+
+With automatic placement, the tip then touches the middle of the element's top or
+bottom edge, whichever faces the box. With `placement="manual"`, it touches the
+point of the element's border nearest to the center of the box.
+
+You can also pass a CSS selector instead of a ref, which is handy when the element
+belongs to another component or isn't rendered by Vue at all:
+
+```vue
+<PointingBubble target="#save-button" target-anchor="edge">
+  Click here to save your changes.
+</PointingBubble>
+```
+
+The selector is looked up in the whole document with `document.querySelector`, and
+the first match is used. It's looked up again on every update, so the bubble finds
+an element that appears later, after a re-render, resize, or scroll, or when you
+call `update()`. While nothing matches, the bubble is hidden.
+
+### Sizing and styling the box
+
+`class`, `style`, and event listeners that you put on `<PointingBubble>` go to the
+box with your content, the same way as on a regular `<div>`. The tail is attached
+to whatever size the box ends up with.
+
+```vue
+<PointingBubble :target="button" class="w-64 p-3 text-sm">
+  Click here to save your changes.
+</PointingBubble>
+```
+
+By default, the box fits its content, wraps the text at `maxWidth` (280px), and has
+`padding` of 8px, a white background, a gray border, and 8px rounded corners.
+These defaults come from a tiny stylesheet that the component adds to the page,
+with zero specificity, so anything your classes or `style` set wins, including
+zero values like `p-0` or `rounded-none`.
+
+If you give the box a fixed height, content that doesn't fit is clipped. Add
+`overflow-auto` (or `overflow: auto`) to make it scrollable instead.
+
+The box paints itself, so any CSS works on it: gradients, per-corner radii,
+`hover:` variants, and so on. The tail takes these properties from the box:
+
+| CSS of the box                          | Effect on the tail                        |
+| --------------------------------------- | ----------------------------------------- |
+| `background-color`                      | Fill color.                               |
+| `border-top-width`, `border-top-color`  | Outline width and color.                  |
+| `border-top-left-radius`                | Keeps the tail away from rounded corners. |
+| `z-index`                               | Stacking order of the whole bubble (`30` if unset). |
+
+```vue
+<PointingBubble :target="button" class="p-3 rounded-xl bg-yellow-100 border-2 border-yellow-600">
+  Click here to save your changes.
+</PointingBubble>
+
+<!-- The same without a CSS framework -->
+<PointingBubble
+  :target="button"
+  style="padding: 12px; border-radius: 12px; background: #fef9c3; border: 2px solid #ca8a04"
+>
+  Click here to save your changes.
+</PointingBubble>
+```
+
+The tail is a solid color, so with a gradient or background image, pick a
+`background-color` that blends with it. The tail is updated on a re-render and on
+resize. If the box colors change without one, for example on hover or when you
+toggle dark mode, call `update()`.
+
+The `shadow` prop adds a drop shadow that follows the box and the tail together. A
+`box-shadow` of your own only applies to the box.
+
+### Placing the box yourself
+
+By default, the box is placed next to the tip automatically. With
+`placement="manual"`, you position the box yourself with `left` and `top`, set by
+classes or by `style`, relative to the positioned parent. The tail still points
+exactly at `target`, from whichever side of the box faces it. This works well for
+an annotated popover on a diagram, or for labels the user can drag around.
+
+```vue
+<template>
+  <div style="position: relative; height: 300px">
+    <img ref="photo" src="/laptop.png" style="margin: 80px auto; display: block">
+
+    <PointingBubble :target="photo" placement="manual" class="left-4 top-4 w-44">
+      This label stays in the top-left corner.
+    </PointingBubble>
+  </div>
+</template>
+```
+
+Any CSS unit works, for example `class="left-[7em] top-[5em]"` in Tailwind CSS, or
+`class="left-7em top-5em"` in UnoCSS. Without a framework, use `style`:
+
+```vue
+<PointingBubble :target="photo" placement="manual" :style="{ left: x + 'px', top: y + 'px' }">
+  Drag me around.
+</PointingBubble>
+```
+
+You don't need a class like `absolute`, because the box is always absolutely
+positioned. Without `left` and `top`, it sits in the top-left corner of the parent.
+The width works as in automatic mode: the box fits its content and wraps at
+`max-width` unless you set a width. In manual mode, the box itself doesn't glide
+when you move it, only the tail does. If the box moves without a resize or a change
+of its classes or style, such as during a CSS transition, call `update()`.
+
+### A box without a tail
+
+Leave out `target`, or set it to `null`, to draw just the box, with no tail. The
+box is then a regular element in the normal document flow: it isn't absolutely
+positioned and doesn't need a positioned parent. It sits on its own line inside
+the component's root block and is as wide as its content, up to the parent's
+width. The 280px default `maxWidth` doesn't apply here, but an explicit
+`:max-width`, or a width or max-width from your CSS, does. Margins on the box work as usual, for example `mx-auto` to
+center it. Opacity and transforms set on the component's root element, such as
+by Slidev's `v-click`, apply to the box as well. In a flex or grid parent, the
+root is the flex or grid item, so put item classes like `flex-1` on a wrapper
+element. This is handy for a step that doesn't point at anything, such as the
+welcome step of a guided tour:
+
+```vue
+<PointingBubble :target="step.element" class="mt-4">
+  {{ step.text }}
+</PointingBubble>
+```
+
+When `target` changes from `null` to an element, the box leaves the flow and appears
+next to the element, with a tail, and comes back when it changes to `null`. To hide
+the bubble completely, use `v-if`. Margins only apply to this mode and to
+`placement="manual"`; a bubble placed automatically next to its target ignores them.
+
+### Global registration
+
+```js
+import { createApp } from 'vue'
+import VuePointingBubble from 'vue-pointing-bubble'
+import App from './App.vue'
+
+createApp(App)
+  .use(VuePointingBubble) // registers <PointingBubble>
+  // .use(VuePointingBubble, { name: 'Callout' }) // or under a custom name
+  .mount('#app')
+```
+
+The component is also exported under the alias `Callout`:
+
+```js
+import { Callout } from 'vue-pointing-bubble'
+```
+
+### Using the raw SFC
+
+If you prefer to compile the component with your own build pipeline:
+
+```js
+import PointingBubble from 'vue-pointing-bubble/PointingBubble.vue'
+```
+
+### Without a build step (CDN)
+
+```html
+<script src="https://unpkg.com/vue@3/dist/vue.global.prod.js"></script>
+<script src="https://unpkg.com/vue-pointing-bubble"></script>
+
+<div id="app">
+  <div style="position: absolute; inset: 0; pointer-events: none">
+    <pointing-bubble :target="{ x: 200, y: 120 }">Hello!</pointing-bubble>
+  </div>
+</div>
+
+<script>
+  Vue.createApp({})
+    .component('PointingBubble', VuePointingBubble.PointingBubble)
+    .mount('#app')
+</script>
+```
+
+## Props
+
+| Prop                 | Type                                  | Default     | Description |
+| -------------------- | ------------------------------------- | ----------- | ----------- |
+| `target`             | `{ x, y }` \| `Element` \| component \| `string` | `null` | What the tip points at. Coordinates are relative to the positioned parent. A string is a CSS selector, looked up with `document.querySelector`; while it matches nothing, the bubble is hidden. Elements are pointed at their center, or at their border with `targetAnchor="edge"`. When `null`, only the box is drawn, without a tail, as a regular element in the document flow. Use `v-if` to hide the bubble entirely. |
+| `placement`          | `'auto'` \| `'top-left'` \| `'top-right'` \| `'bottom-left'` \| `'bottom-right'` \| `'manual'` | `'auto'` | Where the box sits relative to the tip. `auto` chooses the quadrant facing the center of the container. It flips to the other side if the bubble would go outside the viewport, such as after scrolling, and fits on the other side. `manual` leaves the position to the `left` and `top` that you set with `class` or `style`. The tail then grows from whichever side of the box faces the tip. |
+| `targetAnchor`       | `'center'` \| `'edge'`                | `'center'`  | For element targets, where the tip lands. `center` is the element's center. `edge` is the element's border facing the box: the middle of the top or bottom edge with automatic placement, or the nearest border point with `manual` placement. Ignored for coordinate targets. |
+| `maxWidth`           | `number`                              | `280`       | Width in px at which content wraps, unless your `class` or `style` sets a width or max-width. Without a `target`, there's no default: the box is only limited by its parent's width. |
+| `tailLength`         | `number`                              | `45`        | Horizontal and vertical offset in px from the tip to the box corner. |
+| `tailBaseWidth`      | `number`                              | `24`        | Width in px of the tail where it joins the box. |
+| `padding`            | `number` \| `string`                  | `8`         | Padding of the box (a number means px), unless your `class` or `style` sets a padding. |
+| `shadow`             | `boolean`                             | `true`      | Whether to render a drop shadow under the box and the tail. |
+| `transitionDuration` | `number`                              | `200`       | Duration in ms of the glide animation when the target, size, or placement changes. The box and the tail move together. `0` disables it, and it is skipped when the user prefers reduced motion. Consider `0` while the target follows the mouse, such as during dragging. |
+
+## Slots
+
+| Slot      | Props                   | Description |
+| --------- | ----------------------- | ----------- |
+| `default` | `{ placement, tip }`    | Bubble content. `placement` is the resolved quadrant, `'manual'`, or `'none'` without a target, and `tip` is the tip position `{ x, y }` in container pixels, or `null` without a target. |
+
+## Exposed methods
+
+| Name       | Description |
+| ---------- | ----------- |
+| `update()` | Recomputes the tip position, remeasures the box, and rereads its colors for the tail. Call it if the target element or a manually placed box moved, or the box colors changed, without a window resize, scroll, or re-render, such as after an animation or a theme switch. |
+
+## Styling
+
+The overlay elements have stable class names you can target from your own CSS:
+
+- `.vue-pointing-bubble`: the root element, with a `data-placement` attribute holding the resolved quadrant. With a `target`, it's the full-size overlay; without one, it's a plain block around the box, with `data-placement="none"`.
+- `.vue-pointing-bubble__inner`: the box with the slot content. It receives the `class`, `style`, and listeners from `<PointingBubble>`.
+- `.vue-pointing-bubble__svg`: the SVG layer with the tail. It isn't rendered without a `target`.
+- `.vue-pointing-bubble__path`: the tail path.
+
+## Development
+
+```bash
+npm install
+npm run dev:demo       # start the demo dev server with hot reload (`npm run dev` is an alias)
+npm run build          # build the library into dist/
+npm run registry:build # write the shadcn-vue registry JSON into demo/public/r/
+npm run build:demo     # build the registry JSON and the demo into demo-dist/
+npm run preview:demo   # serve the built demo
+npm test               # build the demo and run the browser tests against it
+```
+
+The tests in [`tests/demo.spec.js`](tests/demo.spec.js) use
+[Playwright](https://playwright.dev/) and drive the demo page itself: they hover
+the hint buttons, walk through the tour, click the chart, and drag the labels,
+checking that each tail tip lands exactly on its target and that the box without a
+target stays in the page flow. They run in the installed Google Chrome; if you
+don't have it, install it with `npx playwright install chrome`.
+
+The component source is [`registry/ui/pointing-bubble/PointingBubble.vue`](registry/ui/pointing-bubble/PointingBubble.vue). The library and the shadcn-vue registry install the same file. The demo (`demo/Demo.vue`) imports it through `src/index.js`, so editing the demo or the component hot-reloads in the browser. It shows hover hints,
+a guided tour with a coachmark, an annotated popover on a picture, and draggable
+labels with custom box positions.
+
+The workflow [`.github/workflows/deploy-demo.yml`](.github/workflows/deploy-demo.yml)
+runs the tests on every pull request and push to `main`, and on `main`, once they
+pass, deploys the demo to GitHub Pages. To enable it, open **Settings → Pages** in the repository and
+set **Source** to **GitHub Actions**.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import type { DefineComponent, Plugin, ComponentPublicInstance } from 'vue'
+
+export type PointingBubblePlacement =
+  | 'auto'
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-right'
+  | 'manual'
+
+export interface PointingBubblePoint {
+  x: number
+  y: number
+}
+
+export type PointingBubbleTarget =
+  | PointingBubblePoint
+  | Element
+  | ComponentPublicInstance
+  /** A CSS selector, looked up with `document.querySelector`. */
+  | string
+  | null
+
+export interface PointingBubbleProps {
+  target?: PointingBubbleTarget
+  placement?: PointingBubblePlacement
+  targetAnchor?: 'center' | 'edge'
+  maxWidth?: number
+  tailLength?: number
+  tailBaseWidth?: number
+  padding?: number | string
+  shadow?: boolean
+  transitionDuration?: number
+}
+
+export declare const PointingBubble: DefineComponent<PointingBubbleProps>
+export declare const Callout: typeof PointingBubble
+
+export interface PointingBubblePluginOptions {
+  name?: string
+}
+
+declare const plugin: Plugin<[PointingBubblePluginOptions?]>
+export default plugin

package/dist/vue-pointing-bubble.js

@@ -0,0 +1,310 @@
+import { computed as e, createCommentVNode as t, createElementBlock as n, createElementVNode as r, mergeProps as i, normalizeStyle as a, onBeforeUnmount as o, onMounted as s, onUpdated as c, openBlock as l, ref as u, renderSlot as d, watch as f } from "vue";
+//#region registry/ui/pointing-bubble/PointingBubble.vue
+var p = ["data-placement"], m = ["d", "fill"], h = [
+	"d",
+	"stroke",
+	"stroke-width"
+], g = ":where(.vue-pointing-bubble__inner) {\n  box-sizing: border-box;\n  width: var(--vpb-width, max-content);\n  max-width: var(--vpb-max-width, none);\n  padding: var(--vpb-padding);\n  background: white;\n  border: 2px solid gray;\n  border-radius: 8px;\n}", _ = "drop-shadow(0 6px 8px rgba(0, 0, 0, 0.25))", v = 30, y = 280, b = [
+	"tx",
+	"ty",
+	"bx",
+	"by"
+], x = ["tx", "ty"], S = () => {
+	if (typeof document > "u" || document.getElementById("vue-pointing-bubble-styles")) return;
+	let e = document.createElement("style");
+	e.id = "vue-pointing-bubble-styles", e.textContent = g, document.head.prepend(e);
+}, C = /*@__PURE__*/ Object.assign({ inheritAttrs: !1 }, {
+	__name: "PointingBubble",
+	props: {
+		target: {
+			type: [
+				Object,
+				String,
+				typeof Element < "u" ? Element : Object
+			],
+			default: null
+		},
+		placement: {
+			type: String,
+			default: "auto",
+			validator: (e) => [
+				"auto",
+				"top-left",
+				"top-right",
+				"bottom-left",
+				"bottom-right",
+				"manual"
+			].includes(e)
+		},
+		targetAnchor: {
+			type: String,
+			default: "center",
+			validator: (e) => ["center", "edge"].includes(e)
+		},
+		maxWidth: {
+			type: Number,
+			default: void 0
+		},
+		tailLength: {
+			type: Number,
+			default: 45
+		},
+		tailBaseWidth: {
+			type: Number,
+			default: 24
+		},
+		padding: {
+			type: [Number, String],
+			default: 8
+		},
+		shadow: {
+			type: Boolean,
+			default: !0
+		},
+		transitionDuration: {
+			type: Number,
+			default: 200
+		}
+	},
+	setup(g, { expose: C }) {
+		let w = g;
+		S();
+		let T = u(null), E = u(null), D = u(null), O = u(null), k = u(null), A = u({
+			left: 0,
+			top: 0,
+			width: 0,
+			height: 0,
+			scaleX: 1,
+			scaleY: 1,
+			viewportWidth: 0,
+			viewportHeight: 0
+		}), j = e(() => w.placement === "manual"), M = (e, t) => !!e && !!t && Object.keys(e).every((n) => e[n] === t[n]), N = (e) => typeof Element > "u" || !e ? null : typeof e == "string" ? document.querySelector(e) : e instanceof Element ? e : e.$el instanceof Element ? e.$el : null, P = () => {
+			let e = T.value;
+			if (!w.target || !e) {
+				D.value = null;
+				return;
+			}
+			let t = e.getBoundingClientRect(), n = e.offsetWidth ? t.width / e.offsetWidth : 1, r = e.offsetHeight ? t.height / e.offsetHeight : 1;
+			A.value = {
+				left: t.left,
+				top: t.top,
+				width: e.offsetWidth,
+				height: e.offsetHeight,
+				scaleX: n,
+				scaleY: r,
+				viewportWidth: window.innerWidth,
+				viewportHeight: window.innerHeight
+			};
+			let i = N(w.target);
+			if (i) {
+				let e = i.getBoundingClientRect(), a = {
+					left: (e.left - t.left) / n,
+					top: (e.top - t.top) / r,
+					right: (e.right - t.left) / n,
+					bottom: (e.bottom - t.top) / r
+				};
+				M(a, O.value) || (O.value = a), D.value = {
+					x: (a.left + a.right) / 2,
+					y: (a.top + a.bottom) / 2
+				};
+			} else typeof w.target.x == "number" && typeof w.target.y == "number" ? (O.value = null, D.value = {
+				x: w.target.x,
+				y: w.target.y
+			}) : (O.value = null, D.value = null);
+			F();
+		};
+		f(() => [
+			w.target,
+			w.target?.x,
+			w.target?.y
+		], P, { flush: "post" });
+		let F = () => {
+			let e = E.value;
+			if (!e || !w.target) return;
+			let t = getComputedStyle(e), n = {
+				x: j.value ? e.offsetLeft : 0,
+				y: j.value ? e.offsetTop : 0,
+				width: e.offsetWidth,
+				height: e.offsetHeight,
+				fill: t.backgroundColor,
+				stroke: t.borderTopColor,
+				strokeWidth: parseFloat(t.borderTopWidth) || 0,
+				radius: t.borderTopLeftRadius,
+				zIndex: t.zIndex
+			};
+			M(n, k.value) || (k.value = n);
+		};
+		c(F);
+		let I = e(() => {
+			let e = k.value;
+			if (!D.value || !e?.width || !e?.height) return null;
+			let { width: t, height: n } = e, { x: r, y: i } = D.value, a = w.tailLength, o = A.value, s = w.targetAnchor === "edge" ? O.value : null;
+			if (j.value) {
+				if (s) {
+					let r = e.x + t / 2, i = e.y + n / 2;
+					if (!(r >= s.left && r <= s.right && i >= s.top && i <= s.bottom)) return {
+						placement: "manual",
+						tx: Math.min(s.right, Math.max(s.left, r)),
+						ty: Math.min(s.bottom, Math.max(s.top, i)),
+						bx: e.x,
+						by: e.y,
+						w: t,
+						h: n
+					};
+				}
+				return {
+					placement: "manual",
+					tx: r,
+					ty: i,
+					bx: e.x,
+					by: e.y,
+					w: t,
+					h: n
+				};
+			}
+			let c = (e) => s ? e === "top" ? s.top : s.bottom : i, l = w.placement;
+			if (l === "auto") {
+				let e = i > (o.height || 600) / 2 ? "top" : "bottom", s = r > (o.width || 800) / 2 ? "left" : "right", { scaleX: u, scaleY: d } = o;
+				if (o.viewportHeight) {
+					let t = o.top + (c("top") - n - a) * d >= 0, r = o.top + (c("bottom") + n + a) * d <= o.viewportHeight;
+					e === "top" && !t && r ? e = "bottom" : e === "bottom" && !r && t && (e = "top");
+				}
+				if (o.viewportWidth) {
+					let e = o.left + (r - t - a) * u >= 0, n = o.left + (r + t + a) * u <= o.viewportWidth;
+					s === "left" && !e && n ? s = "right" : s === "right" && !n && e && (s = "left");
+				}
+				l = `${e}-${s}`;
+			}
+			let [u, d] = l.split("-"), f = c(u);
+			return {
+				placement: l,
+				tx: r,
+				ty: f,
+				bx: d === "left" ? r - t - a : r + a,
+				by: u === "top" ? f - n - a : f + a,
+				w: t,
+				h: n
+			};
+		}), L = u(null), R = 0, z = () => typeof matchMedia < "u" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+		f(I, (e) => {
+			typeof cancelAnimationFrame < "u" && cancelAnimationFrame(R);
+			let t = L.value, n = w.transitionDuration;
+			if (!e || !t || n <= 0 || typeof requestAnimationFrame > "u" || z()) {
+				L.value = e;
+				return;
+			}
+			let r = performance.now(), i = (a) => {
+				let o = Math.min(1, (a - r) / n), s = 1 - (1 - o) ** 3, c = { ...e }, l = e.placement === "manual" ? x : b;
+				for (let n of l) c[n] = t[n] + (e[n] - t[n]) * s;
+				L.value = c, o < 1 && (R = requestAnimationFrame(i));
+			};
+			R = requestAnimationFrame(i);
+		}, { immediate: !0 });
+		let B = null;
+		s(() => {
+			window.addEventListener("resize", P), window.addEventListener("scroll", P, !0), typeof ResizeObserver < "u" && (B = new ResizeObserver(P), B.observe(T.value), B.observe(E.value)), P();
+		}), o(() => {
+			window.removeEventListener("resize", P), window.removeEventListener("scroll", P, !0), B?.disconnect(), typeof cancelAnimationFrame < "u" && cancelAnimationFrame(R);
+		});
+		let V = e(() => {
+			let e = L.value;
+			if (!e) return null;
+			let { placement: t, tx: n, ty: r, bx: i, by: a, w: o, h: s } = e, c = k.value.strokeWidth, l = k.value.radius, u = parseFloat(l) * (l.endsWith("%") ? Math.min(o, s) / 100 : 1) || 0, d = w.tailBaseWidth / 2, f = (e, t, n) => t > n ? (t + n) / 2 : Math.min(n, Math.max(t, e)), p = null, m = 0;
+			if (t === "manual") {
+				let e = Math.max(i - n, n - (i + o), 0), t = Math.max(a - r, r - (a + s), 0);
+				if (e > 0 && e >= t) p = n < i ? "left" : "right", m = r;
+				else if (t > 0) p = r < a ? "top" : "bottom", m = n;
+				else return null;
+			} else {
+				let [e, n] = t.split("-");
+				p = n === "left" ? "right" : "left", m = a + s * (e === "top" ? .65 : .35);
+			}
+			let h = (e, t) => `${e} ${t}`, g = (e, t) => `M ${h(...e)} L ${n} ${r} L ${h(...t)}`, _ = c / 2;
+			if (p === "left" || p === "right") {
+				let e = f(m, a + u + d, a + s - u - d), t = e - d, n = e + d, r = p === "left" ? i + c + 1 : i + o - c - 1, l = p === "left" ? i + _ : i + o - _;
+				return {
+					fill: g([r, t], [r, n]),
+					stroke: c ? g([l, t], [l, n]) : null
+				};
+			}
+			let v = f(m, i + u + d, i + o - u - d), y = v - d, b = v + d, x = p === "top" ? a + c + 1 : a + s - c - 1, S = p === "top" ? a + _ : a + s - _;
+			return {
+				fill: g([y, x], [b, x]),
+				stroke: c ? g([y, S], [b, S]) : null
+			};
+		}), H = e(() => w.target ? L.value?.placement : "none"), U = e(() => {
+			if (!w.target) return {};
+			let e = k.value?.zIndex;
+			return {
+				position: "absolute",
+				inset: 0,
+				pointerEvents: "none",
+				zIndex: e && e !== "auto" ? e : v,
+				filter: w.shadow ? _ : void 0
+			};
+		}), W = e(() => {
+			let e = { "--vpb-padding": typeof w.padding == "number" ? `${w.padding}px` : w.padding }, t = w.maxWidth ?? (w.target ? y : null);
+			if (t != null && (e["--vpb-max-width"] = t + "px"), !w.target) return e["--vpb-width"] = "fit-content", w.shadow && (e.filter = _), e;
+			let n = L.value;
+			return Object.assign(e, {
+				position: "absolute",
+				pointerEvents: "auto",
+				visibility: n ? "visible" : "hidden"
+			}), j.value || Object.assign(e, {
+				left: (n?.bx ?? 0) + "px",
+				top: (n?.by ?? 0) + "px",
+				margin: 0
+			}), e;
+		});
+		return C({ update: P }), (e, o) => (l(), n("div", {
+			ref_key: "rootRef",
+			ref: T,
+			class: "vue-pointing-bubble",
+			"data-placement": H.value,
+			style: a(U.value)
+		}, [r("div", i({
+			ref_key: "boxRef",
+			ref: E,
+			class: "vue-pointing-bubble__inner"
+		}, e.$attrs, { style: W.value }), [d(e.$slots, "default", {
+			placement: H.value,
+			tip: I.value ? {
+				x: I.value.tx,
+				y: I.value.ty
+			} : D.value
+		}, () => [o[0] ||= r("p", { style: {
+			margin: 0,
+			fontSize: "14px",
+			fontWeight: 600,
+			color: "#1e293b"
+		} }, "Callout content", -1)])], 16), g.target && V.value ? (l(), n("svg", {
+			key: 0,
+			class: "vue-pointing-bubble__svg",
+			style: a({
+				position: "absolute",
+				inset: 0,
+				width: "100%",
+				height: "100%",
+				overflow: "visible",
+				zIndex: k.value?.zIndex
+			})
+		}, [r("path", {
+			class: "vue-pointing-bubble__path",
+			d: V.value.fill,
+			fill: k.value.fill
+		}, null, 8, m), V.value.stroke ? (l(), n("path", {
+			key: 0,
+			class: "vue-pointing-bubble__path",
+			d: V.value.stroke,
+			fill: "none",
+			stroke: k.value.stroke,
+			"stroke-width": k.value.strokeWidth,
+			"stroke-linejoin": "round",
+			"stroke-linecap": "butt"
+		}, null, 8, h)) : t("", !0)], 4)) : t("", !0)], 12, p));
+	}
+}), w = { install(e, t = {}) {
+	e.component(t.name || "PointingBubble", C);
+} };
+//#endregion
+export { C as Callout, C as PointingBubble, w as default };

package/dist/vue-pointing-bubble.umd.cjs

@@ -0,0 +1,9 @@
+(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports,require("vue")):typeof define==`function`&&define.amd?define([`exports`,`vue`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.VuePointingBubble={},e.Vue))})(this,function(e,t){Object.defineProperties(e,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});var n=[`data-placement`],r=[`d`,`fill`],i=[`d`,`stroke`,`stroke-width`],a=`:where(.vue-pointing-bubble__inner) {
+  box-sizing: border-box;
+  width: var(--vpb-width, max-content);
+  max-width: var(--vpb-max-width, none);
+  padding: var(--vpb-padding);
+  background: white;
+  border: 2px solid gray;
+  border-radius: 8px;
+}`,o=`drop-shadow(0 6px 8px rgba(0, 0, 0, 0.25))`,s=30,c=280,l=[`tx`,`ty`,`bx`,`by`],u=[`tx`,`ty`],d=()=>{if(typeof document>`u`||document.getElementById(`vue-pointing-bubble-styles`))return;let e=document.createElement(`style`);e.id=`vue-pointing-bubble-styles`,e.textContent=a,document.head.prepend(e)},f=Object.assign({inheritAttrs:!1},{__name:`PointingBubble`,props:{target:{type:[Object,String,typeof Element<`u`?Element:Object],default:null},placement:{type:String,default:`auto`,validator:e=>[`auto`,`top-left`,`top-right`,`bottom-left`,`bottom-right`,`manual`].includes(e)},targetAnchor:{type:String,default:`center`,validator:e=>[`center`,`edge`].includes(e)},maxWidth:{type:Number,default:void 0},tailLength:{type:Number,default:45},tailBaseWidth:{type:Number,default:24},padding:{type:[Number,String],default:8},shadow:{type:Boolean,default:!0},transitionDuration:{type:Number,default:200}},setup(e,{expose:a}){let f=e;d();let p=(0,t.ref)(null),m=(0,t.ref)(null),h=(0,t.ref)(null),g=(0,t.ref)(null),_=(0,t.ref)(null),v=(0,t.ref)({left:0,top:0,width:0,height:0,scaleX:1,scaleY:1,viewportWidth:0,viewportHeight:0}),y=(0,t.computed)(()=>f.placement===`manual`),b=(e,t)=>!!e&&!!t&&Object.keys(e).every(n=>e[n]===t[n]),x=e=>typeof Element>`u`||!e?null:typeof e==`string`?document.querySelector(e):e instanceof Element?e:e.$el instanceof Element?e.$el:null,S=()=>{let e=p.value;if(!f.target||!e){h.value=null;return}let t=e.getBoundingClientRect(),n=e.offsetWidth?t.width/e.offsetWidth:1,r=e.offsetHeight?t.height/e.offsetHeight:1;v.value={left:t.left,top:t.top,width:e.offsetWidth,height:e.offsetHeight,scaleX:n,scaleY:r,viewportWidth:window.innerWidth,viewportHeight:window.innerHeight};let i=x(f.target);if(i){let e=i.getBoundingClientRect(),a={left:(e.left-t.left)/n,top:(e.top-t.top)/r,right:(e.right-t.left)/n,bottom:(e.bottom-t.top)/r};b(a,g.value)||(g.value=a),h.value={x:(a.left+a.right)/2,y:(a.top+a.bottom)/2}}else typeof f.target.x==`number`&&typeof f.target.y==`number`?(g.value=null,h.value={x:f.target.x,y:f.target.y}):(g.value=null,h.value=null);C()};(0,t.watch)(()=>[f.target,f.target?.x,f.target?.y],S,{flush:`post`});let C=()=>{let e=m.value;if(!e||!f.target)return;let t=getComputedStyle(e),n={x:y.value?e.offsetLeft:0,y:y.value?e.offsetTop:0,width:e.offsetWidth,height:e.offsetHeight,fill:t.backgroundColor,stroke:t.borderTopColor,strokeWidth:parseFloat(t.borderTopWidth)||0,radius:t.borderTopLeftRadius,zIndex:t.zIndex};b(n,_.value)||(_.value=n)};(0,t.onUpdated)(C);let w=(0,t.computed)(()=>{let e=_.value;if(!h.value||!e?.width||!e?.height)return null;let{width:t,height:n}=e,{x:r,y:i}=h.value,a=f.tailLength,o=v.value,s=f.targetAnchor===`edge`?g.value:null;if(y.value){if(s){let r=e.x+t/2,i=e.y+n/2;if(!(r>=s.left&&r<=s.right&&i>=s.top&&i<=s.bottom))return{placement:`manual`,tx:Math.min(s.right,Math.max(s.left,r)),ty:Math.min(s.bottom,Math.max(s.top,i)),bx:e.x,by:e.y,w:t,h:n}}return{placement:`manual`,tx:r,ty:i,bx:e.x,by:e.y,w:t,h:n}}let c=e=>s?e===`top`?s.top:s.bottom:i,l=f.placement;if(l===`auto`){let e=i>(o.height||600)/2?`top`:`bottom`,s=r>(o.width||800)/2?`left`:`right`,{scaleX:u,scaleY:d}=o;if(o.viewportHeight){let t=o.top+(c(`top`)-n-a)*d>=0,r=o.top+(c(`bottom`)+n+a)*d<=o.viewportHeight;e===`top`&&!t&&r?e=`bottom`:e===`bottom`&&!r&&t&&(e=`top`)}if(o.viewportWidth){let e=o.left+(r-t-a)*u>=0,n=o.left+(r+t+a)*u<=o.viewportWidth;s===`left`&&!e&&n?s=`right`:s===`right`&&!n&&e&&(s=`left`)}l=`${e}-${s}`}let[u,d]=l.split(`-`),p=c(u);return{placement:l,tx:r,ty:p,bx:d===`left`?r-t-a:r+a,by:u===`top`?p-n-a:p+a,w:t,h:n}}),T=(0,t.ref)(null),E=0,D=()=>typeof matchMedia<`u`&&matchMedia(`(prefers-reduced-motion: reduce)`).matches;(0,t.watch)(w,e=>{typeof cancelAnimationFrame<`u`&&cancelAnimationFrame(E);let t=T.value,n=f.transitionDuration;if(!e||!t||n<=0||typeof requestAnimationFrame>`u`||D()){T.value=e;return}let r=performance.now(),i=a=>{let o=Math.min(1,(a-r)/n),s=1-(1-o)**3,c={...e},d=e.placement===`manual`?u:l;for(let n of d)c[n]=t[n]+(e[n]-t[n])*s;T.value=c,o<1&&(E=requestAnimationFrame(i))};E=requestAnimationFrame(i)},{immediate:!0});let O=null;(0,t.onMounted)(()=>{window.addEventListener(`resize`,S),window.addEventListener(`scroll`,S,!0),typeof ResizeObserver<`u`&&(O=new ResizeObserver(S),O.observe(p.value),O.observe(m.value)),S()}),(0,t.onBeforeUnmount)(()=>{window.removeEventListener(`resize`,S),window.removeEventListener(`scroll`,S,!0),O?.disconnect(),typeof cancelAnimationFrame<`u`&&cancelAnimationFrame(E)});let k=(0,t.computed)(()=>{let e=T.value;if(!e)return null;let{placement:t,tx:n,ty:r,bx:i,by:a,w:o,h:s}=e,c=_.value.strokeWidth,l=_.value.radius,u=parseFloat(l)*(l.endsWith(`%`)?Math.min(o,s)/100:1)||0,d=f.tailBaseWidth/2,p=(e,t,n)=>t>n?(t+n)/2:Math.min(n,Math.max(t,e)),m=null,h=0;if(t===`manual`){let e=Math.max(i-n,n-(i+o),0),t=Math.max(a-r,r-(a+s),0);if(e>0&&e>=t)m=n<i?`left`:`right`,h=r;else if(t>0)m=r<a?`top`:`bottom`,h=n;else return null}else{let[e,n]=t.split(`-`);m=n===`left`?`right`:`left`,h=a+s*(e===`top`?.65:.35)}let g=(e,t)=>`${e} ${t}`,v=(e,t)=>`M ${g(...e)} L ${n} ${r} L ${g(...t)}`,y=c/2;if(m===`left`||m===`right`){let e=p(h,a+u+d,a+s-u-d),t=e-d,n=e+d,r=m===`left`?i+c+1:i+o-c-1,l=m===`left`?i+y:i+o-y;return{fill:v([r,t],[r,n]),stroke:c?v([l,t],[l,n]):null}}let b=p(h,i+u+d,i+o-u-d),x=b-d,S=b+d,C=m===`top`?a+c+1:a+s-c-1,w=m===`top`?a+y:a+s-y;return{fill:v([x,C],[S,C]),stroke:c?v([x,w],[S,w]):null}}),A=(0,t.computed)(()=>f.target?T.value?.placement:`none`),j=(0,t.computed)(()=>{if(!f.target)return{};let e=_.value?.zIndex;return{position:`absolute`,inset:0,pointerEvents:`none`,zIndex:e&&e!==`auto`?e:s,filter:f.shadow?o:void 0}}),M=(0,t.computed)(()=>{let e={"--vpb-padding":typeof f.padding==`number`?`${f.padding}px`:f.padding},t=f.maxWidth??(f.target?c:null);if(t!=null&&(e[`--vpb-max-width`]=t+`px`),!f.target)return e[`--vpb-width`]=`fit-content`,f.shadow&&(e.filter=o),e;let n=T.value;return Object.assign(e,{position:`absolute`,pointerEvents:`auto`,visibility:n?`visible`:`hidden`}),y.value||Object.assign(e,{left:(n?.bx??0)+`px`,top:(n?.by??0)+`px`,margin:0}),e});return a({update:S}),(a,o)=>((0,t.openBlock)(),(0,t.createElementBlock)(`div`,{ref_key:`rootRef`,ref:p,class:`vue-pointing-bubble`,"data-placement":A.value,style:(0,t.normalizeStyle)(j.value)},[(0,t.createElementVNode)(`div`,(0,t.mergeProps)({ref_key:`boxRef`,ref:m,class:`vue-pointing-bubble__inner`},a.$attrs,{style:M.value}),[(0,t.renderSlot)(a.$slots,`default`,{placement:A.value,tip:w.value?{x:w.value.tx,y:w.value.ty}:h.value},()=>[o[0]||=(0,t.createElementVNode)(`p`,{style:{margin:0,fontSize:`14px`,fontWeight:600,color:`#1e293b`}},`Callout content`,-1)])],16),e.target&&k.value?((0,t.openBlock)(),(0,t.createElementBlock)(`svg`,{key:0,class:`vue-pointing-bubble__svg`,style:(0,t.normalizeStyle)({position:`absolute`,inset:0,width:`100%`,height:`100%`,overflow:`visible`,zIndex:_.value?.zIndex})},[(0,t.createElementVNode)(`path`,{class:`vue-pointing-bubble__path`,d:k.value.fill,fill:_.value.fill},null,8,r),k.value.stroke?((0,t.openBlock)(),(0,t.createElementBlock)(`path`,{key:0,class:`vue-pointing-bubble__path`,d:k.value.stroke,fill:`none`,stroke:_.value.stroke,"stroke-width":_.value.strokeWidth,"stroke-linejoin":`round`,"stroke-linecap":`butt`},null,8,i)):(0,t.createCommentVNode)(``,!0)],4)):(0,t.createCommentVNode)(``,!0)],12,n))}});e.Callout=f,e.PointingBubble=f,e.default={install(e,t={}){e.component(t.name||`PointingBubble`,f)}}});

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "vue-pointing-bubble",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Vue 3 callout / speech bubble component whose tail points exactly at absolute (x, y) coordinates or at a DOM element.",
+  "keywords": [
+    "vue",
+    "vue3",
+    "callout",
+    "speech-bubble",
+    "tooltip",
+    "popover",
+    "pointer",
+    "svg"
+  ],
+  "author": "Alexey Murz Korepov",
+  "license": "MIT",
+  "homepage": "https://murznn.github.io/vue-pointing-bubble/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MurzNN/vue-pointing-bubble.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MurzNN/vue-pointing-bubble/issues"
+  },
+  "type": "module",
+  "main": "./dist/vue-pointing-bubble.umd.cjs",
+  "module": "./dist/vue-pointing-bubble.js",
+  "unpkg": "./dist/vue-pointing-bubble.umd.cjs",
+  "jsdelivr": "./dist/vue-pointing-bubble.umd.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/vue-pointing-bubble.js",
+      "require": "./dist/vue-pointing-bubble.umd.cjs"
+    },
+    "./PointingBubble.vue": "./registry/ui/pointing-bubble/PointingBubble.vue"
+  },
+  "files": [
+    "dist",
+    "src",
+    "registry"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "dev": "npm run dev:demo",
+    "dev:demo": "vite --config vite.demo.config.js",
+    "build": "vite build && cp src/index.d.ts dist/index.d.ts",
+    "build:demo": "npm run registry:build && vite build --config vite.demo.config.js",
+    "registry:build": "shadcn-vue build --output demo/public/r",
+    "preview:demo": "vite preview --config vite.demo.config.js",
+    "test": "playwright test",
+    "prepare": "npm run build"
+  },
+  "peerDependencies": {
+    "vue": "^3.3.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.63.0",
+    "@vitejs/plugin-vue": "^6.0.9",
+    "shadcn-vue": "^2.8.2",
+    "vite": "^8.3.2",
+    "vue": "^3.5.43"
+  }
+}

package/registry/ui/pointing-bubble/PointingBubble.vue

@@ -0,0 +1,408 @@
+<script>
+// Default look of the box. `:where()` has zero specificity, so any class or style set on the component wins.
+const CSS = `:where(.vue-pointing-bubble__inner) {
+  box-sizing: border-box;
+  width: var(--vpb-width, max-content);
+  max-width: var(--vpb-max-width, none);
+  padding: var(--vpb-padding);
+  background: white;
+  border: 2px solid gray;
+  border-radius: 8px;
+}`
+const SHADOW = 'drop-shadow(0 6px 8px rgba(0, 0, 0, 0.25))'
+const DEFAULT_Z_INDEX = 30
+const DEFAULT_MAX_WIDTH = 280
+// In manual mode CSS owns the box, so only the tail glides.
+const ANIMATED_KEYS = ['tx', 'ty', 'bx', 'by']
+const MANUAL_ANIMATED_KEYS = ['tx', 'ty']
+
+const injectStyles = () => {
+  if (typeof document === 'undefined' || document.getElementById('vue-pointing-bubble-styles')) return
+  const style = document.createElement('style')
+  style.id = 'vue-pointing-bubble-styles'
+  style.textContent = CSS
+  document.head.prepend(style)
+}
+</script>
+
+<script setup>
+/**
+ * Precision Vue 3 callout ("pointing bubble") component.
+ * The box is a regular element styled with CSS; an SVG tail is drawn from its wall,
+ * so the tip lands exactly on the target coordinate (x, y) or on a target element.
+ * Without a target, only the box is rendered, in the normal document flow.
+ */
+import { ref, computed, watch, onMounted, onUpdated, onBeforeUnmount } from 'vue'
+
+// `class`, `style`, and listeners go to the box, not to the full-size overlay.
+defineOptions({ inheritAttrs: false })
+
+const props = defineProps({
+  // DOM element, component instance, CSS selector, or { x, y } relative to the positioned parent.
+  target: {
+    type: [Object, String, typeof Element !== 'undefined' ? Element : Object],
+    default: null
+  },
+  // 'auto' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'manual'
+  // In 'manual' mode the box is positioned by CSS (left/top) on the component.
+  placement: {
+    type: String,
+    default: 'auto',
+    validator: (v) => ['auto', 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'manual'].includes(v)
+  },
+  // For element targets: 'center' points at the element's center, 'edge' at its border facing the box.
+  targetAnchor: {
+    type: String,
+    default: 'center',
+    validator: (v) => ['center', 'edge'].includes(v)
+  },
+  // Content wraps at this width (px) unless CSS on the component sets a width or max-width.
+  // Defaults to 280 with a target; without one, the box is only limited by its parent.
+  maxWidth: { type: Number, default: undefined },
+  // Distance from the box edge to the tip.
+  tailLength: { type: Number, default: 45 },
+  // Width of the tail where it attaches to the box.
+  tailBaseWidth: { type: Number, default: 24 },
+  // Used unless CSS on the component sets a padding.
+  padding: { type: [Number, String], default: 8 },
+  shadow: { type: Boolean, default: true },
+  // Duration in ms of the move animation when the target changes; 0 disables it.
+  transitionDuration: { type: Number, default: 200 }
+})
+
+injectStyles()
+
+const rootRef = ref(null)
+const boxRef = ref(null)
+const tip = ref(null)
+// Target element rect relative to the root; null for coordinate targets.
+const targetRect = ref(null)
+// Size and look of the box, read from the rendered element.
+const box = ref(null)
+// Viewport origin, local size, cumulative scale, and the viewport size.
+const frameRect = ref({ left: 0, top: 0, width: 0, height: 0, scaleX: 1, scaleY: 1, viewportWidth: 0, viewportHeight: 0 })
+const manual = computed(() => props.placement === 'manual')
+
+const sameKeys = (a, b) => !!a && !!b && Object.keys(a).every((k) => a[k] === b[k])
+
+const resolveElement = (t) => {
+  if (typeof Element === 'undefined' || !t) return null
+  // Looked up on every update, so an element that appears later is found too.
+  if (typeof t === 'string') return document.querySelector(t)
+  if (t instanceof Element) return t
+  if (t.$el instanceof Element) return t.$el
+  return null
+}
+
+const update = () => {
+  const root = rootRef.value
+  if (!props.target || !root) {
+    tip.value = null
+    return
+  }
+
+  const rootRect = root.getBoundingClientRect()
+  // getBoundingClientRect is in viewport pixels, after ancestor transforms such as
+  // Slidev's scale(). left/top and the SVG path are in the root's local CSS pixels.
+  const scaleX = root.offsetWidth ? rootRect.width / root.offsetWidth : 1
+  const scaleY = root.offsetHeight ? rootRect.height / root.offsetHeight : 1
+  frameRect.value = {
+    left: rootRect.left,
+    top: rootRect.top,
+    width: root.offsetWidth,
+    height: root.offsetHeight,
+    scaleX,
+    scaleY,
+    viewportWidth: window.innerWidth,
+    viewportHeight: window.innerHeight
+  }
+
+  const el = resolveElement(props.target)
+  if (el) {
+    const r = el.getBoundingClientRect()
+    const rect = {
+      left: (r.left - rootRect.left) / scaleX,
+      top: (r.top - rootRect.top) / scaleY,
+      right: (r.right - rootRect.left) / scaleX,
+      bottom: (r.bottom - rootRect.top) / scaleY
+    }
+    if (!sameKeys(rect, targetRect.value)) targetRect.value = rect
+    tip.value = { x: (rect.left + rect.right) / 2, y: (rect.top + rect.bottom) / 2 }
+  } else if (typeof props.target.x === 'number' && typeof props.target.y === 'number') {
+    targetRect.value = null
+    tip.value = { x: props.target.x, y: props.target.y }
+  } else {
+    // A selector that matches nothing (yet): the bubble stays hidden.
+    targetRect.value = null
+    tip.value = null
+  }
+  measure()
+}
+
+watch(() => [props.target, props.target?.x, props.target?.y], update, { flush: 'post' })
+
+const measure = () => {
+  const el = boxRef.value
+  if (!el || !props.target) return
+  const s = getComputedStyle(el)
+  const next = {
+    // The position only matters in manual mode, where CSS places the box.
+    x: manual.value ? el.offsetLeft : 0,
+    y: manual.value ? el.offsetTop : 0,
+    width: el.offsetWidth,
+    height: el.offsetHeight,
+    fill: s.backgroundColor,
+    stroke: s.borderTopColor,
+    strokeWidth: parseFloat(s.borderTopWidth) || 0,
+    radius: s.borderTopLeftRadius,
+    zIndex: s.zIndex
+  }
+  if (!sameKeys(next, box.value)) box.value = next
+}
+
+// Catches changes of the component's class/style, which are not reactive in the script.
+onUpdated(measure)
+
+// Where the bubble should end up for the current tip, box size, and props.
+const geometry = computed(() => {
+  const m = box.value
+  if (!tip.value || !m?.width || !m?.height) return null
+  const { width: w, height: h } = m
+  const { x: tx, y: ty } = tip.value
+  const tLen = props.tailLength
+  const f = frameRect.value
+  const rect = props.targetAnchor === 'edge' ? targetRect.value : null
+
+  if (manual.value) {
+    if (rect) {
+      // The point of the element's border nearest to the box center, unless that center is over the element.
+      const cx = m.x + w / 2
+      const cy = m.y + h / 2
+      const inside = cx >= rect.left && cx <= rect.right && cy >= rect.top && cy <= rect.bottom
+      if (!inside) {
+        const ex = Math.min(rect.right, Math.max(rect.left, cx))
+        const ey = Math.min(rect.bottom, Math.max(rect.top, cy))
+        return { placement: 'manual', tx: ex, ty: ey, bx: m.x, by: m.y, w, h }
+      }
+    }
+    return { placement: 'manual', tx, ty, bx: m.x, by: m.y, w, h }
+  }
+
+  // With the edge anchor the tip moves to the middle of the element's top or bottom edge, facing the box.
+  const tipYFor = (vertical) => (rect ? (vertical === 'top' ? rect.top : rect.bottom) : ty)
+
+  let placement = props.placement
+  if (placement === 'auto') {
+    let vertical = ty > (f.height || 600) / 2 ? 'top' : 'bottom'
+    let horizontal = tx > (f.width || 800) / 2 ? 'left' : 'right'
+
+    // Flip to the other side if the bubble would leave the viewport and fits there.
+    // Tip, box, and tail are local pixels; multiply by the scale to reach the viewport.
+    const { scaleX: sx, scaleY: sy } = f
+    if (f.viewportHeight) {
+      const fitsAbove = f.top + (tipYFor('top') - h - tLen) * sy >= 0
+      const fitsBelow = f.top + (tipYFor('bottom') + h + tLen) * sy <= f.viewportHeight
+      if (vertical === 'top' && !fitsAbove && fitsBelow) vertical = 'bottom'
+      else if (vertical === 'bottom' && !fitsBelow && fitsAbove) vertical = 'top'
+    }
+    if (f.viewportWidth) {
+      const fitsLeft = f.left + (tx - w - tLen) * sx >= 0
+      const fitsRight = f.left + (tx + w + tLen) * sx <= f.viewportWidth
+      if (horizontal === 'left' && !fitsLeft && fitsRight) horizontal = 'right'
+      else if (horizontal === 'right' && !fitsRight && fitsLeft) horizontal = 'left'
+    }
+
+    placement = `${vertical}-${horizontal}`
+  }
+
+  const [vertical, horizontal] = placement.split('-')
+  const tipY = tipYFor(vertical)
+  return {
+    placement,
+    tx,
+    ty: tipY,
+    bx: horizontal === 'left' ? tx - w - tLen : tx + tLen,
+    by: vertical === 'top' ? tipY - h - tLen : tipY + tLen,
+    w,
+    h
+  }
+})
+
+// What is rendered right now; eases towards `geometry` so the tail and the box move together.
+const current = ref(null)
+let frame = 0
+
+const prefersReducedMotion = () =>
+  typeof matchMedia !== 'undefined' && matchMedia('(prefers-reduced-motion: reduce)').matches
+
+watch(geometry, (to) => {
+  if (typeof cancelAnimationFrame !== 'undefined') cancelAnimationFrame(frame)
+  const from = current.value
+  const duration = props.transitionDuration
+  if (!to || !from || duration <= 0 || typeof requestAnimationFrame === 'undefined' || prefersReducedMotion()) {
+    current.value = to
+    return
+  }
+
+  const start = performance.now()
+  const step = (now) => {
+    const t = Math.min(1, (now - start) / duration)
+    const eased = 1 - Math.pow(1 - t, 3)
+    const next = { ...to }
+    const keys = to.placement === 'manual' ? MANUAL_ANIMATED_KEYS : ANIMATED_KEYS
+    for (const key of keys) next[key] = from[key] + (to[key] - from[key]) * eased
+    current.value = next
+    if (t < 1) frame = requestAnimationFrame(step)
+  }
+  frame = requestAnimationFrame(step)
+}, { immediate: true })
+
+let resizeObserver = null
+
+onMounted(() => {
+  window.addEventListener('resize', update)
+  window.addEventListener('scroll', update, true)
+  if (typeof ResizeObserver !== 'undefined') {
+    resizeObserver = new ResizeObserver(update)
+    resizeObserver.observe(rootRef.value)
+    resizeObserver.observe(boxRef.value)
+  }
+  update()
+})
+
+onBeforeUnmount(() => {
+  window.removeEventListener('resize', update)
+  window.removeEventListener('scroll', update, true)
+  resizeObserver?.disconnect()
+  if (typeof cancelAnimationFrame !== 'undefined') cancelAnimationFrame(frame)
+})
+
+// The tail: a triangle from the box wall facing the tip.
+// The fill runs a pixel past the inner edge of the border, so it covers the border where the
+// tail attaches even when page zoom snaps that edge to a different pixel.
+// An SVG stroke is centered on its path, so the outline is drawn along the middle of the border;
+// if it followed the fill, half of the border width would land inside the bubble.
+const tail = computed(() => {
+  const c = current.value
+  if (!c) return null
+  const { placement, tx, ty, bx, by, w, h } = c
+  const bw = box.value.strokeWidth
+  const radius = box.value.radius
+  const r = parseFloat(radius) * (radius.endsWith('%') ? Math.min(w, h) / 100 : 1) || 0
+  const half = props.tailBaseWidth / 2
+  const clamp = (v, lo, hi) => (lo > hi ? (lo + hi) / 2 : Math.min(hi, Math.max(lo, v)))
+
+  let side = null
+  let along = 0
+  if (placement === 'manual') {
+    const dx = Math.max(bx - tx, tx - (bx + w), 0)
+    const dy = Math.max(by - ty, ty - (by + h), 0)
+    if (dx > 0 && dx >= dy) {
+      side = tx < bx ? 'left' : 'right'
+      along = ty
+    } else if (dy > 0) {
+      side = ty < by ? 'top' : 'bottom'
+      along = tx
+    } else {
+      return null
+    }
+  } else {
+    const [vertical, horizontal] = placement.split('-')
+    side = horizontal === 'left' ? 'right' : 'left'
+    along = by + h * (vertical === 'top' ? 0.65 : 0.35)
+  }
+
+  const point = (x, y) => `${x} ${y}`
+  const triangle = (base1, base2) => `M ${point(...base1)} L ${tx} ${ty} L ${point(...base2)}`
+  // Center of the border. A stroke of width bw centered here stays within the border.
+  const mid = bw / 2
+  // One pixel past the inner edge. The fill matches the background, so this overlap is
+  // invisible, but it covers the border when page zoom snaps that edge off the path.
+  const cover = 1
+
+  if (side === 'left' || side === 'right') {
+    const a = clamp(along, by + r + half, by + h - r - half)
+    const y1 = a - half
+    const y2 = a + half
+    const fillX = side === 'left' ? bx + bw + cover : bx + w - bw - cover
+    const strokeX = side === 'left' ? bx + mid : bx + w - mid
+    return {
+      fill: triangle([fillX, y1], [fillX, y2]),
+      stroke: bw ? triangle([strokeX, y1], [strokeX, y2]) : null
+    }
+  }
+  const a = clamp(along, bx + r + half, bx + w - r - half)
+  const x1 = a - half
+  const x2 = a + half
+  const fillY = side === 'top' ? by + bw + cover : by + h - bw - cover
+  const strokeY = side === 'top' ? by + mid : by + h - mid
+  return {
+    fill: triangle([x1, fillY], [x2, fillY]),
+    stroke: bw ? triangle([x1, strokeY], [x2, strokeY]) : null
+  }
+})
+
+const placement = computed(() => (props.target ? current.value?.placement : 'none'))
+
+// Without a target the root is a plain block around the box, so opacity or transforms set on it apply to the box too.
+const rootStyle = computed(() => {
+  if (!props.target) return {}
+  const z = box.value?.zIndex
+  return {
+    position: 'absolute',
+    inset: 0,
+    pointerEvents: 'none',
+    zIndex: z && z !== 'auto' ? z : DEFAULT_Z_INDEX,
+    filter: props.shadow ? SHADOW : undefined
+  }
+})
+
+// Keys are only added when set: merged with the user's `style`, even an undefined key would win.
+const boxStyle = computed(() => {
+  const style = {
+    '--vpb-padding': typeof props.padding === 'number' ? `${props.padding}px` : props.padding
+  }
+  const maxWidth = props.maxWidth ?? (props.target ? DEFAULT_MAX_WIDTH : null)
+  if (maxWidth != null) style['--vpb-max-width'] = maxWidth + 'px'
+  if (!props.target) {
+    // In the flow the box shrinks to its content but never overflows its parent.
+    style['--vpb-width'] = 'fit-content'
+    if (props.shadow) style.filter = SHADOW
+    return style
+  }
+  const c = current.value
+  Object.assign(style, { position: 'absolute', pointerEvents: 'auto', visibility: c ? 'visible' : 'hidden' })
+  // In manual mode the box is positioned by its own CSS; otherwise next to the tip, ignoring margins.
+  if (!manual.value) Object.assign(style, { left: (c?.bx ?? 0) + 'px', top: (c?.by ?? 0) + 'px', margin: 0 })
+  return style
+})
+
+defineExpose({ update })
+</script>
+
+<template>
+  <div ref="rootRef" class="vue-pointing-bubble" :data-placement="placement" :style="rootStyle">
+    <div ref="boxRef" class="vue-pointing-bubble__inner" v-bind="$attrs" :style="boxStyle">
+      <slot :placement="placement" :tip="geometry ? { x: geometry.tx, y: geometry.ty } : tip">
+        <p :style="{ margin: 0, fontSize: '14px', fontWeight: 600, color: '#1e293b' }">Callout content</p>
+      </slot>
+    </div>
+    <svg
+      v-if="target && tail"
+      class="vue-pointing-bubble__svg"
+      :style="{ position: 'absolute', inset: 0, width: '100%', height: '100%', overflow: 'visible', zIndex: box?.zIndex }"
+    >
+      <path class="vue-pointing-bubble__path" :d="tail.fill" :fill="box.fill" />
+      <path
+        v-if="tail.stroke"
+        class="vue-pointing-bubble__path"
+        :d="tail.stroke"
+        fill="none"
+        :stroke="box.stroke"
+        :stroke-width="box.strokeWidth"
+        stroke-linejoin="round"
+        stroke-linecap="butt"
+      />
+    </svg>
+  </div>
+</template>

package/registry/ui/pointing-bubble/index.ts

@@ -0,0 +1 @@
+export { default as PointingBubble } from "./PointingBubble.vue"

package/src/index.d.ts

@@ -0,0 +1,44 @@
+import type { DefineComponent, Plugin, ComponentPublicInstance } from 'vue'
+
+export type PointingBubblePlacement =
+  | 'auto'
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-right'
+  | 'manual'
+
+export interface PointingBubblePoint {
+  x: number
+  y: number
+}
+
+export type PointingBubbleTarget =
+  | PointingBubblePoint
+  | Element
+  | ComponentPublicInstance
+  /** A CSS selector, looked up with `document.querySelector`. */
+  | string
+  | null
+
+export interface PointingBubbleProps {
+  target?: PointingBubbleTarget
+  placement?: PointingBubblePlacement
+  targetAnchor?: 'center' | 'edge'
+  maxWidth?: number
+  tailLength?: number
+  tailBaseWidth?: number
+  padding?: number | string
+  shadow?: boolean
+  transitionDuration?: number
+}
+
+export declare const PointingBubble: DefineComponent<PointingBubbleProps>
+export declare const Callout: typeof PointingBubble
+
+export interface PointingBubblePluginOptions {
+  name?: string
+}
+
+declare const plugin: Plugin<[PointingBubblePluginOptions?]>
+export default plugin

package/src/index.js

@@ -0,0 +1,9 @@
+import PointingBubble from '../registry/ui/pointing-bubble/PointingBubble.vue'
+
+export { PointingBubble, PointingBubble as Callout }
+
+export default {
+  install(app, options = {}) {
+    app.component(options.name || 'PointingBubble', PointingBubble)
+  }
+}