@charlescms/astro 0.1.0

package/src/edit-affordance.js

@@ -0,0 +1,463 @@
+// Provides one consistent hover/tap ring and click behavior for every editable
+// element. It does not know how editing works; elements expose a `charlescmsEdit`
+// action and this module chooses the right action under the pointer — preferring
+// the most specific element, staying stable as the pointer moves, and, when several
+// editables overlap (a logo's monogram + wordmark, text over a background image),
+// popping a picker so the user chooses exactly instead of fighting a hover target.
+export function createEditAffordance({ state, isVisible }) {
+  // px of slack kept around a target so a steady hand never flickers between two
+  // elements that sit close together — and so a slightly-off click still gathers
+  // the tightly-packed neighbours into the picker.
+  const HIT_PAD = 10;
+  // ms the ring lingers after the pointer leaves — long enough to travel from the
+  // element up to its label without the ring vanishing on the way.
+  const HIDE_DELAY = 260;
+
+  const area = (el) => {
+    const r = el.getBoundingClientRect();
+    return Math.max(1, r.width) * Math.max(1, r.height);
+  };
+
+  // The single element the user is pointing at is the SMALLEST editable under the
+  // point — a small price label on a big card resolves to the price, not the card.
+  function resolveEditableAt(x, y) {
+    let best = null;
+    let bestArea = Infinity;
+    for (const node of document.elementsFromPoint(x, y)) {
+      if (node.closest?.("[data-charlescms-ui]")) continue;
+      const element = node.closest?.('[data-charlescms-editable="true"]');
+      if (!element || !element.charlescmsEdit || !isVisible(element)) continue;
+      const a = area(element);
+      if (a < bestArea) { best = element; bestArea = a; }
+    }
+    return best;
+  }
+
+  // Every editable at OR within a few px of the point — the candidates for the
+  // picker. Stacked elements (under the point) and tightly-packed neighbours
+  // (beside it) both qualify, so a logo's three crammed pieces all show up even on
+  // an imprecise click. Returned top-to-bottom, left-to-right (reading order).
+  function gatherCandidatesAt(x, y) {
+    const found = new Set();
+    for (const node of document.elementsFromPoint(x, y)) {
+      if (node.closest?.("[data-charlescms-ui]")) continue;
+      const element = node.closest?.('[data-charlescms-editable="true"]');
+      if (element?.charlescmsEdit && isVisible(element)) found.add(element);
+    }
+    for (const element of document.querySelectorAll('[data-charlescms-editable="true"]')) {
+      if (found.has(element) || !element.charlescmsEdit || element.closest("[data-charlescms-ui]") || !isVisible(element)) continue;
+      const r = element.getBoundingClientRect();
+      if (x >= r.left - HIT_PAD && x <= r.right + HIT_PAD && y >= r.top - HIT_PAD && y <= r.bottom + HIT_PAD) found.add(element);
+    }
+    const sortReading = (list) => list.sort((a, b) => {
+      const ra = a.getBoundingClientRect();
+      const rb = b.getBoundingClientRect();
+      return Math.abs(ra.top - rb.top) > 6 ? ra.top - rb.top : ra.left - rb.left;
+    }).slice(0, 7);
+    const list = [...found];
+    if (list.length > 1) {
+      // Keep only genuinely COMPARABLE targets. A far-larger container (a full-bleed
+      // hero behind small text or a fixed header) shouldn't turn every click into a
+      // picker — the picker is for things that actually compete for the same spot.
+      // You still edit a background by clicking its own bare area, where it's the
+      // sole candidate.
+      const minArea = Math.min(...list.map(area));
+      const comparable = list.filter((el) => area(el) <= minArea * 12);
+      if (comparable.length) return sortReading(comparable);
+    }
+    return sortReading(list);
+  }
+
+  function withinPadded(element, x, y, pad = HIT_PAD) {
+    const r = element.getBoundingClientRect();
+    return x >= r.left - pad && x <= r.right + pad && y >= r.top - pad && y <= r.bottom + pad;
+  }
+
+  function installEditAffordance() {
+    if (state.affordanceInstalled) return;
+    state.affordanceInstalled = true;
+
+    // A quiet hover ring only — no floating "Edit" label. The hand cursor already
+    // signals "clickable", and a click edits directly (or opens the picker when
+    // several editables overlap), so a separate edit button is just noise.
+    const spot = document.createElement("div");
+    spot.dataset.charlescmsUi = "true";
+    spot.className = "charlescms-spot";
+    spot.style.display = "none";
+    document.body.append(spot);
+
+    let current = null;
+    let hideTimer;
+    const hideNow = () => {
+      clearTimeout(hideTimer);
+      spot.style.display = "none";
+      current = null;
+    };
+    const hideSoon = () => {
+      clearTimeout(hideTimer);
+      hideTimer = setTimeout(hideNow, HIDE_DELAY);
+    };
+    state.hideEditSpot = hideNow;
+
+    const place = (element) => {
+      const rect = element.getBoundingClientRect();
+      spot.style.display = "block";
+      spot.style.left = `${Math.round(rect.left)}px`;
+      spot.style.top = `${Math.round(rect.top)}px`;
+      spot.style.width = `${Math.round(rect.width)}px`;
+      spot.style.height = `${Math.round(rect.height)}px`;
+    };
+
+    const show = (element) => { current = element; place(element); };
+
+    // ---- Disambiguation picker (shown when several editables overlap) ----
+    let picker = null;
+    let backdrop = null;
+    const removePicker = () => {
+      picker?.remove();
+      backdrop?.remove();
+      picker = null;
+      backdrop = null;
+      document.removeEventListener("keydown", onKey, true);
+    };
+    const onKey = (event) => { if (event.key === "Escape") { removePicker(); hideNow(); } };
+
+    const showPicker = (candidates, x, y, link) => {
+      removePicker();
+      // A transparent full-screen backdrop sits behind the picker and ABSORBS the
+      // next outside click — so dismissing the picker is a single action that never
+      // also edits or selects whatever was underneath.
+      backdrop = document.createElement("div");
+      backdrop.dataset.charlescmsUi = "true";
+      backdrop.className = "charlescms-picker-backdrop";
+      backdrop.addEventListener("click", (event) => { event.preventDefault(); event.stopPropagation(); removePicker(); hideNow(); });
+      document.body.append(backdrop);
+      picker = document.createElement("div");
+      picker.dataset.charlescmsUi = "true";
+      picker.className = "charlescms-picker";
+      picker.innerHTML = `<div class="charlescms-picker-head">Pick what to edit</div>`;
+      const addRow = (label, preview, onPick, onHover) => {
+        const row = document.createElement("button");
+        row.type = "button";
+        row.dataset.charlescmsUi = "true";
+        row.className = "charlescms-picker-item";
+        row.innerHTML = `<span class="charlescms-picker-label">${escapeHtml(label)}</span><span class="charlescms-picker-prev">${escapeHtml(preview)}</span>`;
+        row.addEventListener("pointerenter", () => onHover?.());
+        row.addEventListener("click", (event) => { event.preventDefault(); event.stopPropagation(); onPick(); });
+        picker.append(row);
+      };
+      for (const element of candidates) {
+        addRow(affordanceLabel(element), pickerPreview(element),
+          () => { removePicker(); hideNow(); element.charlescmsEdit.open(); },
+          () => place(element));
+      }
+      if (link) {
+        addRow("↗  Open link", link.getAttribute("href"),
+          // Open in a NEW tab so the current edit session and any unpublished
+          // changes are never lost by navigating the page away.
+          () => { removePicker(); hideNow(); window.open(link.href, "_blank"); },
+          () => hideNow());
+      }
+      document.body.append(picker);
+      positionPicker(picker, x, y);
+      document.addEventListener("keydown", onKey, true);
+    };
+    state.removeEditPicker = removePicker;
+
+    const onMove = (event) => {
+      if (event.pointerType === "touch") return;
+      if (event.target?.closest?.("[data-charlescms-ui]")) { clearTimeout(hideTimer); return; }
+      if (picker || document.querySelector(".charlescms-panel, .charlescms-rt-toolbar")) { hideNow(); clearIslandHighlight(); return; }
+      const next = resolveEditableAt(event.clientX, event.clientY);
+      if (!next || next.isContentEditable || next.classList.contains("charlescms-editing")) {
+        if (current) hideSoon();
+        // Editable wins; otherwise reveal the boundary of a hydrated island under
+        // the pointer so locked, in-code regions read as "interactive", not broken.
+        if (!next) highlightIslandAt(event.clientX, event.clientY);
+        return;
+      }
+      clearIslandHighlight();
+      clearTimeout(hideTimer);
+      if (current && current.isConnected && isVisible(current) && next !== current
+        && next.contains(current) && withinPadded(current, event.clientX, event.clientY)) {
+        place(current);
+        return;
+      }
+      show(next);
+    };
+
+    const onScroll = () => {
+      if (picker) { removePicker(); hideNow(); return; }
+      if (current && isVisible(current)) place(current);
+      else if (current) hideSoon();
+      repositionIslandHighlight();
+    };
+
+    const onClick = (event) => {
+      if (!document.documentElement.classList.contains("charlescms-active")) return;
+      if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+      if (event.target.closest("[data-charlescms-ui]")) return;
+
+      const candidates = gatherCandidatesAt(event.clientX, event.clientY);
+      if (!candidates.length) {
+        const direct = event.target.closest('[data-charlescms-editable="true"]');
+        if (direct?.charlescmsEdit) candidates.push(direct);
+        else { showBoundaryHint(event.target, event.clientX, event.clientY); return; }
+      }
+      const link = event.target.closest("a[href]");
+      const navLink = link && !/^(?:tel:|mailto:|sms:)/i.test(link.getAttribute("href") || "") ? link : null;
+
+      // Several editables overlap here → let the user choose, never guess. Works
+      // the same for mouse and touch; the picker rows are big, finger-sized targets
+      // and suppress link navigation so a wrapped logo stays fully editable.
+      if (candidates.length > 1) {
+        event.preventDefault();
+        event.stopPropagation();
+        hideNow();
+        showPicker(candidates, event.clientX, event.clientY, navLink);
+        return;
+      }
+
+      const element = candidates[0];
+      if (element.isContentEditable || element.classList.contains("charlescms-editing")) return;
+
+      // A single editable wrapped in a navigation link (the logo, a menu item)
+      // must never silently navigate on click — that's the "logo can't be edited"
+      // trap. Offer an explicit Edit vs Open choice instead, for mouse and touch.
+      if (navLink && navLink.contains(element)) {
+        event.preventDefault();
+        event.stopPropagation();
+        hideNow();
+        showPicker([element], event.clientX, event.clientY, navLink);
+        return;
+      }
+
+      // A single editable: a tap or click edits it directly. (Several overlapping
+      // editables took the picker branch above; the picker's big rows cover the
+      // fat-finger case, so no separate touch confirm step is needed.)
+      event.preventDefault();
+      event.stopPropagation();
+      hideNow();
+      element.charlescmsEdit.open();
+    };
+
+    document.addEventListener("pointermove", onMove, { passive: true });
+    document.addEventListener("scroll", onScroll, { passive: true, capture: true });
+    document.addEventListener("click", onClick, true);
+
+    state.affordanceCleanup = () => {
+      document.removeEventListener("pointermove", onMove);
+      document.removeEventListener("scroll", onScroll, { capture: true });
+      document.removeEventListener("click", onClick, true);
+      removePicker();
+      clearIslandHighlight();
+      clearBoundaryHint();
+      clearTimeout(hideTimer);
+      state.hideEditSpot = null;
+      state.removeEditPicker = null;
+      spot.remove();
+    };
+  }
+
+  return { installEditAffordance };
+}
+
+// A short, human preview of an editable for a picker row, so the choice is obvious
+// without reading the page ("Edit text · Zum Charles", "Replace image · hero.jpg").
+function pickerPreview(element) {
+  if (element.tagName === "IMG" || element.querySelector?.("img")) {
+    const img = element.tagName === "IMG" ? element : element.querySelector("img");
+    return img.getAttribute("alt") || (img.getAttribute("src") || "").split(/[?#]/)[0].split("/").pop() || "image";
+  }
+  // A link row describes WHERE it points, so "Edit link" never reads as a duplicate
+  // of the "Edit text" row for the very same words ("Edit link · /about" vs "Edit
+  // text · About us").
+  if (element.tagName === "A") {
+    const href = (element.getAttribute("href") || "").trim();
+    if (href) return href;
+  }
+  const text = (element.textContent || "").replace(/\s+/g, " ").trim();
+  return text.length > 44 ? `${text.slice(0, 44)}…` : (text || element.tagName.toLowerCase());
+}
+
+// Place the picker next to the click, clamped to stay fully on-screen.
+function positionPicker(menu, x, y) {
+  const r = menu.getBoundingClientRect();
+  let left = x + 10;
+  let top = y + 10;
+  if (left + r.width > window.innerWidth - 8) left = Math.max(8, x - r.width - 10);
+  if (top + r.height > window.innerHeight - 8) top = Math.max(8, y - r.height - 10);
+  menu.style.left = `${Math.max(8, left)}px`;
+  menu.style.top = `${Math.max(8, top)}px`;
+}
+
+// Explains the editing boundary when a click lands on content the page generates
+// (so there is no source to edit). Fires only on text/media-like elements the user
+// could reasonably expect to edit — never on chrome, links, or already-editable
+// content — so it informs without nagging.
+let boundaryHintTimer;
+function showBoundaryHint(clickTarget, pointerX, pointerY) {
+  const element = boundaryHintTarget(clickTarget);
+  if (!element) return;
+  clearBoundaryHint();
+  const isMedia = element.tagName === "IMG" || element.tagName === "PICTURE" || element.tagName === "SVG"
+    || Boolean(element.querySelector?.("img,video,iframe,svg"));
+  // An Astro framework island (a hydrated React/Vue/Svelte/… component) renders to
+  // a <astro-island> custom element. Its text lives in code, not in any editable
+  // source the CMS owns — so say so plainly, and outline the WHOLE island so the
+  // user sees exactly which block is off-limits, instead of guessing per word.
+  const island = element.closest("astro-island");
+  const content = boundaryHintContent({ isMedia, isInteractive: Boolean(island) });
+
+  // The outline + badge are owned by the hover layer (so they persist while the
+  // pointer is over the island); a click just adds the plain-language "why".
+  if (island) highlightIsland(island);
+
+  const rect = element.getBoundingClientRect();
+  const hint = document.createElement("div");
+  hint.dataset.charlescmsUi = "true";
+  hint.className = `charlescms-boundary-hint charlescms-boundary-hint--${content.variant}`;
+  // For an island the badge already carries the ⚡ title, so the callout is just
+  // the plain-language "why"; media/data keep their icon + line.
+  hint.innerHTML = island
+    ? `<span>${escapeHtml(content.text)}</span>`
+    : `<span class="charlescms-boundary-hint-icon" aria-hidden="true">${content.icon}</span>`
+      + `<span class="charlescms-boundary-hint-body">`
+      + (content.title ? `<span class="charlescms-boundary-hint-title">${escapeHtml(content.title)}</span>` : "")
+      + `<span>${escapeHtml(content.text)}</span></span>`;
+  // Anchor the callout to the click point (offset so it never sits under the
+  // cursor or hides the very content it describes), clamped on-screen.
+  const anchorX = Number.isFinite(pointerX) ? pointerX : rect.left;
+  const anchorY = Number.isFinite(pointerY) ? pointerY : rect.bottom;
+  document.body.append(hint);
+  const hr = hint.getBoundingClientRect();
+  let left = anchorX + 14;
+  let top = anchorY + 14;
+  if (left + hr.width > window.innerWidth - 10) left = Math.max(10, anchorX - hr.width - 14);
+  if (top + hr.height > window.innerHeight - 10) top = Math.max(10, anchorY - hr.height - 14);
+  hint.style.left = `${Math.round(left)}px`;
+  hint.style.top = `${Math.round(top)}px`;
+  requestAnimationFrame(() => hint.classList.add("charlescms-boundary-hint-in"));
+  clearTimeout(boundaryHintTimer);
+  boundaryHintTimer = setTimeout(clearBoundaryHint, 3200);
+}
+
+function clearBoundaryHint() {
+  clearTimeout(boundaryHintTimer);
+  for (const node of document.querySelectorAll(".charlescms-boundary-hint")) node.remove();
+}
+
+// ---- Hydrated-island highlight (hover + click) ------------------------------
+// One amber outline + "Interactive component" badge marks the boundary of a
+// hydrated <astro-island>. It is purely visual (never writes), so it stays safe
+// on every page; it simply makes the edit boundary legible the way a design tool
+// marks a locked symbol. Module-level state: one editor instance per page.
+let islandHighlight = { island: null, veil: null, badge: null };
+
+function highlightIslandAt(x, y) {
+  const top = document.elementFromPoint(x, y);
+  if (!top || top.closest("[data-charlescms-ui]") || top.closest('[data-charlescms-editable="true"]')) {
+    clearIslandHighlight();
+    return;
+  }
+  const island = top.closest("astro-island");
+  if (island) highlightIsland(island);
+  else clearIslandHighlight();
+}
+
+function highlightIsland(island) {
+  if (islandHighlight.island === island && islandHighlight.veil?.isConnected) {
+    repositionIslandHighlight();
+    return;
+  }
+  clearIslandHighlight();
+  const veil = document.createElement("div");
+  veil.dataset.charlescmsUi = "true";
+  veil.className = "charlescms-island-veil";
+  const badge = document.createElement("div");
+  badge.dataset.charlescmsUi = "true";
+  badge.className = "charlescms-island-badge";
+  badge.textContent = "⚡ Interactive component";
+  document.body.append(veil, badge);
+  islandHighlight = { island, veil, badge };
+  repositionIslandHighlight();
+  requestAnimationFrame(() => {
+    veil.classList.add("charlescms-island-veil-in");
+    badge.classList.add("charlescms-island-veil-in");
+  });
+}
+
+function repositionIslandHighlight() {
+  const { island, veil, badge } = islandHighlight;
+  if (!island?.isConnected || !veil) return;
+  const r = island.getBoundingClientRect();
+  veil.style.left = `${Math.round(r.left)}px`;
+  veil.style.top = `${Math.round(r.top)}px`;
+  veil.style.width = `${Math.round(r.width)}px`;
+  veil.style.height = `${Math.round(r.height)}px`;
+  badge.style.left = `${Math.max(8, Math.round(r.left))}px`;
+  badge.style.top = `${Math.max(8, Math.round(r.top - 10))}px`;
+}
+
+function clearIslandHighlight() {
+  islandHighlight.veil?.remove();
+  islandHighlight.badge?.remove();
+  islandHighlight = { island: null, veil: null, badge: null };
+}
+
+// The boundary message, kept pure so the copy and classification are unit-tested
+// (the DOM detection above stays thin glue). Interactive islands get the most
+// specific, actionable line; media and generated values fall back in that order.
+export function boundaryHintContent({ isMedia, isInteractive }) {
+  if (isInteractive) {
+    return {
+      variant: "interactive",
+      icon: "⚡",
+      title: "Interactive component",
+      text: "This area is built in code, so a developer edits it — it can’t be changed here."
+    };
+  }
+  if (isMedia) {
+    return {
+      variant: "media",
+      icon: "🔒",
+      title: "Managed in code",
+      text: "This image comes from the page’s code or data, so it can’t be replaced here."
+    };
+  }
+  return {
+    variant: "data",
+    icon: "🔒",
+    title: "Auto-filled value",
+    text: "This is generated automatically (like a date or a data field), so it can’t be edited here."
+  };
+}
+
+function boundaryHintTarget(node) {
+  if (!node?.closest || node.closest("[data-charlescms-ui]")) return null;
+  if (node.closest("a[href]")) return null; // links navigate, so don't second-guess them
+  // Cover the content elements a person could plausibly try to edit — including
+  // generated values (a <time> date, a <span> from data) — so clicking ANY of
+  // them explains itself instead of being a silent dead-end on any site.
+  const element = node.closest(
+    "p,h1,h2,h3,h4,h5,h6,li,blockquote,figcaption,td,th,dd,dt,time,span,em,strong,small,b,i,mark,cite,abbr,label,address,button,img,picture,svg,figure"
+  );
+  if (!element || element.closest('[data-charlescms-editable="true"]')) return null;
+  const isMedia = element.tagName === "IMG" || element.tagName === "PICTURE" || element.tagName === "SVG"
+    || Boolean(element.querySelector?.("img,video,iframe,svg"));
+  if (!isMedia && (element.textContent || "").trim().length < 2) return null;
+  return element;
+}
+
+function affordanceLabel(element) {
+  // A staged (not yet published) section edits as one block in the builder.
+  if (element.dataset?.charlescmsPreviewBlock) return "✎  Edit new section";
+  if (element.tagName === "IMG" || element.querySelector?.("img")) return "⤢  Replace image";
+  if (element.tagName === "A") return "✎  Edit link";
+  if (element.matches?.("ul,ol") || element.querySelector?.("li")) return "✎  Edit list";
+  return "✎  Edit text";
+}
+
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#039;" })[char]);
+}