npm - @khanglvm/relay - Versions diffs - 0.5.4 → 0.7.0 - Mend

@khanglvm/relay 0.5.4 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/src/ui/kit.js CHANGED Viewed

@@ -32,13 +32,26 @@
  *     sortable: click column header to sort ascending/descending.
  *
  *   relayKit.commentable(el, label, detail?)
- *     Hover: 1px dashed accent outline + cursor pointer + title "add a comment".
- *     Click: parent.postMessage({relay:'annotate-request', label, detail}, '*').
+ *     Make one element commentable: hover shows a comment pin, a per-element
+ *     badge counts comments, click opens the board's annotation popover anchored
+ *     to the element. Thin shim over relayKit.annotate.register().
+ *
+ *   relayKit.annotate.auto()
+ *     Injected automatically by the server into every custom-HTML iframe. With no
+ *     explicit signals it makes a sensible set of content/interactive elements
+ *     hover-commentable so the user can annotate ANY meaningful part of the HTML.
+ *     If the author marks elements with data-relay-annotate[="Label"] (+ optional
+ *     data-relay-detail) or calls commentable(), auto-mode backs off to just those.
+ *     Opt out with data-relay-annotate="off" on <html> or <body>.
  */
 (function () {
   'use strict';
+  // Idempotent: the server may inject a /kit.js load on top of one the author
+  // already added. First load wins; a second execution no-ops.
+  if (window.relayKit) return;
   // ---------------------------------------------------------------------------
   // Theme
   // ---------------------------------------------------------------------------
@@ -357,39 +370,333 @@
   }
   // ---------------------------------------------------------------------------
-  // commentable()
+  // annotate — element-level commenting inside the sandboxed iframe
   // ---------------------------------------------------------------------------
+  // The board's annotation engine lives in the PARENT page and can't reach into
+  // this cross-origin iframe (sandbox without allow-same-origin), so everything
+  // here runs iframe-side and talks to the parent over postMessage:
+  //   iframe → parent  {relay:'annotate-ready'}                     request counts
+  //   iframe → parent  {relay:'annotate-request', ref, label, detail?, rect}
+  //   parent → iframe  {relay:'annotate-counts', counts:{ref:n}}    draw badges
+  //
+  // `ref` is a compact, reload-stable CSS path used as the element's identity so
+  // comments re-bind and badges count per element.
+  const annotate = (() => {
+    // Auto-mode picks anything the user would plausibly point at: every element
+    // with its OWN direct text (so div/span-based mockups work, not just
+    // semantic tags), plus meaningful leaves (icons, buttons, media) and a few
+    // semantic containers worth commenting whole. closest() resolves overlaps to
+    // the innermost target on hover.
+    const LEAF_TAGS = /^(IMG|BUTTON|A|INPUT|SELECT|TEXTAREA|svg|VIDEO|CANVAS|SUMMARY)$/;
+    const SKIP_TAGS = /^(SCRIPT|STYLE|HEAD|META|LINK|TITLE|BASE|NOSCRIPT|TEMPLATE)$/;
+    const CONTAINER_SELECTOR =
+      'li,td,th,figure,blockquote,article,.card,[role="button"],[role="listitem"],[role="option"]';
+    const MAX_AUTO = 400;
+    // Replaced elements that can't host a badge child — overlay the badge instead.
+    const NO_CHILD = /^(IMG|INPUT|HR|BR|EMBED|CANVAS|VIDEO|svg)$/;
+    const byRef = new Map(); // ref -> element
+    let mode = null;         // 'auto' | 'explicit' (decided on first scan)
+    let started = false;
+    let hot = null;          // currently outlined element
+    let pin = null;          // floating pin button
+    let hideTimer = 0;
+    let lastCounts = {};
+    let overlayBadges = [];  // [{el, badge}] for replaced elements
+    let repoTimer = 0;
+    const accent = () => theme.colors.accent;
+    // Compact, reload-stable CSS path — the element's identity.
+    function refOf(el) {
+      if (el.__relayRef) return el.__relayRef;
+      const parts = [];
+      let n = el;
+      while (n && n.nodeType === 1 && n !== document.body && parts.length < 10) {
+        let seg = n.tagName.toLowerCase();
+        const p = n.parentNode;
+        if (p && p.children) {
+          const sibs = Array.prototype.filter.call(p.children, (c) => c.tagName === n.tagName);
+          if (sibs.length > 1) seg += ':nth-of-type(' + (sibs.indexOf(n) + 1) + ')';
+        }
+        parts.unshift(seg);
+        n = p;
+      }
+      const ref = parts.join('>') || el.tagName.toLowerCase();
+      el.__relayRef = ref;
+      return ref;
+    }
-  function commentable(el, label, detail) {
-    try {
-      const lStr = String(label || '').slice(0, 200);
-      const dStr = detail != null ? String(detail).slice(0, 500) : undefined;
-      const accent = theme.colors.accent;
+    // Human label when the author didn't supply one.
+    function labelOf(el) {
+      const aria = el.getAttribute && el.getAttribute('aria-label');
+      if (aria) return aria.trim().slice(0, 80) || el.tagName.toLowerCase();
+      if (el.tagName === 'IMG') return (el.getAttribute('alt') || 'Image').trim().slice(0, 80) || 'Image';
+      const txt = (el.textContent || '').replace(/\s+/g, ' ').trim();
+      return txt ? txt.slice(0, 80) : el.tagName.toLowerCase();
+    }
-      el.style.cursor = 'pointer';
-      el.title = 'add a comment';
+    function injectStyle() {
+      if (document.getElementById('relay-ann-style')) return;
+      const s = document.createElement('style');
+      s.id = 'relay-ann-style';
+      s.textContent = [
+        '.relay-ann-hot{outline:2px solid ' + accent() + ' !important;outline-offset:1px !important;}',
+        '.relay-ann-badge{position:absolute;top:-7px;right:-7px;min-width:16px;height:16px;padding:0 4px;' +
+          'box-sizing:border-box;border-radius:9px;background:' + accent() + ';color:#fff;font:600 10px/16px ' + SANS + ';' +
+          'text-align:center;z-index:2147483646;cursor:pointer;box-shadow:0 1px 2px rgba(0,0,0,.25);}',
+      ].join('\n');
+      (document.head || document.documentElement).appendChild(s);
+    }
-      el.addEventListener('mouseenter', () => {
-        el.style.outline = `1px dashed ${accent}`;
-        el.style.outlineOffset = '2px';
-      });
-      el.addEventListener('mouseleave', () => {
-        el.style.outline = '';
-        el.style.outlineOffset = '';
-      });
-      el.addEventListener('click', (e) => {
+    function ensurePin() {
+      if (pin || !document.body) return pin;
+      pin = document.createElement('button');
+      pin.type = 'button';
+      pin.setAttribute('aria-label', 'Add a comment');
+      pin.title = 'Add a comment';
+      pin.style.cssText = [
+        'position:fixed', 'z-index:2147483647', 'display:none', 'width:22px', 'height:22px',
+        'padding:0', 'border:none', 'border-radius:50%', 'cursor:pointer', 'background:' + accent(),
+        'color:#fff', 'align-items:center', 'justify-content:center', 'line-height:0',
+        'box-shadow:0 1px 4px rgba(0,0,0,.3)',
+      ].join(';');
+      pin.innerHTML =
+        '<svg viewBox="0 0 16 16" width="11" height="11" aria-hidden="true">' +
+        '<path d="M3 2.5h10A1.5 1.5 0 0 1 14.5 4v5a1.5 1.5 0 0 1-1.5 1.5H8.4L5 13.4v-2.9H3A1.5 1.5 0 0 1 1.5 9V4A1.5 1.5 0 0 1 3 2.5Z" fill="currentColor"/></svg>';
+      pin.addEventListener('mouseenter', () => clearTimeout(hideTimer));
+      pin.addEventListener('mouseleave', scheduleHide);
+      pin.addEventListener('click', (e) => {
+        e.preventDefault();
         e.stopPropagation();
-        const msg = { relay: 'annotate-request', label: lStr };
-        if (dStr !== undefined) msg.detail = dStr;
-        try {
-          parent.postMessage(msg, '*');
-        } catch (postErr) {
-          console.warn('[relayKit] commentable postMessage error:', postErr);
+        if (hot) request(hot);
+        hidePin();
+      });
+      document.body.appendChild(pin);
+      return pin;
+    }
+    function showPinFor(el) {
+      if (!ensurePin()) return;
+      clearTimeout(hideTimer);
+      if (hot && hot !== el) hot.classList.remove('relay-ann-hot');
+      hot = el;
+      el.classList.add('relay-ann-hot');
+      const r = el.getBoundingClientRect();
+      const w = 22;
+      pin.style.display = 'flex';
+      pin.style.left = Math.max(2, Math.min(r.right - w / 2, window.innerWidth - w - 2)) + 'px';
+      pin.style.top = Math.max(2, Math.min(r.top - w / 2, window.innerHeight - w - 2)) + 'px';
+    }
+    function scheduleHide() {
+      clearTimeout(hideTimer);
+      hideTimer = setTimeout(hidePin, 220); // grace so the pin itself stays clickable
+    }
+    function hidePin() {
+      clearTimeout(hideTimer);
+      if (hot) hot.classList.remove('relay-ann-hot');
+      hot = null;
+      if (pin) pin.style.display = 'none';
+    }
+    // Ask the parent to open its annotation popover for this element.
+    function request(el) {
+      const r = el.getBoundingClientRect();
+      const msg = {
+        relay: 'annotate-request',
+        ref: refOf(el),
+        label: String(el.__relayLabel || labelOf(el)).slice(0, 200),
+        rect: { left: r.left, top: r.top, width: r.width, height: r.height },
+      };
+      if (el.__relayDetail != null) msg.detail = String(el.__relayDetail).slice(0, 500);
+      try { parent.postMessage(msg, '*'); } catch (_) {}
+    }
+    function positionOverlay(el, badge) {
+      const r = el.getBoundingClientRect();
+      badge.style.left = (r.right + window.scrollX - 9) + 'px';
+      badge.style.top = (r.top + window.scrollY - 7) + 'px';
+      badge.style.right = 'auto';
+    }
+    function repositionOverlays() {
+      for (const o of overlayBadges) if (o.el.isConnected) positionOverlay(o.el, o.badge);
+    }
+    function renderBadges(counts) {
+      lastCounts = counts || {};
+      for (const b of document.querySelectorAll('.relay-ann-badge')) b.remove();
+      overlayBadges = [];
+      for (const ref of Object.keys(lastCounts)) {
+        const n = lastCounts[ref];
+        if (!n) continue;
+        const el = byRef.get(ref);
+        if (!el || !el.isConnected) continue;
+        const badge = document.createElement('span');
+        badge.className = 'relay-ann-badge';
+        badge.textContent = String(n);
+        badge.title = n + (n === 1 ? ' comment' : ' comments');
+        badge.addEventListener('click', (e) => { e.preventDefault(); e.stopPropagation(); request(el); });
+        if (NO_CHILD.test(el.tagName)) {
+          badge.style.position = 'absolute';
+          document.body.appendChild(badge);
+          overlayBadges.push({ el, badge });
+          positionOverlay(el, badge);
+        } else {
+          if (getComputedStyle(el).position === 'static') el.style.position = 'relative';
+          el.appendChild(badge);
         }
+      }
+    }
+    function add(el, label, detail) {
+      if (!el || el.nodeType !== 1) return;
+      byRef.set(refOf(el), el);
+      el.classList.add('relay-annotatable');
+      if (label != null && label !== '') el.__relayLabel = String(label);
+      if (detail != null) el.__relayDetail = detail;
+    }
+    // True when the element holds non-whitespace text of its OWN (a direct text
+    // node), not just text inherited from descendants.
+    function hasDirectText(el) {
+      for (const n of el.childNodes) {
+        if (n.nodeType === 3 && n.nodeValue && n.nodeValue.trim()) return true;
+      }
+      return false;
+    }
+    function autoPick() {
+      let all;
+      try { all = document.body.querySelectorAll('*'); } catch (_) { return []; }
+      let containers;
+      try { containers = new Set(document.querySelectorAll(CONTAINER_SELECTOR)); } catch (_) { containers = new Set(); }
+      const out = [];
+      for (const el of all) {
+        if (out.length >= MAX_AUTO) break;
+        if (SKIP_TAGS.test(el.tagName)) continue;
+        if (pin && pin.contains(el)) continue;             // our own pin
+        if (el.classList && el.classList.contains('relay-ann-badge')) continue;
+        if (LEAF_TAGS.test(el.tagName) || containers.has(el) || hasDirectText(el)) out.push(el);
+      }
+      return out;
+    }
+    function scan() {
+      const signalled = Array.prototype.filter.call(
+        document.querySelectorAll('[data-relay-annotate]'),
+        (el) => el.getAttribute('data-relay-annotate') !== 'off'
+      );
+      // ANY explicit signal (attribute or a prior commentable() call) → the
+      // author scopes what's annotatable; auto-mode stays off.
+      if (mode === null) mode = signalled.length > 0 || byRef.size > 0 ? 'explicit' : 'auto';
+      if (mode === 'explicit') {
+        for (const el of signalled) add(el, el.getAttribute('data-relay-annotate') || null, el.getAttribute('data-relay-detail'));
+        return;
+      }
+      for (const el of autoPick()) add(el, null, undefined);
+    }
+    function optedOut() {
+      const v = (document.body && document.body.getAttribute('data-relay-annotate')) ||
+        document.documentElement.getAttribute('data-relay-annotate');
+      return v === 'off';
+    }
+    function announce() {
+      try { parent.postMessage({ relay: 'annotate-ready' }, '*'); } catch (_) {}
+    }
+    function start() {
+      if (started) return;
+      if (!document.body) { document.addEventListener('DOMContentLoaded', start, { once: true }); return; }
+      started = true;
+      injectStyle();
+      ensurePin();
+      // Delegated hover — closest() resolves nested targets to the innermost.
+      document.addEventListener('mouseover', (e) => {
+        const t = e.target && e.target.closest && e.target.closest('.relay-annotatable');
+        if (t) showPinFor(t);
+      }, true);
+      document.addEventListener('mouseout', (e) => {
+        const t = e.target && e.target.closest && e.target.closest('.relay-annotatable');
+        if (t) scheduleHide();
+      }, true);
+      window.addEventListener('scroll', () => {
+        hidePin();
+        if (overlayBadges.length) { cancelAnimationFrame(repoTimer); repoTimer = requestAnimationFrame(repositionOverlays); }
+      }, true);
+      window.addEventListener('resize', () => { hidePin(); repositionOverlays(); });
+      window.addEventListener('message', (e) => {
+        const m = e.data;
+        if (m && typeof m === 'object' && m.relay === 'annotate-counts') renderBadges(m.counts || {});
       });
-    } catch (err) {
-      console.warn('[relayKit] commentable error:', err);
+      // Re-pick up DOM that author JS builds after load. We observe childList
+      // only (not attributes, so our own hover-class toggles don't fire it) and
+      // ignore mutations that only touch our own pin/badge nodes — otherwise
+      // rendering a badge would re-trigger the observer in a tight loop.
+      try {
+        const ours = (n) =>
+          n.nodeType === 1 &&
+          (n === pin || (pin && pin.contains(n)) || n.id === 'relay-ann-style' ||
+            (n.classList && n.classList.contains('relay-ann-badge')));
+        const mo = new MutationObserver((muts) => {
+          let relevant = false;
+          for (const m of muts) {
+            for (const n of m.addedNodes) if (!ours(n)) { relevant = true; break; }
+            if (relevant) break;
+            for (const n of m.removedNodes) if (!ours(n)) { relevant = true; break; }
+            if (relevant) break;
+          }
+          if (!relevant) return;
+          clearTimeout(mo._t);
+          mo._t = setTimeout(() => { scan(); renderBadges(lastCounts); announce(); }, 250);
+        });
+        mo.observe(document.body, { childList: true, subtree: true });
+      } catch (_) {}
+      announce();
+    }
+    // Server-injected entrypoint. Idempotent.
+    function auto() {
+      try {
+        if (optedOut()) return;
+        if (!document.body) { document.addEventListener('DOMContentLoaded', auto, { once: true }); return; }
+        scan();
+        start();
+      } catch (err) {
+        console.warn('[relayKit] annotate.auto error:', err);
+      }
+    }
+    // Explicit per-element registration (also used by commentable()).
+    function register(el, label, detail) {
+      try {
+        add(el, label, detail);
+        if (started) renderBadges(lastCounts);
+        else start();
+      } catch (err) {
+        console.warn('[relayKit] annotate.register error:', err);
+      }
     }
+    return { auto, register };
+  })();
+  // ---------------------------------------------------------------------------
+  // commentable() — back-compat shim over annotate.register()
+  // ---------------------------------------------------------------------------
+  function commentable(el, label, detail) {
+    if (!el) return;
+    annotate.register(
+      el,
+      label != null ? String(label).slice(0, 200) : null,
+      detail != null ? String(detail).slice(0, 500) : undefined
+    );
   }
   // ---------------------------------------------------------------------------
@@ -403,6 +710,7 @@
     mermaid,
     table,
     commentable,
+    annotate,
   };
   window.relayKit = relayKit;

package/src/ui/style.css CHANGED Viewed

@@ -73,7 +73,7 @@ body {
   color: var(--fg);
   font: 16px/1.6 var(--sans);
   -webkit-font-smoothing: antialiased;
-  transition: background 200ms var(--ease), color 200ms var(--ease);
+  transition: background 200ms var(--ease), color 200ms var(--ease), padding 240ms var(--ease);
 }
 .wrap { max-width: 860px; margin: 0 auto; padding: 32px 20px 28px; }
@@ -193,7 +193,7 @@ input[type="text"]:focus, textarea:focus {
 textarea { min-height: 90px; resize: vertical; }
 .qnotewrap { margin-top: 10px; }
-.qnotewrap .qnote { font-size: 0.88rem; padding: 8px 12px; }
+.qnotewrap .qnote { font-size: 0.88rem; padding: 8px 12px; min-height: 52px; resize: vertical; }
 .errmsg { color: var(--danger); font-size: 0.85rem; margin: 8px 0 0; display: none; }
 .card.error .errmsg { display: block; }
@@ -220,8 +220,14 @@ textarea { min-height: 90px; resize: vertical; }
   position: sticky; top: 0;
   background: var(--danger); color: var(--danger-fg);
   text-align: center; padding: 9px 16px; font-size: 0.9rem;
+  line-height: 1.45;
   z-index: 10; display: none;
+  border-bottom: 1px solid transparent;
 }
+/* Calm status notes (timeout hand-back / lost connection). Never the red error
+   state — the board stays usable, so these only inform. */
+.banner.info { background: var(--accent-soft); color: var(--accent); }
+.banner.warn { background: var(--bg-sunken); color: var(--fg-2); border-bottom-color: var(--border-strong); }
 /* Live-update toast: flagged after a `rly update` reload (see app.js).
    Fixed top-center, accent-soft bg, accent text; JS auto-removes it. */