state-hub/dashboard/src/components/doc-overlay.js

/**
 * doc-overlay — hoverable ? button that opens a documentation page in an overlay.
 *
 * Usage:
 *   import {withDocHelp} from "./components/doc-overlay.js";
 *
 *   const el = html`<div class="my-card">...</div>`;
 *   withDocHelp(el, "/docs/my-page");   // mutates el in place, returns it
 *   display(el);
 *
 * The element must have position:relative (or set it via inline style before calling).
 * The ? button is invisible until the user hovers over the element.
 */

const _STYLE_ID   = "doc-overlay-styles";
const _titleCache = new Map();

async function _fetchDocTitle(docPath) {
  if (_titleCache.has(docPath)) return _titleCache.get(docPath);
  try {
    const res = await fetch(docPath);
    if (!res.ok) return null;
    const parser = new DOMParser();
    const doc    = parser.parseFromString(await res.text(), "text/html");
    const title  = doc.querySelector("h1")?.textContent?.trim() ?? null;
    if (title) _titleCache.set(docPath, title);
    return title;
  } catch { return null; }
}

function _ensureStyles() {
  if (typeof document === "undefined" || document.getElementById(_STYLE_ID)) return;
  const s = document.createElement("style");
  s.id = _STYLE_ID;
  s.textContent = `
/* ── ? help button ─────────────────────────────────────────────────────────── */
.doc-help-btn {
  position: absolute;
  top: 0.45rem;
  right: 0.45rem;
  width: 1.25rem;
  height: 1.25rem;
  border-radius: 50%;
  border: 1px solid var(--theme-foreground-faint, #ccc);
  background: var(--theme-background, #fff);
  color: var(--theme-foreground-muted, #999);
  font-size: 0.65rem;
  font-weight: 700;
  cursor: pointer;
  display: flex;
  align-items: center;
  justify-content: center;
  opacity: 0;
  transition: opacity 0.15s, background 0.15s, border-color 0.15s;
  z-index: 10;
  padding: 0;
  line-height: 1;
  font-family: var(--sans-serif, system-ui, sans-serif);
}
.doc-help-wrap:hover .doc-help-btn,
.doc-help-btn:focus-visible {
  opacity: 1;
}
.doc-help-btn:hover {
  background: var(--theme-background-alt, #f0f0f0);
  border-color: steelblue;
  color: steelblue;
}

/* ── overlay backdrop ───────────────────────────────────────────────────────── */
.doc-overlay {
  position: fixed;
  inset: 0;
  background: rgba(0, 0, 0, 0.45);
  z-index: 9000;
  display: flex;
  align-items: center;
  justify-content: center;
  animation: _doc-fade-in 0.15s ease;
}
@keyframes _doc-fade-in {
  from { opacity: 0; }
  to   { opacity: 1; }
}

/* ── overlay box ────────────────────────────────────────────────────────────── */
.doc-overlay-box {
  width: min(780px, 92vw);
  height: 82vh;
  background: var(--theme-background, #fff);
  border-radius: 12px;
  box-shadow: 0 16px 56px rgba(0, 0, 0, 0.28);
  overflow: hidden;
  display: flex;
  flex-direction: column;
  animation: _doc-rise 0.15s ease;
}
@keyframes _doc-rise {
  from { transform: translateY(14px); opacity: 0; }
  to   { transform: translateY(0);    opacity: 1; }
}

/* ── overlay header bar ─────────────────────────────────────────────────────── */
.doc-overlay-header {
  display: flex;
  align-items: center;
  justify-content: flex-end;
  padding: 0.45rem 0.75rem;
  border-bottom: 1px solid var(--theme-foreground-faint, #e8e8e8);
  background: var(--theme-background-alt, #f7f7f7);
  flex-shrink: 0;
  gap: 0.5rem;
}
.doc-overlay-hint {
  font-size: 0.75rem;
  color: var(--theme-foreground-faint, #aaa);
  margin-right: auto;
}
.doc-overlay-close {
  background: none;
  border: 1px solid transparent;
  cursor: pointer;
  font-size: 0.82rem;
  color: var(--theme-foreground-muted, #888);
  padding: 0.2rem 0.55rem;
  border-radius: 6px;
  line-height: 1.2;
  font-family: inherit;
}
.doc-overlay-close:hover {
  border-color: var(--theme-foreground-faint, #ccc);
  background: var(--theme-background, #fff);
  color: var(--theme-foreground, #111);
}

/* ── iframe ─────────────────────────────────────────────────────────────────── */
.doc-overlay-frame {
  flex: 1;
  border: none;
  width: 100%;
}
`;
  document.head.append(s);
}

function _openOverlay(docPath) {
  // Remove any existing overlay
  document.getElementById("_doc-overlay-root")?.remove();

  const root = document.createElement("div");
  root.id = "_doc-overlay-root";
  root.className = "doc-overlay";
  root.setAttribute("role", "dialog");
  root.setAttribute("aria-modal", "true");

  const box = document.createElement("div");
  box.className = "doc-overlay-box";

  const header = document.createElement("div");
  header.className = "doc-overlay-header";

  const hint = document.createElement("span");
  hint.className = "doc-overlay-hint";
  hint.textContent = "Press Esc or click outside to close";

  const closeBtn = document.createElement("button");
  closeBtn.className = "doc-overlay-close";
  closeBtn.textContent = "✕ close";
  closeBtn.setAttribute("aria-label", "Close documentation");

  header.append(hint, closeBtn);

  const frame = document.createElement("iframe");
  frame.className = "doc-overlay-frame";
  frame.src = docPath;
  frame.setAttribute("loading", "lazy");
  frame.title = "Documentation";

  box.append(header, frame);
  root.append(box);
  document.body.append(root);

  const close = () => root.remove();

  closeBtn.addEventListener("click", close);
  root.addEventListener("click", e => { if (e.target === root) close(); });

  const onKey = e => {
    if (e.key === "Escape") { close(); document.removeEventListener("keydown", onKey); }
  };
  document.addEventListener("keydown", onKey);
}

/**
 * Adds a hoverable ? button to an element that opens a documentation overlay.
 *
 * @param {HTMLElement} element  - Element to annotate. Must have position:relative.
 * @param {string}      docPath  - Root-relative URL, e.g. "/docs/decisions-kpi"
 * @returns {HTMLElement}          The element (mutated in place).
 */
export function withDocHelp(element, docPath) {
  _ensureStyles();

  element.classList.add("doc-help-wrap");

  const btn = document.createElement("button");
  btn.className = "doc-help-btn";
  btn.textContent = "?";
  btn.setAttribute("aria-label", "Open documentation");
  btn.addEventListener("click", e => { e.stopPropagation(); _openOverlay(docPath); });

  // Lazy-load the h1 of the target doc page as a native tooltip (bubblehelp)
  btn.addEventListener("mouseenter", async () => {
    if (btn.dataset.titleFetched) return;
    btn.dataset.titleFetched = "1";
    const title = await _fetchDocTitle(docPath);
    if (title) btn.title = title;
  }, {once: true});

  element.append(btn);
  return element;
}