tolltop 1.0.1 → 3.0.0

package/README.md

@@ -1,6 +1,8 @@
 # tolltop
 
-One-attribute tooltips. Popover API + CSS Anchor Positioning. Auto-inverts color based on page background.
+Tiny, dependency-free tooltips with smart edge-aware positioning. One attribute to add a
+tooltip, one call to configure them all, no build step, and it works in every browser
+released since mid-2023 (Chrome/Edge 114+, Firefox 114+, Safari 16.5+).
 
 ## Install
 
@@ -10,33 +12,65 @@ npm install tolltop
 
 ## Usage
 
-### Script tag (CDN)
-
 ```html
-<script src="https://cdn.jsdelivr.net/npm/tolltop"></script>
+<script src="https://cdn.jsdelivr.net/npm/tolltop/tolltop.js"></script>
+
+<!-- mark any element with the attribute -->
+<button data-tooltip="Save your work">Save</button>
 ```
 
-### ES module
+Tooltips show on hover and on keyboard focus, and hide on `Esc`. The script injects its own
+styles, so loading `tolltop.css` is optional. Link it (before the script) only if you want
+to edit the CSS directly:
 
-```js
-import 'tolltop'
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tolltop/tolltop.css">
+<script src="https://cdn.jsdelivr.net/npm/tolltop/tolltop.js"></script>
 ```
 
-### Then just add the attribute
+## Configuration
 
-```html
-<button data-tooltip="Save your work">Save</button>
+Style and behavior are global. Call `tolltop()` once with any subset of options (it merges
+into the current config and applies immediately):
+
+```js
+tolltop({
+  bg: '#18181b',
+  color: '#e4e4e7',
+  radius: 6,          // number = px, or any CSS length string
+  fontSize: 12,       // same
+  padding: '6px 9px',
+  maxWidth: 240,      // px
+  placement: 'auto',  // 'auto' | 'top' | 'bottom'
+  gap: 8,             // px between the trigger and the tooltip
+  edge: 24,           // px min gap from each viewport side
+});
 ```
 
-That's it. No init, no config, no dependencies.
+| Option       | Example          | Default    |
+| ------------ | ---------------- | ---------- |
+| `bg`         | `'#1e3a5f'`      | `#18181b`  |
+| `color`      | `'#fff'`         | `#e4e4e7`  |
+| `radius`     | `10` or `'10px'` | `6`        |
+| `fontSize`   | `14` or `'.9rem'`| `12`       |
+| `padding`    | `'8px 12px'`     | `6px 9px`  |
+| `maxWidth`   | `320`            | `240`      |
+| `placement`  | `'top'`          | `'auto'`   |
+| `gap`        | `10`             | `8`        |
+| `edge`       | `16`             | `24`       |
+
+Calling `tolltop()` with no arguments returns the current config. The only per-element
+attribute is `data-tooltip="text"`, which marks an element and supplies its text.
 
-## What it does
+## Positioning
 
-- **Positions** tooltips above the trigger using CSS Anchor Positioning, flips to bottom when clipped
-- **300ms delay** before showing — no accidental flashes
-- **Auto-detects** background luminance and picks light or dark tooltip style
-- **Event delegation** — works on dynamically added elements
-- **Escape** key dismisses
+- Shows above the trigger by default.
+- Flips below if there isn't room above. Set `placement` to force a side (it still flips if
+  the forced side won't fit).
+- Centers horizontally on the trigger, then shifts left or right just enough to stay on
+  screen, leaving `edge` px of room on each side (the vertical scrollbar is excluded).
+- Long text is capped at the available width and wraps instead of running off screen.
+- The arrow stays centered on the trigger even after the box shifts, and points toward it.
 
 ## License
 

package/package.json

@@ -1,24 +1,25 @@
 {
   "name": "tolltop",
-  "version": "1.0.1",
-  "description": "One-attribute tooltips. Popover API + CSS Anchor Positioning. Auto-inverts color based on page background.",
-  "main": "index.js",
-  "types": "index.d.ts",
+  "version": "3.0.0",
+  "description": "Tiny dependency-free tooltips with smart edge-aware positioning. One attribute, no build, works in browsers back to mid-2023.",
+  "main": "tolltop.js",
+  "style": "tolltop.css",
   "files": [
-    "index.js",
-    "index.d.ts"
+    "tolltop.js",
+    "tolltop.css"
   ],
   "keywords": [
     "tooltip",
-    "popover",
-    "anchor-positioning",
-    "css",
+    "tooltips",
+    "vanilla",
+    "no-dependencies",
+    "positioning",
     "lightweight"
   ],
   "author": "David Miranda",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/davidmiranda/tolltop"
+    "url": "git+https://github.com/panphora/tolltop.git"
   }
 }

