tolltop 2.0.0 → 3.0.1

package/README.md

@@ -1,6 +1,8 @@
 # tolltop
 
-One-attribute CSS tooltips. No JavaScript required.
+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 all modern
+browsers.
 
 ## Install
 
@@ -10,65 +12,65 @@ npm install tolltop
 
 ## Usage
 
-### CDN (recommended)
-
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tolltop/tolltop.css">
-```
-
-### CSS import
-
-```css
-@import 'tolltop/tolltop.css';
-```
-
-### JS bundler
-
-```js
-import 'tolltop'
-```
+<script src="https://cdn.jsdelivr.net/npm/tolltop/tolltop.js"></script>
 
-This auto-injects the stylesheet — a convenience wrapper, not a runtime dependency.
-
-### Then just add the attribute
-
-```html
+<!-- mark any element with the attribute -->
 <button data-tooltip="Save your work">Save</button>
 ```
 
-## How it works
-
-The entire library is CSS:
-
-- `::after` pseudo-element with `content: attr(data-tooltip)`
-- CSS Anchor Positioning (`position-area: top` + `position-try-fallbacks: flip-block`) for viewport flipping
-- `light-dark()` for automatic color inversion based on `color-scheme`
-- `:hover` for show/hide (works as tap on mobile)
+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:
 
-## Customization
-
-Override with CSS variables (globally or per-element):
-
-```css
-:root {
-  --tt-bg: #1e3a5f;
-  --tt-color: #fff;
-  --tt-radius: 8px;
-  --tt-font-size: 14px;
-  --tt-line-height: 1.5;
-}
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tolltop/tolltop.css">
+<script src="https://cdn.jsdelivr.net/npm/tolltop/tolltop.js"></script>
 ```
 
-## Color inversion
+## Configuration
 
-Set `color-scheme` on your page or sections:
+Style and behavior are global. Call `tolltop()` once with any subset of options (it merges
+into the current config and applies immediately):
 
-```css
-body { color-scheme: dark; }
-.light-section { color-scheme: light; }
+```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: 10,            // px between the trigger and the tooltip
+  edge: 24,           // px min gap from each viewport side
+});
 ```
 
-Tooltips auto-invert based on the nearest `color-scheme`.
+| 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`        | `12`             | `10`       |
+| `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.
+
+## Positioning
+
+- 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,32 +1,29 @@
 {
   "name": "tolltop",
-  "version": "2.0.0",
-  "description": "One-attribute CSS tooltips. CSS Anchor Positioning + light-dark().",
-  "main": "index.js",
+  "version": "3.0.1",
+  "description": "Tiny dependency-free tooltips with smart edge-aware positioning. One attribute, no build, works in all modern browsers.",
+  "main": "tolltop.js",
   "style": "tolltop.css",
-  "types": "index.d.ts",
+  "scripts": {
+    "build": "node build.js",
+    "prepublishOnly": "node build.js"
+  },
   "files": [
-    "index.js",
-    "index.d.ts",
+    "tolltop.js",
     "tolltop.css"
   ],
-  "scripts": {
-    "build": "node build.js"
-  },
   "keywords": [
     "tooltip",
-    "css",
-    "anchor-positioning",
-    "light-dark",
+    "tooltips",
+    "vanilla",
+    "no-dependencies",
+    "positioning",
     "lightweight"
   ],
   "author": "David Miranda",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/davidmiranda/tolltop"
-  },
-  "devDependencies": {
-    "esbuild": "^0.27.4"
+    "url": "git+https://github.com/panphora/tolltop.git"
   }
 }

package/tolltop.css

@@ -1,31 +1,60 @@
-[data-tooltip]:hover { anchor-name: --tt; }
+.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%;
 
