@datalabz_/dashboard-kit 4.0.0

package/v4.js

@@ -0,0 +1,1093 @@
+/* DashboardKit v4.js */
+(function (global) {
+  'use strict';
+
+  // Default gateway. The parent may name its own via `endpoint` in
+  // CUSTOM_DASHBOARDS_PARAMS (each BackOffice has its own); omitted → this one.
+  const DEFAULT_ENDPOINT = "https://aidqgateway.draftplaza.com/aidq";
+  // Retry is off: 1 = a single attempt. Set to 2 to re-enable one retry for
+  // whatever _isRetryable allows (no response, 5xx, 200 without rows).
+  const MAX_ATTEMPTS = 1;
+
+  // ── State ────────────────────────────────────────────────────────────────────
+  let _authToken = '';
+  let _endpoint = DEFAULT_ENDPOINT;
+  let _dateFromIso = '';
+  let _dateToIso = '';
+  let _timezone = '';
+  let _hierarchyId = null;
+  let _hasBooted = false;
+  let _activeTabId = '';
+  let _sections = [];   // { id, label, load, loaded, errors }
+  let _title = '';
+  let _gitVer = '5f9741d'; // replaced at deploy: sed -i "s/5f9741d/$(git rev-parse --short HEAD)/g" v4.js
+  let _calls = [];   // System Info call log
+  let _sectionErrors = {}; // sectionId → error count
+  let _generation = 0;
+  let _ttEl = null;
+
+  // ── Inject CSS ───────────────────────────────────────────────────────────────
+  // v4.css is expected to be loaded via <link> alongside this script.
+  // No runtime injection — keeps CSP simple and avoids FOUC.
+
+  // ── Helpers ──────────────────────────────────────────────────────────────────
+  function esc(s) {
+    return String(s == null ? '' : s)
+      .replace(/&/g, '&amp;').replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+  }
+
+  function fmtAmount(v) {
+    const n = parseFloat(v);
+    if (isNaN(n)) return '—';
+    return n.toFixed(2).replace(/\d(?=(\d{3})+\.)/g, '$&,');
+  }
+
+  function fmtInt(v) {
+    if (v == null) return '—';
+    return String(v);
+  }
+
+  function _fmtDate(iso, tz, withTime) {
+    if (!iso) return '—';
+    try {
+      const p = {};
+      new Intl.DateTimeFormat('en-CA', {
+        timeZone: tz || _timezone || 'UTC',
+        day: '2-digit', month: '2-digit', year: 'numeric',
+        hour: '2-digit', minute: '2-digit', second: '2-digit', hourCycle: 'h23',
+      }).formatToParts(new Date(iso)).forEach(function (x) { p[x.type] = x.value; });
+      const date = p.day + '.' + p.month + '.' + p.year;
+      return withTime ? date + ' ' + p.hour + ':' + p.minute + ':' + p.second : date;
+    } catch { return withTime ? iso : String(iso).slice(0, 10); }
+  }
+
+  const CALENDAR_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+  // DD.MM.YYYY for a bare YYYY-MM-DD that names a real day; null otherwise, so anything else
+  // (2026-13-01, 2026-02-30) takes the existing path and formats exactly as it did before.
+  function _calendarDay(iso) {
+    const m = typeof iso === 'string' ? CALENDAR_DATE.exec(iso) : null;
+    if (!m) return null;
+    const t = new Date(Date.UTC(+m[1], m[2] - 1, +m[3]));
+    return t.getUTCMonth() === m[2] - 1 && t.getUTCDate() === +m[3] ? m[3] + '.' + m[2] + '.' + m[1] : null;
+  }
+
+  // A calendar date (a Postgres `date`, e.g. a birth date) names a day, not a moment:
+  // show that day, whatever the timezone. Instants still format in the report's timezone.
+  function fmtDate(iso, tz) {
+    return _calendarDay(iso) || _fmtDate(iso, tz, false);
+  }
+
+  // A calendar date has no time of day, so it is shown as the date alone; 00:00:00 would invent one.
+  function fmtDatetime(iso, tz) {
+    return _calendarDay(iso) || _fmtDate(iso, tz, true);
+  }
+
+  function formatCurrency(amount, currency) {
+    const n = fmtAmount(amount);
+    return currency ? `${currency} ${n}` : n;
+  }
+
+  function formatPercent(v, decimals) {
+    const n = parseFloat(v);
+    if (isNaN(n)) return '—';
+    return n.toFixed(decimals ?? 2) + '%';
+  }
+
+  function colorClass(v) {
+    const n = Number(v);
+    return n > 0 ? 'pos' : n < 0 ? 'neg' : '';
+  }
+
+  // ── Tooltip ──────────────────────────────────────────────────────────────────
+  function _initTooltip() {
+    if (_ttEl) return;
+    _ttEl = document.createElement('div');
+    _ttEl.id = 'dk-tt';
+    document.body.appendChild(_ttEl);
+    let _cur = null;
+    document.addEventListener('mouseover', function (e) {
+      const tip = e.target.closest('.dk-tip');
+      if (tip === _cur) return;
+      _cur = tip;
+      if (!tip) { _ttEl.style.opacity = '0'; return; }
+      const text = tip.getAttribute('data-tooltip');
+      if (!text) return;
+      _ttEl.textContent = text;
+      _ttEl.style.display = 'block';
+      _ttEl.style.opacity = '0';
+      requestAnimationFrame(function () {
+        const r = tip.getBoundingClientRect();
+        const tw = _ttEl.offsetWidth, th = _ttEl.offsetHeight;
+        _ttEl.style.left = Math.max(4, Math.min(r.left + r.width / 2 - tw / 2, window.innerWidth - tw - 4)) + 'px';
+        _ttEl.style.top = (r.top - th - 6) + 'px';
+        _ttEl.style.opacity = '1';
+      });
+    });
+    document.addEventListener('mouseout', function (e) {
+      if (_cur && !_cur.contains(e.relatedTarget)) {
+        _cur = null;
+        _ttEl.style.opacity = '0';
+      }
+    });
+  }
+
+  // ── Status pill ───────────────────────────────────────────────────────────────
+  function _setPill(state, label) {
+    const p = document.getElementById('dk-pill');
+    if (!p) return;
+    p.className = 'dk-pill ' + state;
+    p.textContent = label;
+  }
+
+  // ── postMessage ───────────────────────────────────────────────────────────────
+  function _isGatewayUrl(v) {
+    if (typeof v !== 'string' || !v) return false;
+    try {
+      const u = new URL(v);
+      return u.protocol === 'https:' ||
+        (u.protocol === 'http:' && (u.hostname === 'localhost' || u.hostname === '127.0.0.1'));
+    } catch { return false; }
+  }
+
+  function _onMessage(e) {
+    if (!e.data || typeof e.data !== 'object') return;
+    if (e.data.type === 'RK_SNAPSHOT') { _snapshot(); return; }
+    if (e.data.type === 'CHAT_MODE') { document.documentElement.dataset.chatMode = 'true'; return; }
+    if (e.data.type !== 'CUSTOM_DASHBOARDS_PARAMS') return;
+
+    if (typeof e.data.token === 'string') _authToken = e.data.token;
+
+    // The token rides on every call to the endpoint, so only the parent may set
+    // it, and only to an https URL (http for localhost dev). Anything else is
+    // ignored and the current endpoint stays.
+    if (e.data.endpoint !== undefined) {
+      if (e.source === window.parent && _isGatewayUrl(e.data.endpoint)) _endpoint = e.data.endpoint;
+      else console.warn('[DashboardKit] endpoint ignored:', e.data.endpoint);
+    }
+
+    if (e.data.theme === 'light' || e.data.theme === 'dark')
+      document.documentElement.dataset.theme = e.data.theme;
+
+    const f = e.data.filters;
+    if (f && typeof f === 'object') {
+      if (typeof f.dateFrom === 'string') _dateFromIso = f.dateFrom;
+      if (typeof f.dateTo === 'string') _dateToIso = f.dateTo;
+      if (typeof f.timezone === 'string') _timezone = f.timezone;
+      if ('hierarchyId' in f)
+        _hierarchyId = f.hierarchyId == null ? null : Number(f.hierarchyId);
+    }
+
+    if (!_hasBooted && _authToken && _dateFromIso && _dateToIso && _timezone) {
+      _hasBooted = true;
+      const wait = document.getElementById('dk-wait');
+      if (wait) wait.hidden = true;
+      _buildTabNav();
+      _activateTab(_sections[0].id);
+    } else if (_hasBooted) {
+      _invalidateAll();
+      _loadSection(_activeTabId);
+    }
+  }
+
+  // ── Tab state machine ─────────────────────────────────────────────────────────
+  function _buildTabNav() {
+    const nav = document.getElementById('dk-tabs');
+    if (!nav) return;
+    nav.innerHTML = '';
+    _sections.forEach(function (s) {
+      const btn = document.createElement('button');
+      btn.id = 'dk-tab-' + s.id;
+      btn.textContent = s.label;
+      if (s.tooltip) {
+        const icon = document.createElement('span');
+        icon.className = 'dk-tip';
+        icon.setAttribute('data-tooltip', s.tooltip);
+        icon.textContent = 'i';
+        btn.appendChild(icon);
+      }
+      btn.addEventListener('click', function () { _activateTab(s.id); });
+      nav.appendChild(btn);
+    });
+    _renderTabBtns();
+  }
+
+  function _renderTabBtns() {
+    _sections.forEach(function (s) {
+      const btn = document.getElementById('dk-tab-' + s.id);
+      if (!btn) return;
+      btn.className = s.id === _activeTabId ? 'active' : '';
+      const old = btn.querySelector('.dk-badge');
+      if (old) old.remove();
+      if (s.errors > 0) {
+        const b = document.createElement('span');
+        b.className = 'dk-badge';
+        b.textContent = s.errors;
+        btn.appendChild(b);
+      }
+    });
+  }
+
+  function _activateTab(id) {
+    _activeTabId = id;
+    document.querySelectorAll('.dk-panel').forEach(function (p) {
+      p.classList.remove('active');
+    });
+    const panel = document.getElementById('dk-panel-' + id);
+    if (panel) panel.classList.add('active');
+    _renderTabBtns();
+    const sec = _sections.find(function (s) { return s.id === id; });
+    if (sec && !sec.loaded) _loadSection(id);
+  }
+
+  function _loadSection(id) {
+    const sec = _sections.find(function (s) { return s.id === id; });
+    const panel = document.getElementById('dk-panel-' + id);
+    if (!sec || !panel) return;
+    sec.loaded = false;
+    _runSectionLoad(sec, panel);
+  }
+
+  function _invalidateAll() {
+    _generation++;
+    _sections.forEach(function (s) { s.loaded = false; s.errors = 0; });
+    _sectionErrors = {};
+    _calls = [];
+    _setPill('', 'idle');
+    _renderSystemInfo();
+  }
+
+  async function _runSectionLoad(sec, panel) {
+    if (sec.id === 'dk-sysinfo') { _renderSystemInfo(); sec.loaded = true; return; }
+    const gen = _generation;
+    // _sectionErrors is cumulative for the whole session, only ever cleared by
+    // _invalidateAll() — a full-dashboard Refresh. Retry reloads one section on
+    // its own, so without this reset a section that fails once, then succeeds
+    // on retry, would keep showing its old error badge forever.
+    _sectionErrors[sec.id] = 0;
+    setSectionState(panel, 'loading');
+    _setPill('loading', 'loading…');
+    try {
+      await sec.load({
+        runQuery,
+        formatCurrency,
+        formatPercent,
+        formatInteger: fmtInt,
+        formatDate: fmtDate,
+        formatDatetime: fmtDatetime,
+        renderTable,
+        renderKpiCard,
+        renderKpiStrip,
+        renderInfoGrid,
+        renderTotalsStrip,
+        escHtml: esc,
+        colorClass,
+        filters: DashboardKit.filters,
+      });
+      if (gen !== _generation) return;
+      sec.loaded = true;
+      sec.errors = _sectionErrors[sec.id] || 0;
+    } catch (e) {
+      // The real exception, stack and dkCall included — the panel and the report only get a phrase.
+      console.error('[DashboardKit] section "' + sec.id + '" failed:', e);
+      console.log('[DashboardKit] section "' + sec.id + '" failed:', e);
+      if (gen !== _generation) return;
+      setSectionState(panel, 'error', e.message || String(e), e && e.dkCall, e && e.stack);
+      sec.errors = _sectionErrors[sec.id] || 0;
+      sec.loaded = true;
+    }
+    _renderTabBtns();
+    _refreshPill();
+    _renderSystemInfo();
+  }
+
+  function _refreshPill() {
+    const anyErr = Object.keys(_sectionErrors).some(function (k) { return _sectionErrors[k] > 0; });
+    _setPill(anyErr ? 'error' : 'ok', anyErr ? 'error' : 'ok');
+  }
+
+  // ── Failure kind ─────────────────────────────────────────────────────────
+  // One question: did a response arrive? 'transport' = no (network/CORS/DNS),
+  // 'gateway' = yes, whatever the status or body. Who is to blame is read from
+  // the status and the gateway's own fields by the host/server, not here.
+  // Builds the exception a failed call throws, diagnosis attached as err.dkCall —
+  // with parallel runQuery calls, searching _calls afterwards is ambiguous.
+  function _failure(entry, kind) {
+    const err = new Error(entry.error);
+    const r = entry.response || {};
+    const gw = kind === 'gateway';
+    // '' is refused by the server; null is "not present".
+    const s = function (v) { return typeof v === 'string' && v.length ? v : null; };
+    let detail = gw
+      ? s(r.error || r.message || (typeof r._raw === 'string' ? r._raw.slice(0, 200) : ''))
+      : s(entry.browserMessage);
+    // pg_position has no wire field of its own — the one permitted append.
+    if (detail && gw && r.pg_position != null) detail += ' [pg_position ' + r.pg_position + ']';
+    err.dkCall = {
+      kind,
+      label: entry.label, sql: entry.sql, args: entry.args,
+      durationMs: entry.durationMs, clientMs: entry.clientMs,
+      status: entry.status,
+      error: entry.error,
+      detail: detail,
+      errorCode: gw ? s(r.error_code) : null,
+      pgDetail: gw ? s(r.pg_detail) : null,
+      pgHint: gw ? s(r.pg_hint) : null,
+      trackId: gw ? s(r.track_id) : null,
+    };
+    return err;
+  }
+
+  // By status, not kind: no response and 5xx may clear on their own; a 200
+  // without { rows } is a proxy/captive portal; 4xx (408 included) is deterministic.
+  function _isRetryable(entry) {
+    if (entry.status === null) return true;
+    if (entry.status >= 500) return true;
+    if (entry.status === 200) return true;
+    return false;
+  }
+
+  // Randomized so every dashboard open against a recovering service doesn't
+  // retry in the same instant and hammer it right as it's coming back —
+  // the gateway team's own warning: retrying a struggling backend in lockstep
+  // makes things worse, not better.
+  function _retryDelay() {
+    return new Promise(function (resolve) { setTimeout(resolve, 800 + Math.random() * 700); });
+  }
+
+  // ── runQuery ──────────────────────────────────────────────────────────────────
+  // One retry, only where _isRetryable says the same request may succeed.
+  async function runQuery(sectionId, callLabel, sql, args, params) {
+    const t0 = performance.now();
+    const entry = {
+      index: _calls.length + 1,
+      sectionId, label: callLabel, sql,
+      args: args || [],
+      requestHeaders: { 'Content-Type': 'application/json', Authorization: 'Bearer ***' },
+      status: null, clientMs: null, durationMs: null, serverMs: null,
+      bytes: null, rowCount: null, response: null,
+      error: null, state: 'running',
+      ts: new Date().toISOString(),
+    };
+    _calls.push(entry);
+
+    const body = { sql };
+    if (args && args.length) body.args = args;
+    if (params && params.hierarchy_id != null) body.hierarchy_id = params.hierarchy_id;
+    else if (_hierarchyId != null) body.hierarchy_id = _hierarchyId;
+
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+      // Cleared each attempt so a stale status/text from a prior try can't
+      // classify or describe this one.
+      entry.status = null;
+      entry.error = null;
+      entry.browserMessage = null;
+      const ta = performance.now(); // this attempt only — clientMs includes the retry pause
+      try {
+        const res = await fetch(_endpoint, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + _authToken },
+          body: JSON.stringify(body),
+        });
+        entry.status = res.status;
+        const text = await res.text();
+        entry.bytes = text.length;
+        let data;
+        try { data = JSON.parse(text); } catch { data = { _raw: text }; }
+        entry.response = data;
+        entry.clientMs = Math.round(performance.now() - t0);
+        entry.durationMs = Math.round(performance.now() - ta);
+
+        // A 200 whose body isn't { rows: [...] } (proxy HTML, truncated JSON) is
+        // a gateway failure too, not an empty result.
+        let failed = false;
+        if (!res.ok) {
+          entry.error = 'HTTP ' + res.status + ': ' + (data && (data.error || data.message) || text);
+          failed = true;
+        } else if (!Array.isArray(data.rows)) {
+          entry.error = 'HTTP 200 but the body is not { rows: [...] }' +
+            (data._raw !== undefined ? ' — not JSON: ' + text.slice(0, 200) : '');
+          failed = true;
+        }
+        if (failed) {
+          if (attempt < MAX_ATTEMPTS && _isRetryable(entry)) {
+            entry.retried = true;
+            await _retryDelay();
+            continue;
+          }
+          entry.state = 'error';
+          _sectionErrors[sectionId] = (_sectionErrors[sectionId] || 0) + 1;
+          throw _failure(entry, 'gateway');
+        }
+        entry.serverMs = data.duration_ms ?? null;
+        entry.rowCount = data.rows.length;
+        entry.state = 'ok';
+        return data.rows;
+      } catch (err) {
+        // The failed-response throw lands here too — already built.
+        if (err && err.dkCall) throw err;
+        entry.clientMs = Math.round(performance.now() - t0);
+        entry.durationMs = Math.round(performance.now() - ta);
+        if (entry.status === null) {
+          // The browser's own message goes to the wire untouched; the suffix is
+          // for System Info only.
+          entry.browserMessage = err.message;
+          entry.error = err.message + ' [no HTTP response — network/CORS error]';
+        } else if (!entry.error) {
+          entry.error = err.message;
+        }
+        if (attempt < MAX_ATTEMPTS && _isRetryable(entry)) {
+          entry.retried = true;
+          await _retryDelay();
+          continue;
+        }
+        entry.state = 'error';
+        _sectionErrors[sectionId] = (_sectionErrors[sectionId] || 0) + 1;
+        throw _failure(entry, entry.status === null ? 'transport' : 'gateway');
+      }
+    }
+  }
+
+  // ── Container resolution ──────────────────────────────────────────────────────
+  // Shared by setSectionState and every render primitive: accepts a CSS selector
+  // string or a DOM element, throws (fail loud) instead of silently rendering
+  // nothing when it resolves to nothing. Called from inside a section's load(),
+  // the throw propagates through the kit's own try/catch into the section's
+  // error state — same path a failed runQuery already uses.
+  function resolveContainer(fnName, arg) {
+    const el = typeof arg === 'string' ? document.querySelector(arg) : arg;
+    if (!el) {
+      const shown = typeof arg === 'string' ? `"${arg}"` : String(arg);
+      throw new Error(`${fnName}: container ${shown} matched no element`);
+    }
+    return el;
+  }
+
+  // ── Header filter values ─────────────────────────────────────────────────────
+  // Generic — reads whatever dashboard-specific inputs/selects the author put in
+  // <header data-dk-header>, keyed by element id. Dashboards define their own
+  // filters beyond date/timezone/hierarchy, so the kit can't hardcode field names.
+  function _headerFilterValues() {
+    const header = document.querySelector('[data-dk-header]');
+    const out = {};
+    if (!header) return out;
+    header.querySelectorAll('input, select').forEach(function (el) {
+      if (el.id) out[el.id] = el.value;
+    });
+    return out;
+  }
+
+  // ── Error report ── the turn:dashboard-error wire shape, nothing else. The host
+  // adds chatId/dashboardFile and strips what the kit appends after it.
+  function _wireReport(sectionId, sectionLabel, failedCall, msg, stack) {
+    if (!failedCall) {
+      return {
+        kind: 'script', phase: 'section',
+        sectionId: sectionId, sectionLabel: sectionLabel,
+        error: { message: msg || '', stack: stack || null },
+      };
+    }
+    const w = {
+      kind: failedCall.kind, // 'transport' | 'gateway'
+      sectionId: sectionId, sectionLabel: sectionLabel,
+      callLabel: failedCall.label,
+      sql: failedCall.sql, args: failedCall.args || [],
+      durationMs: failedCall.durationMs,
+      detail: failedCall.detail,
+    };
+    if (failedCall.kind === 'gateway') {
+      w.status = failedCall.status;
+      w.errorCode = failedCall.errorCode;
+      w.pgDetail = failedCall.pgDetail;
+      w.pgHint = failedCall.pgHint;
+      w.trackId = failedCall.trackId;
+    }
+    return w;
+  }
+
+  // ── Section state helpers ─────────────────────────────────────────────────────
+  function setSectionState(container, state, msg, failedCall, stack) {
+    container = resolveContainer('setSectionState', container);
+    if (state === 'loading') {
+      container.innerHTML =
+        '<div class="dk-loading"><span class="dk-spinner"></span>Loading…</div>';
+    } else if (state === 'error') {
+      // A caller can be the section panel itself or, from a dashboard's own
+      // load(), an arbitrary sub-container inside it — either way the nearest
+      // .dk-panel ancestor is the section that actually failed. Falling back to
+      // _activeTabId only covers the (shouldn't-happen) case of an element
+      // outside any panel.
+      const ownPanel = container.closest ? container.closest('.dk-panel') : null;
+      const sectionId = ownPanel ? ownPanel.id.replace('dk-panel-', '') : _activeTabId;
+      const sec = _sections.find(function (s) { return s.id === sectionId; });
+      // failedCall is err.dkCall from runQuery; without one the rejection didn't
+      // come from a gateway call at all — that's kind 'script'. The operator gets
+      // a fixed phrase; the raw text goes to the parent via "Ask AI to fix" and to
+      // System Info. No panel Retry: the header's Refresh covers it.
+      container.innerHTML =
+        '<div class="dk-error"><span>This view couldn\'t load — try Refresh.</span>' +
+        '<button class="dk-error-report-btn" type="button">Ask AI to fix</button></div>';
+
+      const reportBtn = container.querySelector('.dk-error-report-btn');
+      if (reportBtn) {
+        reportBtn.addEventListener('click', function () {
+          const dashboardSections = _sections.filter(function (s) { return s.id !== 'dk-sysinfo'; });
+          const failedSections = dashboardSections.filter(function (s) { return (s.errors || 0) > 0; }).length;
+          window.parent.postMessage(Object.assign(
+            { type: 'DASHBOARD_ERROR' },
+            _wireReport(sectionId, sec ? sec.label : '', failedCall, msg, stack),
+            {
+              // Host-only, stripped before the socket.
+              title: _title,
+              message: msg || '',
+              sectionErrorCount: sec ? sec.errors : 0,
+              totalSections: dashboardSections.length,
+              failedSections: failedSections,
+              filters: Object.assign(
+                {
+                  dateFromIso: _dateFromIso,
+                  dateToIso: _dateToIso,
+                  timezone: _timezone,
+                  hierarchyId: _hierarchyId,
+                },
+                _headerFilterValues(),
+              ),
+              call: failedCall,
+            },
+          ), '*');
+          reportBtn.disabled = true;
+          reportBtn.textContent = 'Sent ✓';
+          setTimeout(function () {
+            reportBtn.disabled = false;
+            reportBtn.textContent = 'Ask AI to fix';
+          }, 1500);
+        });
+      }
+    } else if (state === 'empty') {
+      container.innerHTML =
+        '<div class="dk-empty">No data for the selected period.</div>';
+    }
+  }
+
+  // ── renderTable ───────────────────────────────────────────────────────────────
+  // columns: [{ key, label, format?, sortable?, tooltip? }]
+  //   format receives (value, row) — read row.<key> for per-row currency, etc.
+  // totalsRow: [label|{key,agg}] matching columns length — optional
+  // tableTitle: table heading; also the CSV filename — omit to hide title + CSV button
+  function renderTable(containerOrSelector, rows, schema) {
+    const container = resolveContainer('renderTable', containerOrSelector);
+
+    const { columns = [], totalsRow, tableTitle } = schema || {};
+
+    if (!rows || !rows.length) {
+      container.innerHTML = '<div class="dk-empty">No data for the selected period.</div>';
+      return;
+    }
+
+    let sortKey = null, sortDir = 'asc';
+
+    function buildBodyRows(data) {
+      return data.map(function (row) {
+        return '<tr>' + columns.map(function (col) {
+          const raw = row[col.key];
+          const displayed = col.format ? col.format(raw, row) : (raw == null ? '—' : raw);
+          return '<td>' + esc(displayed) + '</td>';
+        }).join('') + '</tr>';
+      }).join('');
+    }
+
+    function sortedRows() {
+      if (!sortKey) return rows;
+      return rows.slice().sort(function (a, b) {
+        let av = a[sortKey], bv = b[sortKey];
+        if (av != null && bv != null && !isNaN(+av) && !isNaN(+bv)) { av = +av; bv = +bv; }
+        if (av == null && bv == null) return 0;
+        if (av == null) return 1;
+        if (bv == null) return -1;
+        const cmp = av < bv ? -1 : av > bv ? 1 : 0;
+        return sortDir === 'asc' ? cmp : -cmp;
+      });
+    }
+
+    // Totals row
+    let totalsHtml = '';
+    if (totalsRow) {
+      totalsHtml = '<tr class="dk-totals-row">';
+      totalsRow.forEach(function (cell, i) {
+        const col = columns[i] || {};
+        if (typeof cell === 'string' || cell == null) {
+          totalsHtml += '<td>' + esc(cell ?? '—') + '</td>';
+        } else if (cell && cell.agg === 'sum') {
+          const sum = rows.reduce(function (a, r) { return a + (Number(r[cell.key]) || 0); }, 0);
+          const fmt = col.format || function (v) { return v; };
+          // Totals have no single row; pass an empty row so a per-row-currency
+          // formatter degrades gracefully instead of throwing. Don't sum a
+          // mixed-currency column (see the all-currencies note in the docs).
+          let out;
+          try { out = fmt(sum, {}); } catch { out = '—'; }
+          totalsHtml += '<td>' + esc(out) + '</td>';
+        } else {
+          totalsHtml += '<td>—</td>';
+        }
+      });
+      totalsHtml += '</tr>';
+    }
+
+    const tblId = 'dk-tbl-' + Math.random().toString(36).slice(2, 7);
+    let html = '<div class="dk-table-wrap">';
+    html += '<div class="dk-toolbar">';
+    if (tableTitle) html += '<span class="dk-table-title">' + esc(tableTitle) + '</span>';
+    html += '<button class="dk-csv-btn" data-dk-csv="' + tblId + '">CSV ↓</button>';
+    html += '</div>';
+    html += '<table class="dk-table" id="' + tblId + '"><thead><tr>';
+    columns.forEach(function (col) {
+      const sortAttr = col.sortable === true ? ' data-dk-sort-key="' + esc(col.key) + '"' : '';
+      const tipHtml = col.tooltip ? '<span class="dk-tip" data-tooltip="' + esc(col.tooltip) + '">i</span>' : '';
+      html += '<th' + sortAttr + '><div class="dk-th-inner"><span>' + esc(col.label) + '</span>' + tipHtml + '</div></th>';
+    });
+    html += '</tr></thead><tbody>';
+    if (totalsHtml) html += totalsHtml;
+    html += buildBodyRows(rows);
+    html += '</tbody></table></div>';
+
+    container.innerHTML = html;
+
+    // Sort handler
+    const tblEl = container.querySelector('#' + tblId);
+    tblEl.querySelector('thead').addEventListener('click', function (e) {
+      const th = e.target.closest('th[data-dk-sort-key]');
+      if (!th) return;
+      const key = th.dataset.dkSortKey;
+      sortDir = key === sortKey && sortDir === 'asc' ? 'desc' : 'asc';
+      sortKey = key;
+      tblEl.querySelector('tbody').innerHTML = (totalsHtml || '') + buildBodyRows(sortedRows());
+      tblEl.querySelectorAll('thead th[data-dk-sort-key]').forEach(function (h) {
+        h.classList.remove('dk-sort-asc', 'dk-sort-desc');
+        if (h.dataset.dkSortKey === sortKey) h.classList.add('dk-sort-' + sortDir);
+      });
+    });
+
+    // Wire CSV button
+    const csvBtn = container.querySelector('[data-dk-csv]');
+    if (csvBtn) {
+      csvBtn.addEventListener('click', function () {
+        const tbl = document.getElementById(csvBtn.dataset.dkCsv);
+        if (!tbl) return;
+        const name = [_title, tableTitle].filter(Boolean).concat(fmtDatetime(new Date().toISOString()).replace(/:/g, '-')).join(' - ') + '.csv';
+        _downloadCsv(tbl, name);
+      });
+    }
+  }
+
+  // ── renderKpiCard ─────────────────────────────────────────────────────────────
+  // item: { label, value, colorClass?, tooltip? }
+  function _kpiCardHtml(item) {
+    const cls = 'dk-kpi-value' + (item.colorClass ? ' ' + item.colorClass : '');
+    const tipIcon = item.tooltip ? '<span class="dk-tip" data-tooltip="' + esc(item.tooltip) + '">i</span>' : '';
+    return '<div class="dk-kpi">' +
+      tipIcon +
+      '<div class="dk-kpi-label">' + esc(item.label) + '</div>' +
+      '<div class="' + cls + '">' + esc(item.value) + '</div>' +
+      '</div>';
+  }
+
+  function renderKpiCard(containerOrSelector, item) {
+    const container = resolveContainer('renderKpiCard', containerOrSelector);
+    container.innerHTML = _kpiCardHtml(item);
+  }
+
+  // ── renderKpiStrip ────────────────────────────────────────────────────────────
+  // items: [{ label, value, colorClass? }]
+  // options: { stripTitle? }
+  function renderKpiStrip(containerOrSelector, items, options) {
+    const container = resolveContainer('renderKpiStrip', containerOrSelector);
+    const { stripTitle } = options || {};
+    let html = '';
+    if (stripTitle) html += '<div class="dk-toolbar"><span class="dk-table-title">' + esc(stripTitle) + '</span></div>';
+    html += '<div class="dk-kpi-strip">' +
+      (items || []).map(_kpiCardHtml).join('') +
+      '</div>';
+    container.innerHTML = html;
+  }
+
+  // ── renderInfoGrid ────────────────────────────────────────────────────────────
+  // items: [[label, value, colorClass?], ...]  — renders a responsive key/value grid
+  // options: { gridTitle? }
+  function renderInfoGrid(containerOrSelector, items, options) {
+    const container = resolveContainer('renderInfoGrid', containerOrSelector);
+    const { gridTitle } = options || {};
+    let html = '';
+    if (gridTitle) html += '<div class="dk-toolbar"><span class="dk-table-title">' + esc(gridTitle) + '</span></div>';
+    html += '<div class="dk-info-grid">' +
+      (items || []).map(function (item) {
+        const cls = 'dk-val' + (item[2] ? ' ' + item[2] : '');
+        return '<div class="dk-info-row">' +
+          '<span class="dk-lbl">' + esc(item[0]) + '</span>' +
+          '<span class="' + cls + '">' + esc(item[1] != null ? item[1] : '—') + '</span>' +
+          '</div>';
+      }).join('') +
+      '</div>';
+    container.innerHTML = html;
+  }
+
+  // ── renderTotalsStrip ─────────────────────────────────────────────────────────
+  // items: [[label, value, colorClass?], ...]  — renders a horizontal totals bar
+  // options: { stripTitle? }
+  function renderTotalsStrip(containerOrSelector, items, options) {
+    const container = resolveContainer('renderTotalsStrip', containerOrSelector);
+    const { stripTitle } = options || {};
+    let html = '';
+    if (stripTitle) html += '<div class="dk-toolbar"><span class="dk-table-title">' + esc(stripTitle) + '</span></div>';
+    html += '<div class="dk-totals-strip">' +
+      (items || []).map(function (item) {
+        const cls = 'dk-field-value' + (item[2] ? ' ' + item[2] : '');
+        return '<div class="dk-field">' +
+          '<span class="dk-field-label">' + esc(item[0]) + '</span>' +
+          '<span class="' + cls + '">' + esc(item[1] != null ? item[1] : '—') + '</span>' +
+          '</div>';
+      }).join('') +
+      '</div>';
+    container.innerHTML = html;
+  }
+
+  // ── CSV download ──────────────────────────────────────────────────────────────
+  function _downloadCsv(tableEl, filename) {
+    const rows = [];
+    tableEl.querySelectorAll('tr').forEach(function (tr) {
+      const cells = Array.from(tr.querySelectorAll('th, td')).map(function (td) {
+        const v = td.dataset.csvValue !== undefined ? td.dataset.csvValue : td.textContent.trim();
+        const safe = /^[=+\-@]/.test(String(v)) && !/^-\d/.test(String(v)) ? "'" + String(v) : String(v);
+        return '"' + safe.replace(/"/g, '""') + '"';
+      });
+      if (cells.length) rows.push(cells.join(','));
+    });
+    const blob = new Blob(['' + rows.join('\r\n')], { type: 'text/csv;charset=utf-8' });
+    const a = document.createElement('a');
+    a.href = URL.createObjectURL(blob);
+    a.download = filename;
+    a.click();
+    URL.revokeObjectURL(a.href);
+  }
+
+  // ── Snapshot ──────────────────────────────────────────────────────────────────
+  function _snapshot() {
+    // Freeze current filter values into attributes so cloneNode captures them.
+    document.querySelectorAll('[data-dk-header] input, [data-dk-header-right] input').forEach(function (el) {
+      el.setAttribute('value', el.value);
+    });
+    document.querySelectorAll('[data-dk-header] select, [data-dk-header-right] select').forEach(function (el) {
+      el.querySelectorAll('option').forEach(function (opt) {
+        opt.selected = opt.value === el.value;
+      });
+    });
+
+    const clone = document.documentElement.cloneNode(true);
+
+    // Strip auth token from System Info pre elements
+    if (_authToken) {
+      clone.querySelectorAll('pre').forEach(function (pre) {
+        if (pre.textContent.includes(_authToken))
+          pre.textContent = pre.textContent.replaceAll(_authToken, '***');
+      });
+    }
+
+    // Remove action buttons that make no sense in a static snapshot
+    ['#dk-btn-refresh', '#dk-btn-snapshot'].forEach(function (sel) {
+      const el = clone.querySelector(sel);
+      if (el) el.remove();
+    });
+
+    // Disable all inputs; keep tab buttons enabled
+    clone.querySelectorAll('input, select, button').forEach(function (el) {
+      el.setAttribute('disabled', '');
+    });
+
+    // Remove live scripts
+    clone.querySelectorAll('script').forEach(function (s) { s.remove(); });
+
+    // Re-attach tab-click handlers only
+    const tabScript = document.createElement('script');
+    tabScript.textContent = '(function(){' +
+      'document.querySelectorAll("nav.dk-tabs button").forEach(function(btn){' +
+      'btn.removeAttribute("disabled");' +
+      'btn.addEventListener("click",function(){' +
+      'var id=btn.id.replace("dk-tab-","");' +
+      'document.querySelectorAll(".dk-panel").forEach(function(p){p.classList.remove("active");});' +
+      'var panel=document.getElementById("dk-panel-"+id);' +
+      'if(panel)panel.classList.add("active");' +
+      'document.querySelectorAll("nav.dk-tabs button").forEach(function(b){b.classList.remove("active");});' +
+      'btn.classList.add("active");' +
+      '});' +
+      '});' +
+      '})();';
+    clone.querySelector('body').appendChild(tabScript);
+
+    const dateSlug = (_dateFromIso || '').slice(0, 10);
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const filename = _title + '-snapshot-' + dateSlug + '-' + ts + '.html';
+
+    const blob = new Blob(['<!doctype html>\n' + clone.outerHTML], { type: 'text/html' });
+    const a = document.createElement('a');
+    a.href = URL.createObjectURL(blob);
+    a.download = filename;
+    a.click();
+    URL.revokeObjectURL(a.href);
+  }
+
+  // ── System Info ───────────────────────────────────────────────────────────────
+  function _renderSystemInfo() {
+    const container = document.getElementById('dk-panel-dk-sysinfo');
+    if (!container) return;
+    const calls = _calls;
+    const okN = calls.filter(function (c) { return c.state === 'ok'; }).length;
+    const errN = calls.filter(function (c) { return c.state === 'error'; }).length;
+    const runN = calls.filter(function (c) { return c.state === 'running'; }).length;
+    const totMs = calls.reduce(function (a, c) { return a + (c.clientMs || 0); }, 0);
+    const totB = calls.reduce(function (a, c) { return a + (c.bytes || 0); }, 0);
+    const hasCors = calls.some(function (c) { return c.state === 'error' && c.status === null; });
+
+    const callsHtml = calls.length === 0
+      ? '<p style="color:var(--muted);font-size:12px">No calls yet.</p>'
+      : calls.map(function (c) {
+        const statusLabel = c.status === null
+          ? '<span class="dk-s-net">NET</span>'
+          : c.state === 'ok'
+            ? '<span class="dk-s-ok">' + c.status + '</span>'
+            : '<span class="dk-s-err">' + c.status + '</span>';
+        return '<details class="dk-call"><summary>' +
+          '<span style="color:var(--muted);font-size:11px">#' + c.index + '</span>' +
+          statusLabel +
+          '<span style="flex:1">' + esc(c.label) + '</span>' +
+          '<span style="color:var(--muted);font-size:11px">' + (c.clientMs != null ? c.clientMs + 'ms' : '—') + '</span>' +
+          (c.serverMs != null ? '<span style="color:var(--muted);font-size:11px">srv:' + c.serverMs + 'ms</span>' : '') +
+          (c.rowCount != null ? '<span style="color:var(--muted);font-size:11px">' + c.rowCount + ' rows</span>' : '') +
+          '<span style="color:var(--muted);font-size:10px">' + c.ts.slice(11, 19) + '</span>' +
+          '</summary><div class="dk-call-body">' +
+          (c.error ? '<div class="dk-s-err" style="margin-bottom:6px">' + esc(c.error) + '</div>' : '') +
+          '<p style="font-size:11px;color:var(--muted);margin:0 0 4px">Data Request:</p>' +
+          '<pre>' + esc(c.sql) + '</pre>' +
+          (c.args && c.args.length ? '<p style="font-size:11px;color:var(--muted);margin:8px 0 4px">Args:</p><pre>' + esc(JSON.stringify(c.args, null, 2)) + '</pre>' : '') +
+          '<div class="dk-resp-head">' +
+          '<span>Response:</span><button type="button" class="dk-resp-toggle" aria-label="Toggle response">−</button>' +
+          '</div>' +
+          '<pre class="dk-resp-body">' + esc(JSON.stringify(c.response, null, 2)) + '</pre>' +
+          '</div></details>';
+      }).join('');
+
+    container.innerHTML =
+      '<div class="dk-sysinfo">' +
+      (hasCors ? '<div class="dk-cors-hint">⚠ One or more calls received no HTTP response — likely a CORS or network error. Open DevTools → Network to inspect.</div>' : '') +
+      '<div><h3>Context</h3><table class="dk-sys-table">' +
+      '<tr><td>Version</td><td>' + esc(_gitVer) + '</td></tr>' +
+      '<tr><td>Dashboard title</td><td>' + esc(_title) + '</td></tr>' +
+      '<tr><td>Hierarchy ID</td><td>' + (_hierarchyId != null ? _hierarchyId : '—') + '</td></tr>' +
+      '<tr><td>Timezone</td><td>' + esc(_timezone || '—') + '</td></tr>' +
+      '<tr><td>Day window (UTC)</td><td>' + esc(_dateFromIso) + ' → ' + esc(_dateToIso) + '</td></tr>' +
+      '</table></div>' +
+      '<div><h3>Totals</h3><table class="dk-sys-table">' +
+      '<tr><td>Calls</td><td>' + calls.length + ' (' + okN + ' ok · ' + errN + ' error' + (runN ? ' · ' + runN + ' running' : '') + ')</td></tr>' +
+      '<tr><td>Client duration</td><td>' + totMs + ' ms</td></tr>' +
+      '<tr><td>Bytes received</td><td>' + fmtInt(totB) + '</td></tr>' +
+      '</table></div>' +
+      '<div><h3>Calls <button id="dk-sysinfo-export" style="margin-left:8px;background:transparent;color:var(--brand);border:1px solid var(--brand);border-radius:3px;padding:0 8px;height:22px;font-size:11px;cursor:pointer">Export JSON ↓</button></h3>' +
+      callsHtml + '</div>' +
+      '</div>';
+
+    container.querySelectorAll('.dk-resp-toggle').forEach(function (btn) {
+      btn.addEventListener('click', function () {
+        const pre = btn.parentElement.nextElementSibling;
+        pre.hidden = !pre.hidden;
+        btn.textContent = pre.hidden ? '+' : '−';
+      });
+    });
+
+    const expBtn = document.getElementById('dk-sysinfo-export');
+    if (expBtn) {
+      expBtn.addEventListener('click', function () {
+        const payload = {
+          title: _title,
+          hierarchyId: _hierarchyId, timezone: _timezone,
+          dateFromIso: _dateFromIso, dateToIso: _dateToIso,
+          calls: _calls.map(function (c) {
+            return Object.assign({}, c, { requestHeaders: { 'Content-Type': 'application/json', Authorization: 'Bearer ***' } });
+          }),
+        };
+        const blob = new Blob([JSON.stringify(payload, null, 2)], { type: 'application/json' });
+        const a = document.createElement('a');
+        a.href = URL.createObjectURL(blob);
+        a.download = 'system-info-' + (_dateFromIso || '').slice(0, 10) + '-' + new Date().toISOString().replace(/[:.]/g, '-') + '.json';
+        a.click();
+        URL.revokeObjectURL(a.href);
+      });
+    }
+  }
+
+  // ── Header wiring ─────────────────────────────────────────────────────────────
+  function _buildHeader(title) {
+    const header = document.querySelector('[data-dk-header]');
+    if (!header) return;
+
+    // Collect dashboard-provided content before clearing
+    const dashboardNodes = Array.from(header.childNodes);
+
+    const titleEl = document.createElement('span');
+    titleEl.className = 'dk-title';
+    titleEl.textContent = title;
+
+    const spacer = document.createElement('div');
+    spacer.className = 'dk-spacer';
+
+    const btnRefresh = document.createElement('button');
+    btnRefresh.id = 'dk-btn-refresh';
+    btnRefresh.textContent = 'Refresh';
+    btnRefresh.disabled = true;
+    btnRefresh.addEventListener('click', function () {
+      _invalidateAll();
+      _loadSection(_activeTabId);
+    });
+
+    const pill = document.createElement('div');
+    pill.id = 'dk-pill';
+    pill.className = 'dk-pill';
+    pill.textContent = 'idle';
+
+    // Rebuild: title | spacer | dashboard filters | Refresh | Snapshot | pill
+    header.innerHTML = '';
+    header.appendChild(titleEl);
+    header.appendChild(spacer);
+    dashboardNodes.forEach(function (n) { header.appendChild(n); });
+    header.appendChild(btnRefresh);
+    header.appendChild(pill);
+  }
+
+  // ── DashboardKit.init ────────────────────────────────────────────────────────────
+  // A throw here leaves an empty document with no "Ask AI to fix" to click, so the
+  // report is posted immediately. No sectionId: the server refuses init with one.
+  function init(opts) {
+    try {
+      _init(opts);
+    } catch (e) {
+      console.error('[DashboardKit] init failed:', e);
+      console.log('[DashboardKit] init failed:', e);
+      window.parent.postMessage({
+        type: 'DASHBOARD_ERROR',
+        kind: 'script', phase: 'init',
+        error: { message: e.message || String(e), stack: e.stack || null },
+        title: (opts && opts.title) || '',
+      }, '*');
+      throw e;
+    }
+  }
+
+  function _init(opts) {
+    _title = opts.title || '';
+    if (opts.gitVersion) _gitVer = opts.gitVersion;
+    _initTooltip();
+
+    // Build internal section list, append System Info last
+    _sections = (opts.sections || []).map(function (s) {
+      return { id: s.id, label: s.label, tooltip: s.tooltip, load: s.load, loaded: false, errors: 0 };
+    });
+    _sections.push({ id: 'dk-sysinfo', label: 'System Info', load: null, loaded: false, errors: 0 });
+
+    // Build header controls
+    _buildHeader(_title);
+
+    // Build nav + panels for each section
+    const nav = document.querySelector('[data-dk-tabs]') || _createNav();
+    nav.id = 'dk-tabs';
+    nav.classList.add('dk-tabs');
+    const content = document.querySelector('.dk-content') || _createContent();
+
+    _sections.forEach(function (s) {
+      if (!document.getElementById('dk-panel-' + s.id)) {
+        const panel = document.createElement('section');
+        panel.id = 'dk-panel-' + s.id;
+        panel.className = 'dk-panel';
+        content.appendChild(panel);
+      }
+    });
+
+    // Wait message
+    const wait = document.createElement('div');
+    wait.id = 'dk-wait';
+    wait.className = 'dk-wait';
+    wait.textContent = 'Waiting for dashboard parameters…';
+    content.insertBefore(wait, content.firstChild);
+
+    // Enable refresh after first boot
+    const origOnMessage = _onMessage;
+    window.addEventListener('message', function (e) {
+      origOnMessage(e);
+      if (_hasBooted) {
+        const btn = document.getElementById('dk-btn-refresh');
+        if (btn) btn.disabled = false;
+      }
+    });
+  }
+
+  function _createNav() {
+    const nav = document.createElement('nav');
+    nav.id = 'dk-tabs';
+    nav.className = 'dk-tabs';
+    document.body.appendChild(nav);
+    return nav;
+  }
+
+  function _createContent() {
+    const div = document.createElement('div');
+    div.className = 'dk-content';
+    document.body.appendChild(div);
+    return div;
+  }
+
+  // ── Public API ────────────────────────────────────────────────────────────────
+  const DashboardKit = {
+    init,
+    get filters() {
+      return {
+        dateFromIso: _dateFromIso,
+        dateToIso: _dateToIso,
+        timezone: _timezone,
+        hierarchyId: _hierarchyId,
+      };
+    },
+    // Helpers are also passed into each load() function — that is the canonical
+    // way to use them. They are mirrored here so DashboardKit.<helper>(…) works too.
+    runQuery,
+    setSectionState,
+    renderTable,
+    renderKpiCard,
+    renderKpiStrip,
+    renderInfoGrid,
+    renderTotalsStrip,
+    formatCurrency,
+    formatInteger: fmtInt,
+    formatPercent,
+    formatDate: fmtDate,
+    formatDatetime: fmtDatetime,
+    colorClass,
+    escHtml: esc,
+  };
+
+  // Expose primitives directly (called inside load functions via destructuring).
+  // Deprecated: prefer the load() arguments or DashboardKit.<helper>; these bare
+  // globals remain for backwards compatibility and may be removed later.
+  global.DashboardKit = DashboardKit;
+  global.runQuery = runQuery;
+  global.setSectionState = setSectionState;
+  global.renderTable = renderTable;
+  global.renderKpiCard = renderKpiCard;
+  global.renderKpiStrip = renderKpiStrip;
+  global.renderInfoGrid = renderInfoGrid;
+  global.renderTotalsStrip = renderTotalsStrip;
+  global.formatCurrency = formatCurrency;
+  global.formatInteger = fmtInt;
+  global.formatPercent = formatPercent;
+  global.formatDate = fmtDate;
+  global.formatDatetime = fmtDatetime;
+  global.colorClass = colorClass;
+  global.escHtml = esc;
+
+}(window));