# Floating tooltip

One shared hint that follows the pointer and slides between triggers.

Package: @reuse-sh/interactions

## Principles

These are the rules to keep when you adapt this library. The code is one way to keep them. An adaptation on any framework must keep every one.

- Share one popup. Nearby triggers share one tooltip, so moving along a toolbar slides it across instead of closing and reopening it.

- Follow the pointer on a spring. It trails the pointer with a little weight, below and to the right, and never jumps.

- Anchor to keyboard focus. Keyboard focus places it on the element, and Escape hides it.

- Treat touch as touch. A touch is not hover, so touch input never opens it.

- Hold only a hint. It describes its trigger through aria-describedby and never holds controls or required instructions.

- Stay inside the window. It keeps a margin from every edge of the viewport.

## Install

```bash
npm install @reuse-sh/interactions
```

## Integration notes

- Mark triggers with data-reuse-tooltip, or with data-reuse-tooltip-template for rich content.

- A tooltip holds a short hint that nobody needs to click. Put controls and required instructions somewhere else.

- Keyboard focus shows an anchored hint. A touch is not treated as hover.

## API

- `createFloatingTooltip(root, options?)`: Binds every trigger inside root to one shared popup. Returns refresh, dismiss, update(options) and destroy.

- `data-reuse-tooltip, data-reuse-tooltip-template`: Marks a trigger. The first holds the hint as text, the second names the id of a template to clone.

- `selector`: Which elements count as triggers. Both attributes above by default.

- `side, sideOffset`: Where the popup sits from the pointer, such as "bottom-right" or "top", and how far away. Bottom right and 10 px by default.

- `tilt`: Leans the popup by up to this many degrees while the pointer moves. 5 by default, 0 turns it off.

- `delay, closeDelay`: The wait before the first hint shows, 150 ms, and before the last one hides, 80 ms. Moving between triggers swaps at once.

- `content(trigger)`: Returns text or a node for a trigger, in place of the attributes.

- `className`: Added to the popup, for your own styles.

- `track, viewportPadding`: Follow the pointer or stay on the trigger, per axis, and the margin kept from the window edges.

- `FloatingTooltip, FloatingTooltipGroup`: The React components: one trigger with a content string, or a group that takes the same options. tooltipClassName sets the popup's class.

## Browser JavaScript

```js
import { createFloatingTooltip } from "@reuse-sh/interactions";
import "@reuse-sh/interactions/styles.css";

// Any element inside the root with data-reuse-tooltip gets the hint.
// <button aria-label="Share" data-reuse-tooltip="Share">…</button>
const toolbar = document.querySelector(".toolbar");
const tooltip = createFloatingTooltip(toolbar, { tilt: 5 });

// Later, when the toolbar leaves the page
tooltip.destroy();
```

## React

```tsx
import { FloatingTooltipGroup } from "@reuse-sh/interactions/react";
import "@reuse-sh/interactions/styles.css";

export function Toolbar() {
  return (
    <FloatingTooltipGroup className="toolbar" tilt={5}>
      <button aria-label="Share" data-reuse-tooltip="Share"><ShareIcon /></button>
      <button aria-label="Delete" data-reuse-tooltip="Delete"><TrashIcon /></button>
    </FloatingTooltipGroup>
  );
}
```

## Agent workflow

1. Inspect the project and read the installed package's types and stylesheet.

2. Reuse the native controller. Use the React adapter only in a React surface.

3. Adapt styles and data connections to the project. Keep every principle above. Do not recreate the gesture or state engine.

4. Connect destroy and unsubscribe callbacks to the owner lifecycle.

5. Verify keyboard access, pointer/touch behavior, resize, empty/one-item states, errors, reduced motion, and teardown where applicable.

6. Report the actual checks and remaining browser/device limits.

## Source

https://github.com/reuse-sh/reuse/tree/main/packages/interactions/src

License: MIT for original library code. Preserve dependency and asset license notices.