-[data-tooltip]::after {
-  content: attr(data-tooltip);
   position: fixed;
-  position-anchor: --tt;
-  position-area: top;
-  position-try-fallbacks: flip-block;
-  inset: auto;
-  margin: 0 0 8px;
-  padding: 5px 9px;
-  font-size: var(--tt-font-size, 12px);
-  font-weight: 500;
-  line-height: var(--tt-line-height, 1.4);
-  font-family: ui-monospace, monospace;
-  border-radius: var(--tt-radius, 5px);
-  max-width: 240px;
+  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;
-  z-index: 2147483647;
-  background: var(--tt-bg, light-dark(#18181b, #fafafa));
-  color: var(--tt-color, light-dark(#e4e4e7, #18181b));
-  box-shadow:
-    0 2px 10px light-dark(rgba(0,0,0,.45), rgba(0,0,0,.12)),
-    0 0 0 1px light-dark(rgba(255,255,255,.06), rgba(0,0,0,.06));
+  box-shadow: 0 2px 12px rgba(0, 0, 0, 0.3);
   opacity: 0;
-  transition: opacity .1s ease;
+  visibility: hidden;
 }
 
-[data-tooltip]:hover::after { opacity: 1; }
+.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,219 @@
+/*!
+ * tolltop v3.0.1
+ * Tiny edge-aware tooltips with smart positioning. One attribute, one config call.
+ * MIT License · https://github.com/panphora/tolltop
+ */
+(() => {
+  '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.
+  // Generated from tolltop.css by build.js; do not edit by hand. Run `npm run build`.
+  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,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: 10,
+    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, 10));
+    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');
+  }
+
+  // True when a scrollable/overflow ancestor fully clips the element out of its box.
+  function clippedOut(el) {
+    const pos = getComputedStyle(el).position;
+    if (pos === 'fixed') return false; // viewport-positioned, not clipped by scroll ancestors
+    const r = el.getBoundingClientRect();
+    // An absolute element isn't clipped by overflow ancestors below its containing block.
+    const cb = pos === 'absolute' ? el.offsetParent : null;
+    let node = el.parentElement;
+    let clips = !cb;
+    while (node && node !== document.documentElement) {
+      if (!clips && node === cb) clips = true;
+      // Skip non-rendered/zero-box ancestors (e.g. display:contents) that don't actually clip.
+      if (clips && (node.clientWidth || node.clientHeight)) {
+        const o = getComputedStyle(node);
+        if (/auto|scroll|hidden|clip/.test(o.overflow + o.overflowX + o.overflowY)) {
+          const c = node.getBoundingClientRect();
+          const left = c.left + node.clientLeft; // padding box: where overflow actually clips
+          const top = c.top + node.clientTop;
+          if (r.bottom <= top || r.top >= top + node.clientHeight || r.right <= left || r.left >= left + node.clientWidth) return true;
+        }
+      }
+      node = node.parentElement;
+    }
+    return false;
+  }
+
+  function reposition() {
+    if (!active) return;
+    // A fixed tip isn't clipped by an ancestor's overflow, so hide it ourselves when the
+    // trigger is removed, scrolled out of the viewport, or clipped out of a scroll container.
+    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 || clippedOut(active)) {
+      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 @@
-(()=>{(()=>{let t=document.createElement("style");t.textContent="[data-tooltip]:hover{anchor-name:--tt}[data-tooltip]:after{content:attr(data-tooltip);position:fixed;position-anchor:--tt;position-area:top;position-try-fallbacks:flip-block;inset:auto;margin:0 0 8px;padding:5px 9px;font-size:var(--tt-font-size, 12px);font-weight:500;line-height:var(--tt-line-height, 1.4);font-family:ui-monospace,monospace;border-radius:var(--tt-radius, 5px);max-width:240px;width:max-content;text-align:center;pointer-events:none;z-index:2147483647;background:var(--tt-bg, light-dark(#18181b, #fafafa));color:var(--tt-color, light-dark(#e4e4e7, #18181b));box-shadow:0 2px 10px light-dark(rgba(0,0,0,.45),rgba(0,0,0,.12)),0 0 0 1px light-dark(rgba(255,255,255,.06),rgba(0,0,0,.06));opacity:0;transition:opacity .1s ease}[data-tooltip]:hover:after{opacity:1}",document.head.appendChild(t)})();})();