{"_id":"@cujuju/solidjs-kv-tooltip","_rev":"2-818c0186448ba55121a3d6a8868a75a0","name":"@cujuju/solidjs-kv-tooltip","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@cujuju/solidjs-kv-tooltip","version":"0.1.0","keywords":["solidjs","tooltip","hover","portal","viewport-clamp"],"author":{"name":"Cujuju"},"license":"MIT","_id":"@cujuju/solidjs-kv-tooltip@0.1.0","maintainers":[{"name":"cujuju","email":"cujuju@pm.me"}],"homepage":"https://github.com/Cujuju/solidjs-toolkit/tree/main/packages/kv-tooltip","bugs":{"url":"https://github.com/Cujuju/solidjs-toolkit/issues"},"dist":{"shasum":"f9d193e36041fca17b3cddf84d965caa02b38c97","tarball":"https://registry.npmjs.org/@cujuju/solidjs-kv-tooltip/-/solidjs-kv-tooltip-0.1.0.tgz","fileCount":17,"integrity":"sha512-RIv0cfbNiXLZQw5cpsWgIZR5N1tkRScED/wI235Ta0yV6Jz3GLNw0txkBSWh5jxqpR70vUlnkEKz2hgcZhJbOg==","signatures":[{"sig":"MEUCIQCOXLFj3/ybU0XmgzGDAEN/IZ5bQvfu+/ty2drrcid9BgIgIBlezgnbOY0k4s9NcJozayQ6/7bLOxaZ5EMBzIGaIhY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":84188},"main":"./dist/index.js","type":"module","_from":"file:cujuju-solidjs-kv-tooltip-0.1.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"solid":"./src/index.ts","types":"./dist/index.d.ts","import":"./dist/index.js"},"./styles.css":"./src/styles.css"},"scripts":{"test":"vitest run","build":"vite build","test:watch":"vitest"},"_npmUser":{"name":"cujuju","email":"cujuju@pm.me"},"_resolved":"C:\\Users\\shawn\\AppData\\Local\\Temp\\c8c428632f783f0281e8103ed184ed43\\cujuju-solidjs-kv-tooltip-0.1.0.tgz","_integrity":"sha512-RIv0cfbNiXLZQw5cpsWgIZR5N1tkRScED/wI235Ta0yV6Jz3GLNw0txkBSWh5jxqpR70vUlnkEKz2hgcZhJbOg==","repository":{"url":"git+https://github.com/Cujuju/solidjs-toolkit.git","type":"git","directory":"packages/kv-tooltip"},"_npmVersion":"11.12.1","description":"Mouse-follow key-value tooltip for SolidJS — viewport-clamped with hysteresis, Portal-rendered, extraContent slot.","directories":{},"sideEffects":["**/*.css"],"_nodeVersion":"25.8.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jsdom":"^24.1.3","vitest":"^3.2.4","vite-plugin-solid":"^2.11.12","@testing-library/jest-dom":"^6.9.1"},"peerDependencies":{"solid-js":">=1.7.0"},"_npmOperationalInternal":{"tmp":"tmp/solidjs-kv-tooltip_0.1.0_1777341457319_0.42787473633208206","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@cujuju/solidjs-kv-tooltip","version":"0.2.0","description":"Mouse-follow or rect-anchored key-value tooltip for SolidJS — viewport-clamped with hysteresis, Portal-rendered, extraContent slot.","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","solid":"./src/index.ts","import":"./dist/index.js"},"./styles.css":"./src/styles.css"},"sideEffects":["**/*.css"],"license":"MIT","author":{"name":"Cujuju"},"repository":{"type":"git","url":"git+https://github.com/Cujuju/solidjs-toolkit.git","directory":"packages/kv-tooltip"},"homepage":"https://github.com/Cujuju/solidjs-toolkit/tree/main/packages/kv-tooltip","bugs":{"url":"https://github.com/Cujuju/solidjs-toolkit/issues"},"keywords":["solidjs","tooltip","hover","portal","viewport-clamp","anchored","placement"],"peerDependencies":{"solid-js":">=1.7.0"},"devDependencies":{"@testing-library/jest-dom":"^6.9.1","jsdom":"^24.1.3","vite-plugin-solid":"^2.11.12","vitest":"^3.2.4"},"publishConfig":{"access":"public"},"scripts":{"test":"vitest run","test:watch":"vitest","build":"vite build"},"_id":"@cujuju/solidjs-kv-tooltip@0.2.0","_integrity":"sha512-LNi6AJk1JqIY0kx8SUabiHqpvWeZXkiqJaOsDoA12nGWIalHomGFtbjqNJXoR4J0uL2YJy6hT2apYtThFUiE6w==","_resolved":"/tmp/2b8acfc4bf478823c4ee6b93d5ccc669/cujuju-solidjs-kv-tooltip-0.2.0.tgz","_from":"file:cujuju-solidjs-kv-tooltip-0.2.0.tgz","_nodeVersion":"24.18.0","_npmVersion":"12.0.1","dist":{"integrity":"sha512-LNi6AJk1JqIY0kx8SUabiHqpvWeZXkiqJaOsDoA12nGWIalHomGFtbjqNJXoR4J0uL2YJy6hT2apYtThFUiE6w==","shasum":"af8776ea771fc385dca5ea154f20332c76f18228","tarball":"https://registry.npmjs.org/@cujuju/solidjs-kv-tooltip/-/solidjs-kv-tooltip-0.2.0.tgz","fileCount":21,"unpackedSize":201757,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCM1TJeBUWCsUeJLtc+P3zAs/EY15ganSrfe98vUxQzpwIhAMElbPFzLUy7z6ak5EXc7qeyCFFc+ytuiy1xZt1T9yQ8"}]},"_npmUser":{"name":"cujuju","email":"cujuju@pm.me"},"directories":{},"maintainers":[{"name":"cujuju","email":"cujuju@pm.me"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/solidjs-kv-tooltip_0.2.0_1784887074075_0.8111340224118928"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-28T01:57:37.245Z","modified":"2026-07-24T09:57:54.356Z","0.1.0":"2026-04-28T01:57:37.451Z","0.2.0":"2026-07-24T09:57:54.214Z"},"bugs":{"url":"https://github.com/Cujuju/solidjs-toolkit/issues"},"author":{"name":"Cujuju"},"license":"MIT","homepage":"https://github.com/Cujuju/solidjs-toolkit/tree/main/packages/kv-tooltip","keywords":["solidjs","tooltip","hover","portal","viewport-clamp","anchored","placement"],"repository":{"type":"git","url":"git+https://github.com/Cujuju/solidjs-toolkit.git","directory":"packages/kv-tooltip"},"description":"Mouse-follow or rect-anchored key-value tooltip for SolidJS — viewport-clamped with hysteresis, Portal-rendered, extraContent slot.","maintainers":[{"name":"cujuju","email":"cujuju@pm.me"}],"readme":"# @cujuju/solidjs-kv-tooltip\n\nMouse-follow key-value tooltip for SolidJS. Two modes: hover-wrapper and caller-controlled panel. Viewport-clamped with hysteresis (never flickers at edges). Portal-rendered so `overflow: hidden` parents can't clip it.\n\n## Install\n\n```\npnpm add @cujuju/solidjs-kv-tooltip\n```\n\n## Usage\n\n### Hover wrapper\n\n```tsx\nimport { KvTooltip } from '@cujuju/solidjs-kv-tooltip';\n\n<KvTooltip entries={{ Bid: '123.45', Ask: '123.50', Vol: '1.2M' }}>\n  <span>AAPL</span>\n</KvTooltip>\n```\n\n### Controlled panel\n\nCaller manages visibility + x/y (useful when the trigger isn't a simple hover target — e.g., a virtualised table row).\n\n```tsx\nimport { KvTooltipPanel } from '@cujuju/solidjs-kv-tooltip';\n\nconst [active, setActive] = createSignal<{ x: number; y: number; data: ... } | null>(null);\n\n<Show when={active()}>\n  {(a) => (\n    <KvTooltipPanel\n      entries={a().data}\n      x={a().x}\n      y={a().y}\n    />\n  )}\n</Show>\n```\n\n### With extra content (e.g., a chart)\n\n```tsx\n<KvTooltipPanel\n  entries={entries}\n  x={mx} y={my}\n  extraContent={<Sparkline data={...} />}\n/>\n```\n\nA 1px separator + padding are added automatically between the entries and the `extraContent`.\n\n## API (highlights)\n\n| Prop | Default | Description |\n|---|---|---|\n| `entries` | (required) | `Record<string, string>` rendered as key/value rows. Empty/undefined values are dropped unless `showEmpty: true`. |\n| `children` (wrapper) | (required) | Element the hover listener attaches to. |\n| `x`, `y` (panel) | (required) | Cursor / anchor coordinates in viewport space. |\n| `extraContent` | — | JSX rendered below entries with a top separator. |\n| `showEmpty` | `false` | Render entries with empty-string values. |\n| `disabled` (wrapper) | `false` | Never show. |\n| `interactive` | `false` | When `true`: panel receives pointer events (so consumers can put links / copy buttons / form fields inside) and persists for `hideDelayMs` after the cursor leaves the trigger, allowing the user to cross the gap into the panel without losing it. Cancelled by re-entering either the trigger or the panel. |\n| `hideDelayMs` | `100` | Hide-debounce delay (ms). Only consulted when `interactive=true`. Tuned to match typical pointer-travel time across the `mouseOffsetX/Y` gap; lower for snappier dismiss, higher for more forgiving traversal. |\n| `showDelayMs` (wrapper) | `0` | Rest delay (ms) before showing. A pointer passing *through* the trigger never flashes a panel. No derived default — the right value depends on your trigger density/size, not on this package's geometry. |\n| `anchor` | — | `DOMRect \\| (() => DOMRect \\| null)`. Anchors the panel to a rect instead of `x`/`y`. Prefer the accessor form so the rect is re-read on resize/scroll. |\n| `placement` | `'cursor'` | `'cursor' \\| 'above-start' \\| 'below-start' \\| 'above-end' \\| 'below-end'`. With an `anchor` set and this left at `'cursor'`, resolves to `'below-start'`. |\n| `anchorGapPx` | `4` | Gap between the anchor edge and the panel edge. Matches `DEFAULT_POPOVER_OFFSET_PX` in `@cujuju/solidjs-anchored-popover`. |\n| `freezeOnShow` (wrapper) | `false` | Snapshot entries + reference position at show time and hold both until hidden. For live-ticking entry sources that would otherwise re-measure the panel every frame. |\n| `hideOnPointerDown` (wrapper) | `false` | Pointerdown on the trigger hides the panel and suppresses re-show until the pointer leaves and re-enters. |\n| `suppressWhileTopLayerOpen` (wrapper) | `false` | Refuse to show while any native popover is open (`[popover]:popover-open`). |\n| `hideOnScroll` (wrapper) | `false` | Dismiss on any scroll. Position *recompute* on scroll is unconditional and needs no prop. |\n| `mouseOffsetX`, `mouseOffsetY` | `12`, `16` | Gap from cursor to tooltip in px. |\n| `hysteresisPx` | `20` | Clearance required before un-flipping from an edge-overflow position. Prevents flicker. Bypassed in anchored mode. |\n| `edgePadPx` | `8` | Minimum distance from viewport edge. |\n| `minWidth`, `maxWidth` | `120`, `300` | Size bounds. |\n| `role` | `'tooltip'` | ARIA role. |\n| `ariaLabel` | — | Describes the panel for screen readers. |\n| `class`, `panelClass`, `portalTarget` | — | Passthrough styling / mount hooks. |\n\n## Viewport clamping with hysteresis\n\nDefault position is below-right of the cursor. If the tooltip would overflow the right or bottom edge, it flips to the opposite side. Once flipped, it requires `hysteresisPx` of clearance before flipping back — this prevents the tooltip from jittering when the cursor is right at the boundary.\n\n## Anchored placement\n\nPassing an `anchor` switches the panel from following the cursor to taking a side of a rect:\n\n```tsx\nlet field!: HTMLDivElement;\n\n<KvTooltip\n  entries={quote}\n  anchor={() => field.getBoundingClientRect()}\n  placement=\"above-start\"\n  hideOnPointerDown\n>\n  <div ref={field}>SPY</div>\n</KvTooltip>\n```\n\nWhy it exists: a panel placed at a cursor *point* can only stay clear of a menu opening from the same trigger by luck. Anchoring to the trigger's *rect* lets the tooltip take one side while the menu takes the other, so neither covers the other. That matters specifically because the native Popover API paints in the browser **top layer** — this Portal-rendered panel is ordinary stacking content and can never paint above an open popover at *any* z-index. Placement, not z-index, is the fix.\n\nOverflow flips to the opposite side of the **rect**, never onto it: an `above-*` placement on a trigger near the top of the window moves *below* the trigger rather than sliding down on top of it. Horizontal overflow switches `-start` alignment to `-end` (and back) rather than jumping a full panel width. `hysteresisPx` is bypassed here — it damps a moving cursor, and a static rect cannot flicker.\n\nIf the panel fits on neither side, it keeps the side with more room and stays flush against the anchor, overflowing the viewport edge instead. Covering the anchor defeats the point of anchoring, so viewport overflow is the lesser failure.\n\n## Scroll\n\nAny clamped position — anchored or cursor — re-derives on scroll, via a single shared capture-phase listener (`scroll` does not bubble out of a nested scroller, so a bubble-phase listener would miss exactly the case that matters). An `anchor` passed as an accessor therefore tracks its element down the page on its own. Set `hideOnScroll` when the tooltip's *content* goes stale on scroll, not merely its geometry.\n\n## Theming\n\n```css\n:root {\n  --kv-bg: #0f172a;\n  --kv-border: #334155;\n  --kv-key-color: #64748b;\n  --kv-value-color: #e2e8f0;\n  --kv-separator-color: #334155;\n  --kv-radius: 5px;\n  --kv-shadow: 0 4px 16px rgba(0, 0, 0, 0.5);\n  --kv-padding: 6px 9px;\n  --kv-key-font-size: 10px;\n  --kv-value-font-size: 11px;\n  --kv-key-min-width: 32px;\n  --kv-gap: 8px;\n  --kv-line-height: 1.6;\n  --kv-min-width: 120px;\n  --kv-max-width: 300px;\n}\n```\n\n## Future ideas (not shipped)\n\n- Full WAI-ARIA focus-triggered tooltip pattern (also appears on keyboard focus, dismisses on Escape). Current version is mouse-only.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}