vue-pointing-bubble 0.1.0 → 0.2.0

package/README.md

@@ -1,418 +1,69 @@
 # vue-pointing-bubble
 
-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.
+Vue 3 callout / speech bubble whose SVG tail points exactly at coordinates or 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.
+Repository: [github.com/MurzNN/js-pointing-bubble](https://github.com/MurzNN/js-pointing-bubble) · Demo: [https://murznn.github.io/js-pointing-bubble/vue/](https://murznn.github.io/js-pointing-bubble/vue/)
 
-![Screenshot of the pointing bubble simple demo layout.](docs/screenshot.png)
+- Point at `{ x, y }` or a DOM element / CSS selector
+- Auto / fixed / manual placement with a seamless SVG tail
+- Edge or center target anchors, resize + scroll tracking, optional glide
+- Style with `class` / `style` (Tailwind / UnoCSS welcome); no CSS import required
 
-**[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:
+## Install
 
 ```bash
-npm install github:MurzNN/vue-pointing-bubble
+pnpm add 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:
+## Install via shadcn-vue
 
 ```bash
-pnpm dlx shadcn-vue@latest add MurzNN/vue-pointing-bubble/pointing-bubble
+pnpm dlx shadcn-vue@latest add MurzNN/js-pointing-bubble/vue-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>
+```ts
 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.
+## Quick start
 
 ```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>
+<script setup lang="ts">
 import { ref } from 'vue'
 import { PointingBubble } from 'vue-pointing-bubble'
 
-const button = ref(null)
+const btn = ref<HTMLElement | null>(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>
+  <button ref="btn">Hint</button>
+  <PointingBubble :target="btn" :max-width="240">
+    Precise callout content
+  </PointingBubble>
 </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>
-```
+### Props
 
-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()`.
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `target` | `null` | `{x,y}`, `Element`, CSS selector, or `null` (in-flow box only) |
+| `placement` | `'auto'` | `'auto'` \| quadrant \| `'manual'` (CSS positions the box) |
+| `targetAnchor` | `'center'` | `'center'` \| `'edge'` for element targets |
+| `maxWidth` | — | Wrap width (px) unless CSS sets width/max-width |
+| `tailLength` | `45` | Tip → box offset (px) |
+| `tailBaseWidth` | `24` | Tail width at the box (px) |
+| `padding` | `8` | Via `--pb-padding` unless CSS sets padding |
+| `shadow` | `true` | Shared drop-shadow on overlay/box |
+| `transitionDuration` | `200` | Glide ms (`0` off; respects reduced motion) |
 
-### A box without a tail
+Expose / ref: `update()` after non-reactive layout changes.
 
-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:
+CSS hooks: `.pointing-bubble`, `.pointing-bubble__inner`, `.pointing-bubble__svg`, `.pointing-bubble__path`. Vars: `--pb-padding`, `--pb-max-width`, `--pb-width`.
 
-```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**.
+**Breaking (v0.2):** class prefix renamed from `.vue-pointing-bubble*` / `--vpb-*` to `.pointing-bubble*` / `--pb-*`.
 
 ## License
 
-[MIT](LICENSE)
+MIT
+

package/dist/index.d.ts

@@ -1,44 +1,3 @@
-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
+export { PointingBubble, PointingBubble as Callout, PointingBubble as default, PointingBubblePlugin, type PointingBubblePluginOptions, } from './pointing-bubble';
+export type { Placement, ResolvedPlacement, TargetAnchor, Point, BubbleTarget, BubbleConfig, BubbleController, BubbleRenderState, } from './pointing-bubble';
+export { DEFAULT_BUBBLE_CONFIG, createBubbleController, resolveElement, isPoint, computeGeometry, buildTailPaths, } from './pointing-bubble';

package/dist/pointing-bubble/PointingBubble.vue.d.ts

@@ -0,0 +1,45 @@
+import { ComponentPublicInstance } from 'vue';
+import { BubbleTarget, Placement, TargetAnchor } from './core';
+type __VLS_Props = {
+    target?: BubbleTarget | ComponentPublicInstance | null;
+    placement?: Placement;
+    targetAnchor?: TargetAnchor;
+    maxWidth?: number;
+    tailLength?: number;
+    tailBaseWidth?: number;
+    padding?: number | string;
+    shadow?: boolean;
+    transitionDuration?: number;
+};
+declare function update(): void;
+declare var __VLS_1: {
+    placement: "none";
+    tip: {
+        x: number;
+        y: number;
+    } | null;
+};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {
+    update: typeof update;
+}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    placement: Placement;
+    tailLength: number;
+    tailBaseWidth: number;
+    target: BubbleTarget | ComponentPublicInstance;
+    targetAnchor: TargetAnchor;
+    maxWidth: number;
+    padding: string | number;
+    shadow: boolean;
+    transitionDuration: number;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/pointing-bubble/core.d.ts

@@ -0,0 +1,13 @@
+export type { Placement, ResolvedPlacement, TargetAnchor, Point, BubbleTarget, FrameRect, LocalRect, BoxMeasure, Geometry, Room, TailPaths, BubbleConfig, StyleMap, } from './types';
+export { DEFAULT_BUBBLE_CONFIG } from './types';
+export { injectBubbleStyles, SHADOW } from './styles';
+export { isPoint, resolveElement } from './resolveTarget';
+export { sameKeys, measureFrame, measureBox } from './measure';
+export { computeRoom, roomierSide, computeGeometry } from './geometry';
+export type { ComputeGeometryOptions } from './geometry';
+export { easeGeometry } from './ease';
+export type { EaseHandle } from './ease';
+export { buildTailPaths } from './tail';
+export type { BuildTailOptions } from './tail';
+export { createBubbleController } from './createBubbleController';
+export type { BubbleRenderState, BubbleControllerOptions, BubbleController, } from './createBubbleController';

package/dist/pointing-bubble/createBubbleController.d.ts

@@ -0,0 +1,31 @@
+import { BubbleConfig, BubbleTarget, Point, ResolvedPlacement, StyleMap, TailPaths } from './types';
+export interface BubbleRenderState {
+    hasTarget: boolean;
+    placement: ResolvedPlacement;
+    tip: Point | null;
+    /** Tip passed to slot/children (resolved geometry tip when available). */
+    slotTip: Point | null;
+    overlayStyle: StyleMap;
+    boxStyle: StyleMap;
+    /** When no target, root element is the box. */
+    rootIsBox: boolean;
+    tail: TailPaths | null;
+    boxFill: string;
+    boxStroke: string;
+    boxStrokeWidth: number;
+    boxZIndex: string;
+}
+export interface BubbleControllerOptions {
+    getRootEl: () => HTMLElement | null;
+    getBoxEl: () => HTMLElement | null;
+    onChange?: (state: BubbleRenderState) => void;
+}
+export interface BubbleController {
+    update: () => void;
+    setConfig: (partial: Partial<BubbleConfig>) => void;
+    getConfig: () => BubbleConfig;
+    getState: () => BubbleRenderState;
+    destroy: () => void;
+}
+export declare function createBubbleController(options: BubbleControllerOptions): BubbleController;
+export type { BubbleTarget };

package/dist/pointing-bubble/ease.d.ts

@@ -0,0 +1,9 @@
+import { Geometry } from './types';
+export interface EaseHandle {
+    cancel: () => void;
+}
+/**
+ * Ease `from` → `to` with ease-out cubic. Calls `onFrame` each tick.
+ * Manual placement only animates tip coords (CSS owns the box).
+ */
+export declare function easeGeometry(from: Geometry | null, to: Geometry | null, durationMs: number, onFrame: (value: Geometry | null) => void): EaseHandle;

package/dist/pointing-bubble/geometry.d.ts

@@ -0,0 +1,14 @@
+import { BoxMeasure, FrameRect, Geometry, LocalRect, Placement, Point, Room, TargetAnchor } from './types';
+export declare function computeRoom(tip: Point, frame: FrameRect, tailLength: number): Room;
+export declare function roomierSide(room: Room): 'left' | 'right';
+export interface ComputeGeometryOptions {
+    tip: Point;
+    box: BoxMeasure;
+    frame: FrameRect;
+    placement: Placement;
+    targetAnchor: TargetAnchor;
+    targetRect: LocalRect | null;
+    room: Room;
+    tailLength: number;
+}
+export declare function computeGeometry(opts: ComputeGeometryOptions): Geometry | null;

package/dist/pointing-bubble/index.d.ts

@@ -0,0 +1,11 @@
+import { Plugin } from 'vue';
+import { default as PointingBubble } from './PointingBubble.vue';
+export type { Placement, ResolvedPlacement, TargetAnchor, Point, BubbleTarget, BubbleConfig, BubbleController, BubbleRenderState, } from './core';
+export { DEFAULT_BUBBLE_CONFIG, createBubbleController, resolveElement, isPoint, computeGeometry, buildTailPaths, } from './core';
+export { PointingBubble };
+export { PointingBubble as Callout };
+export { PointingBubble as default };
+export interface PointingBubblePluginOptions {
+    name?: string;
+}
+export declare const PointingBubblePlugin: Plugin;

package/dist/pointing-bubble/measure.d.ts

@@ -0,0 +1,5 @@
+import { BoxMeasure, FrameRect } from './types';
+export declare function sameKeys(a: Record<string, unknown> | null | undefined, b: Record<string, unknown> | null | undefined): boolean;
+/** Measure root frame including ancestor CSS scale (e.g. Slidev). */
+export declare function measureFrame(root: HTMLElement): FrameRect;
+export declare function measureBox(boxEl: HTMLElement, rootEl: HTMLElement, frame: FrameRect, manual: boolean): BoxMeasure;

package/dist/pointing-bubble/resolveTarget.d.ts

@@ -0,0 +1,7 @@
+import { BubbleTarget, Point } from './types';
+export declare function isPoint(value: unknown): value is Point;
+/**
+ * Resolve a CSS selector or Element. Adapters unwrap framework component
+ * instances / refs before calling this.
+ */
+export declare function resolveElement(target: BubbleTarget): Element | null;

package/dist/pointing-bubble/styles.d.ts

@@ -0,0 +1,3 @@
+export declare const SHADOW = "drop-shadow(0 6px 8px rgba(0, 0, 0, 0.25))";
+/** Inject default zero-specificity box styles once per document. */
+export declare function injectBubbleStyles(doc?: Document): void;