@data-slot/tooltip 0.1.0

package/README.md

@@ -0,0 +1,216 @@
+# @data-slot/tooltip
+
+Headless tooltip component for vanilla JavaScript. Accessible, unstyled, tiny.
+
+## Installation
+
+```bash
+npm install @data-slot/tooltip
+```
+
+## Quick Start
+
+```html
+<div data-slot="tooltip">
+  <button data-slot="tooltip-trigger">Hover me</button>
+  <div data-slot="tooltip-content" role="tooltip" hidden>
+    Helpful tooltip text
+  </div>
+</div>
+
+<script type="module">
+  import { create } from "@data-slot/tooltip";
+  
+  const controllers = create();
+</script>
+```
+
+## API
+
+### `create(scope?)`
+
+Auto-discover and bind all tooltip instances in a scope (defaults to `document`).
+
+```typescript
+import { create } from "@data-slot/tooltip";
+
+const controllers = create(); // Returns TooltipController[]
+```
+
+### `createTooltip(root, options?)`
+
+Create a controller for a specific element.
+
+```typescript
+import { createTooltip } from "@data-slot/tooltip";
+
+const tooltip = createTooltip(element, {
+  delay: 300,
+  skipDelayDuration: 300,
+  position: "top",
+  onOpenChange: (open) => console.log(open),
+});
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `delay` | `number` | `300` | Delay before showing tooltip (ms) |
+| `skipDelayDuration` | `number` | `300` | Duration to skip delay after closing (ms). Set to `0` to disable. |
+| `position` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | Position relative to trigger |
+| `onOpenChange` | `(open: boolean) => void` | `undefined` | Callback when visibility changes |
+
+### Controller
+
+| Method/Property | Description |
+|-----------------|-------------|
+| `show()` | Show the tooltip immediately |
+| `hide()` | Hide the tooltip |
+| `isOpen` | Current visibility state (readonly `boolean`) |
+| `destroy()` | Cleanup all event listeners |
+
+## Markup Structure
+
+```html
+<div data-slot="tooltip">
+  <button data-slot="tooltip-trigger">Trigger</button>
+  <div data-slot="tooltip-content" role="tooltip">Content</div>
+</div>
+```
+
+Both `tooltip-trigger` and `tooltip-content` are required.
+
+### Data Attributes
+
+Set position via HTML:
+
+```html
+<div data-slot="tooltip-content" data-position="bottom" role="tooltip">
+```
+
+## Styling
+
+### Basic Styling
+
+```css
+/* Hidden state */
+[data-slot="tooltip-content"][hidden] {
+  display: none;
+}
+
+/* Positioning */
+[data-slot="tooltip"] {
+  position: relative;
+}
+
+[data-slot="tooltip-content"] {
+  position: absolute;
+  white-space: nowrap;
+}
+
+[data-slot="tooltip-content"][data-position="top"] {
+  bottom: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+  margin-bottom: 8px;
+}
+
+[data-slot="tooltip-content"][data-position="bottom"] {
+  top: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+  margin-top: 8px;
+}
+
+[data-slot="tooltip-content"][data-position="left"] {
+  right: 100%;
+  top: 50%;
+  transform: translateY(-50%);
+  margin-right: 8px;
+}
+
+[data-slot="tooltip-content"][data-position="right"] {
+  left: 100%;
+  top: 50%;
+  transform: translateY(-50%);
+  margin-left: 8px;
+}
+```
+
+### Animations
+
+```css
+[data-slot="tooltip-content"] {
+  opacity: 0;
+  transition: opacity 0.15s;
+}
+
+[data-slot="tooltip"][data-state="open"] [data-slot="tooltip-content"] {
+  opacity: 1;
+}
+
+/* Skip transition during warm-up (instant show) */
+[data-slot="tooltip-content"][data-instant] {
+  transition: none;
+}
+```
+
+### Tailwind Example
+
+```html
+<div data-slot="tooltip" class="relative inline-block group">
+  <button data-slot="tooltip-trigger">
+    Hover me
+  </button>
+  <div 
+    data-slot="tooltip-content" 
+    data-position="top"
+    role="tooltip"
+    class="absolute bottom-full left-1/2 -translate-x-1/2 mb-2 px-2 py-1 bg-gray-900 text-white text-sm rounded opacity-0 group-data-[state=open]:opacity-100 transition-opacity pointer-events-none"
+  >
+    Tooltip text
+  </div>
+</div>
+```
+
+## Warm-up Behavior
+
+When a user closes one tooltip and quickly hovers another, the second tooltip shows instantly (no delay). This creates a fluid browsing experience similar to native OS tooltips.
+
+- Controlled by `skipDelayDuration` option
+- Set to `0` to disable this behavior
+- The `data-instant` attribute is set when showing instantly (use to skip CSS transitions)
+
+## Accessibility
+
+The component automatically handles:
+
+- `role="tooltip"` on content
+- `aria-describedby` linking trigger to content
+- Unique ID generation for content
+
+## Keyboard & Interaction
+
+| Action | Behavior |
+|--------|----------|
+| Mouse enter | Show after delay |
+| Mouse leave | Hide immediately |
+| Focus | Show after delay |
+| Blur | Hide immediately |
+| `Escape` | Hide immediately |
+
+## Events
+
+Listen for changes via custom events:
+
+```javascript
+element.addEventListener("tooltip:change", (e) => {
+  console.log("Tooltip visible:", e.detail.open);
+});
+```
+
+## License
+
+MIT
+

package/dist/index.cjs

@@ -0,0 +1 @@
+var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));const c=s(require(`@data-slot/core`));let l=0;const u=300;function d(e,t={}){let{delay:n=300,skipDelayDuration:r=u,onOpenChange:i}=t,a=(0,c.getPart)(e,`tooltip-trigger`),o=(0,c.getPart)(e,`tooltip-content`);if(!a||!o)throw Error(`Tooltip requires trigger and content slots`);let s=t.position??o.dataset.position??`top`,d=!1,f=null,p=[],m=(0,c.ensureId)(o,`tooltip-content`);a.setAttribute(`aria-describedby`,m),o.setAttribute(`role`,`tooltip`),o.setAttribute(`data-position`,s);let h=(t,n=!1)=>{d!==t&&(d=t,o.hidden=!d,e.setAttribute(`data-state`,d?`open`:`closed`),n&&d?o.setAttribute(`data-instant`,``):o.removeAttribute(`data-instant`),(0,c.emit)(e,`tooltip:change`,{open:d}),i?.(d))},g=()=>{if(f)return;let e=Date.now();if(e<l){h(!0,!0);return}f=setTimeout(()=>{h(!0,!1),f=null},n)},_=()=>{f&&(clearTimeout(f),f=null),d&&r>0&&(l=Date.now()+r),h(!1)};o.hidden=!0,e.setAttribute(`data-state`,`closed`),p.push((0,c.on)(a,`mouseenter`,g),(0,c.on)(a,`mouseleave`,_),(0,c.on)(a,`focus`,g),(0,c.on)(a,`blur`,_)),p.push((0,c.on)(document,`keydown`,e=>{d&&e.key===`Escape`&&_()}));let v={show:()=>{f&&(clearTimeout(f),f=null),h(!0)},hide:_,get isOpen(){return d},destroy:()=>{f&&clearTimeout(f),p.forEach(e=>e()),p.length=0}};return v}const f=new WeakSet;function p(e=document){let t=[];for(let n of(0,c.getRoots)(e,`tooltip`)){if(f.has(n))continue;f.add(n),t.push(d(n))}return t}exports.create=p,exports.createTooltip=d;

package/dist/index.d.cts

@@ -0,0 +1,41 @@
+//#region src/index.d.ts
+type TooltipPosition = 'top' | 'bottom' | 'left' | 'right';
+interface TooltipOptions {
+  /** Delay before showing tooltip (ms) */
+  delay?: number;
+  /** Duration to skip delay after closing (ms). Set to 0 to disable warm-up behavior. */
+  skipDelayDuration?: number;
+  /** Position of tooltip relative to trigger */
+  position?: TooltipPosition;
+  /** Callback when visibility changes */
+  onOpenChange?: (open: boolean) => void;
+}
+interface TooltipController {
+  /** Show the tooltip */
+  show(): void;
+  /** Hide the tooltip */
+  hide(): void;
+  /** Current visibility state */
+  readonly isOpen: boolean;
+  /** Cleanup all event listeners */
+  destroy(): void;
+}
+/**
+ * Create a tooltip controller for a root element
+ *
+ * Expected markup:
+ * ```html
+ * <div data-slot="tooltip">
+ *   <button data-slot="tooltip-trigger">Hover me</button>
+ *   <div data-slot="tooltip-content" role="tooltip">Tooltip text</div>
+ * </div>
+ * ```
+ */
+declare function createTooltip(root: Element, options?: TooltipOptions): TooltipController;
+/**
+ * Find and bind all tooltip components in a scope
+ * Returns array of controllers for programmatic access
+ */
+declare function create(scope?: ParentNode): TooltipController[];
+//#endregion
+export { TooltipController, TooltipOptions, TooltipPosition, create, createTooltip };

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+//#region src/index.d.ts
+type TooltipPosition = 'top' | 'bottom' | 'left' | 'right';
+interface TooltipOptions {
+  /** Delay before showing tooltip (ms) */
+  delay?: number;
+  /** Duration to skip delay after closing (ms). Set to 0 to disable warm-up behavior. */
+  skipDelayDuration?: number;
+  /** Position of tooltip relative to trigger */
+  position?: TooltipPosition;
+  /** Callback when visibility changes */
+  onOpenChange?: (open: boolean) => void;
+}
+interface TooltipController {
+  /** Show the tooltip */
+  show(): void;
+  /** Hide the tooltip */
+  hide(): void;
+  /** Current visibility state */
+  readonly isOpen: boolean;
+  /** Cleanup all event listeners */
+  destroy(): void;
+}
+/**
+ * Create a tooltip controller for a root element
+ *
+ * Expected markup:
+ * ```html
+ * <div data-slot="tooltip">
+ *   <button data-slot="tooltip-trigger">Hover me</button>
+ *   <div data-slot="tooltip-content" role="tooltip">Tooltip text</div>
+ * </div>
+ * ```
+ */
+declare function createTooltip(root: Element, options?: TooltipOptions): TooltipController;
+/**
+ * Find and bind all tooltip components in a scope
+ * Returns array of controllers for programmatic access
+ */
+declare function create(scope?: ParentNode): TooltipController[];
+//#endregion
+export { TooltipController, TooltipOptions, TooltipPosition, create, createTooltip };

package/dist/index.js

@@ -0,0 +1 @@
+import{emit as e,ensureId as t,getPart as n,getRoots as r,on as i}from"@data-slot/core";let a=0;const o=300;function s(r,s={}){let{delay:c=300,skipDelayDuration:l=o,onOpenChange:u}=s,d=n(r,`tooltip-trigger`),f=n(r,`tooltip-content`);if(!d||!f)throw Error(`Tooltip requires trigger and content slots`);let p=s.position??f.dataset.position??`top`,m=!1,h=null,g=[],_=t(f,`tooltip-content`);d.setAttribute(`aria-describedby`,_),f.setAttribute(`role`,`tooltip`),f.setAttribute(`data-position`,p);let v=(t,n=!1)=>{m!==t&&(m=t,f.hidden=!m,r.setAttribute(`data-state`,m?`open`:`closed`),n&&m?f.setAttribute(`data-instant`,``):f.removeAttribute(`data-instant`),e(r,`tooltip:change`,{open:m}),u?.(m))},y=()=>{if(h)return;let e=Date.now();if(e<a){v(!0,!0);return}h=setTimeout(()=>{v(!0,!1),h=null},c)},b=()=>{h&&(clearTimeout(h),h=null),m&&l>0&&(a=Date.now()+l),v(!1)};f.hidden=!0,r.setAttribute(`data-state`,`closed`),g.push(i(d,`mouseenter`,y),i(d,`mouseleave`,b),i(d,`focus`,y),i(d,`blur`,b)),g.push(i(document,`keydown`,e=>{m&&e.key===`Escape`&&b()}));let x={show:()=>{h&&(clearTimeout(h),h=null),v(!0)},hide:b,get isOpen(){return m},destroy:()=>{h&&clearTimeout(h),g.forEach(e=>e()),g.length=0}};return x}const c=new WeakSet;function l(e=document){let t=[];for(let n of r(e,`tooltip`)){if(c.has(n))continue;c.add(n),t.push(s(n))}return t}export{l as create,s as createTooltip};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@data-slot/tooltip",
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsdown"
+  },
+  "dependencies": {
+    "@data-slot/core": "workspace:*"
+  },
+  "keywords": ["headless", "ui", "tooltip", "vanilla", "data-slot"],
+  "license": "MIT"
+}