package/tolltop.css

@@ -0,0 +1,60 @@
+.tolltop {
+  --tt-bg: #18181b;
+  --tt-color: #e4e4e7;
+  --tt-radius: 6px;
+  --tt-font-size: 12px;
+  --tt-padding: 6px 9px;
+  --tt-arrow: 6px;
+  --tt-arrow-x: 50%;
+
+  position: fixed;
+  top: 0;
+  left: 0;
+  z-index: 2147483647;
+  box-sizing: border-box;
+  margin: 0;
+  width: max-content;
+  max-width: 240px;
+  padding: var(--tt-padding);
+  border-radius: var(--tt-radius);
+  background: var(--tt-bg);
+  color: var(--tt-color);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: var(--tt-font-size);
+  font-weight: 500;
+  line-height: 1.4;
+  text-align: center;
+  white-space: normal;
+  overflow-wrap: break-word;
+  pointer-events: none;
+  box-shadow: 0 2px 12px rgba(0, 0, 0, 0.3);
+  opacity: 0;
+  visibility: hidden;
+}
+
+.tolltop[data-show] {
+  opacity: 1;
+  visibility: visible;
+}
+
+.tolltop::after {
+  content: "";
+  position: absolute;
+  left: var(--tt-arrow-x);
+  transform: translateX(-50%);
+  width: 0;
+  height: 0;
+  border: var(--tt-arrow) solid transparent;
+}
+
+.tolltop[data-placement="top"]::after {
+  top: 100%;
+  border-bottom-width: 0;
+  border-top-color: var(--tt-bg);
+}
+
+.tolltop[data-placement="bottom"]::after {
+  bottom: 100%;
+  border-top-width: 0;
+  border-bottom-color: var(--tt-bg);
+}

package/tolltop.js

@@ -0,0 +1,188 @@
+(() => {
+  'use strict';
+  if (window.__tolltop) return;
+  window.__tolltop = true;
+
+  const VEDGE = 8;
+  const TIP_ID = 'tolltop-tip';
+
+  // Baseline styles, injected only if tolltop.css isn't already on the page.
+  // Keep in sync with tolltop.css.
+  const CSS = `.tolltop{--tt-bg:#18181b;--tt-color:#e4e4e7;--tt-radius:6px;--tt-font-size:12px;--tt-padding:6px 9px;--tt-arrow:6px;--tt-arrow-x:50%;position:fixed;top:0;left:0;z-index:2147483647;box-sizing:border-box;margin:0;width:max-content;max-width:240px;padding:var(--tt-padding);border-radius:var(--tt-radius);background:var(--tt-bg);color:var(--tt-color);font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:var(--tt-font-size);font-weight:500;line-height:1.4;text-align:center;white-space:normal;overflow-wrap:break-word;pointer-events:none;box-shadow:0 2px 12px rgba(0,0,0,.3);opacity:0;visibility:hidden}.tolltop[data-show]{opacity:1;visibility:visible}.tolltop::after{content:"";position:absolute;left:var(--tt-arrow-x);transform:translateX(-50%);width:0;height:0;border:var(--tt-arrow) solid transparent}.tolltop[data-placement="top"]::after{top:100%;border-bottom-width:0;border-top-color:var(--tt-bg)}.tolltop[data-placement="bottom"]::after{bottom:100%;border-top-width:0;border-bottom-color:var(--tt-bg)}`;
+
+  const cfg = {
+    bg: null,
+    color: null,
+    radius: null,
+    fontSize: null,
+    padding: null,
+    maxWidth: 240,
+    placement: 'auto',
+    gap: 8,
+    edge: 24,
+  };
+
+  let tip = null;
+  let active = null;
+  let activePrevAria = null;
+
+  const clamp = (n, lo, hi) => Math.min(Math.max(n, lo), hi);
+  const isNumStr = (v) => /^-?\d*\.?\d+$/.test(String(v).trim());
+  const toLen = (v) =>
+    v == null || v === '' ? null : typeof v === 'number' ? v + 'px' : isNumStr(v) ? v.trim() + 'px' : v.trim();
+  const numOr = (v, fallback) => (isFinite(Number(v)) ? Number(v) : fallback);
+
+  function setVar(name, value) {
+    if (value == null || value === '') tip.style.removeProperty(name);
+    else tip.style.setProperty(name, value);
+  }
+
+  function applyConfig() {
+    if (!tip) return;
+    setVar('--tt-bg', cfg.bg);
+    setVar('--tt-color', cfg.color);
+    setVar('--tt-radius', toLen(cfg.radius));
+    setVar('--tt-font-size', toLen(cfg.fontSize));
+    setVar('--tt-padding', cfg.padding);
+  }
+
+  function ensureTip() {
+    if (tip) return tip;
+    tip = document.createElement('div');
+    tip.className = 'tolltop';
+    tip.id = TIP_ID;
+    tip.setAttribute('role', 'tooltip');
+    document.body.appendChild(tip);
+    if (getComputedStyle(tip).position !== 'fixed') {
+      const style = document.createElement('style');
+      style.setAttribute('data-tolltop', '');
+      style.textContent = CSS;
+      document.head.insertBefore(style, document.head.firstChild);
+    }
+    applyConfig();
+    return tip;
+  }
+
+  function position(el) {
+    const rect = el.getBoundingClientRect();
+    // clientWidth/Height exclude the scrollbar; innerWidth would not.
+    const vw = document.documentElement.clientWidth;
+    const vh = document.documentElement.clientHeight;
+    const gap = Math.max(0, numOr(cfg.gap, 8));
+    const edge = Math.max(0, numOr(cfg.edge, 24));
+
+    const maxW = Math.min(numOr(cfg.maxWidth, 240), vw - edge * 2);
+    tip.style.maxWidth = maxW + 'px';
+
+    const t = tip.getBoundingClientRect();
+
+    const pref = cfg.placement;
+    const topY = rect.top - t.height - gap;
+    const botY = rect.bottom + gap;
+    const topFits = topY >= VEDGE;
+    const botFits = botY + t.height <= vh - VEDGE;
+    let placement;
+    if (pref === 'bottom') placement = botFits || !topFits ? 'bottom' : 'top';
+    else if (pref === 'top') placement = topFits || !botFits ? 'top' : 'bottom';
+    else placement = topFits ? 'top' : 'bottom';
+    // When the tip is taller than the viewport, pin to the top edge so its top stays visible.
+    const y =
+      t.height >= vh - VEDGE * 2 ? VEDGE : clamp(placement === 'top' ? topY : botY, VEDGE, vh - t.height - VEDGE);
+
+    const centerX = rect.left + rect.width / 2;
+    const x = clamp(centerX - t.width / 2, edge, vw - t.width - edge);
+
+    const radius = parseFloat(getComputedStyle(tip).borderTopLeftRadius) || 6;
+    const arrow = parseFloat(getComputedStyle(tip).getPropertyValue('--tt-arrow')) || 6;
+    const arrowX = clamp(centerX - x, radius + arrow, t.width - radius - arrow);
+
+    tip.style.left = x + 'px';
+    tip.style.top = y + 'px';
+    tip.style.setProperty('--tt-arrow-x', arrowX + 'px');
+    tip.setAttribute('data-placement', placement);
+    tip.setAttribute('data-show', '');
+  }
+
+  function restoreAria() {
+    if (!active) return;
+    if (activePrevAria == null) active.removeAttribute('aria-describedby');
+    else active.setAttribute('aria-describedby', activePrevAria);
+    activePrevAria = null;
+  }
+
+  function show(el) {
+    const text = el.getAttribute('data-tooltip');
+    if (!text) return;
+    ensureTip();
+    if (active !== el) {
+      if (active) restoreAria();
+      active = el;
+      activePrevAria = el.getAttribute('aria-describedby');
+      const ids = activePrevAria ? activePrevAria.split(/\s+/) : [];
+      if (ids.indexOf(TIP_ID) === -1) ids.push(TIP_ID);
+      el.setAttribute('aria-describedby', ids.join(' '));
+    }
+    tip.textContent = text;
+    position(el);
+  }
+
+  function hide() {
+    if (!active) return;
+    restoreAria();
+    active = null;
+    if (tip) tip.removeAttribute('data-show');
+  }
+
+  function reposition() {
+    if (!active) return;
+    // Hide if the trigger has been removed or scrolled out of view (a fixed tip
+    // isn't clipped by an ancestor's overflow, so it would otherwise float free).
+    if (!active.isConnected) {
+      hide();
+      return;
+    }
+    const r = active.getBoundingClientRect();
+    const vw = document.documentElement.clientWidth;
+    const vh = document.documentElement.clientHeight;
+    if (r.bottom < 0 || r.top > vh || r.right < 0 || r.left > vw) {
+      hide();
+      return;
+    }
+    position(active);
+  }
+
+  function trigger(node) {
+    return node && node.closest ? node.closest('[data-tooltip]') : null;
+  }
+
+  document.addEventListener('pointerover', (e) => {
+    const el = trigger(e.target);
+    if (el && el !== active) show(el);
+  });
+  document.addEventListener('pointerout', (e) => {
+    if (active && (!e.relatedTarget || !active.contains(e.relatedTarget))) hide();
+  });
+  document.addEventListener('focusin', (e) => {
+    const el = trigger(e.target);
+    if (el) show(el);
+  });
+  document.addEventListener('focusout', hide);
+  document.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape') hide();
+  });
+  window.addEventListener('scroll', reposition, true);
+  window.addEventListener('resize', reposition);
+
+  window.tolltop = function (opts) {
+    if (opts && typeof opts === 'object') {
+      for (const k in opts) {
+        if (Object.prototype.hasOwnProperty.call(cfg, k)) cfg[k] = opts[k];
+      }
+      applyConfig();
+      if (active) position(active);
+    }
+    const out = {};
+    for (const k in cfg) out[k] = cfg[k];
+    return out;
+  };
+})();

package/index.d.ts

@@ -1 +0,0 @@
-declare module 'tolltop' {}

package/index.js

@@ -1 +0,0 @@
-(()=>{const s=document.createElement('style');s.textContent=`[popover].tt{position:fixed;position-anchor:--tt;position-area:top;position-try-fallbacks:flip-block;inset:auto;margin:0 0 8px;padding:5px 9px;font:500 12px/1.4 ui-monospace,monospace;border-radius:5px;border:none;max-width:240px;pointer-events:none;z-index:2147483647;opacity:0;transition:opacity .1s ease}[popover].tt:popover-open{opacity:1}@starting-style{[popover].tt:popover-open{opacity:0}}[popover].tt.tt-light{background:#fff;color:#18181b;box-shadow:0 2px 10px rgba(0,0,0,.18),0 0 0 1px rgba(0,0,0,.06)}[popover].tt.tt-dark{background:#18181b;color:#e4e4e7;box-shadow:0 2px 10px rgba(0,0,0,.45),0 0 0 1px rgba(255,255,255,.06)}`;document.head.appendChild(s);const D=300;let tip=null,timer=null,anchor=null;function ct(el){let n=el;while(n&&n!==document){if(n.nodeType===1&&n.hasAttribute&&n.hasAttribute('data-tooltip'))return n;n=n.parentNode}return null}function init(){if(tip)return tip;tip=document.createElement('div');tip.classList.add('tt');tip.setAttribute('popover','manual');document.body.appendChild(tip);return tip}function isDark(el){let n=el;while(n&&n!==document){const bg=getComputedStyle(n).backgroundColor;const m=bg.match(/\d+/g);if(m&&(m.length<4||+m[3]>0)){const[r,g,b]=m.map(Number);return r*.299+g*.587+b*.114<128}n=n.parentElement}return true}function show(el){const text=el.getAttribute('data-tooltip');if(!text)return;el.style.anchorName='--tt';const t=init();t.textContent=text;t.classList.toggle('tt-light',isDark(el));t.classList.toggle('tt-dark',!isDark(el));t.showPopover();anchor=el}function hide(){clearTimeout(timer);if(tip)try{tip.hidePopover()}catch{}if(anchor){anchor.style.anchorName='';anchor=null}}document.addEventListener('pointerenter',e=>{const el=ct(e.target);if(!el)return;hide();timer=setTimeout(()=>show(el),D)},true);document.addEventListener('pointerleave',e=>{if(ct(e.target))hide()},true);document.addEventListener('keydown',e=>{if(e.key==='Escape')hide()})})();