@caretcms/core 0.3.0 → 0.4.0

package/static/cms/editor/draft-client.js

@@ -0,0 +1,87 @@
+/**
+ * @typedef {object} DraftState
+ * @property {number} count
+ * @property {boolean} canPublish
+ * @property {boolean} retryRebuild
+ */
+/**
+ * @typedef {object} RetryDeploymentResult
+ * @property {boolean} deploymentTracked
+ */
+
+export class CmsDraftRequestError extends Error {}
+
+/** @param {Response} response */
+async function requireOk(response) {
+  if (!response.ok) {
+    throw new CmsDraftRequestError(`CMS request failed (${response.status})`);
+  }
+  return response;
+}
+
+/** @param {unknown} value */
+function record(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? /** @type {Record<string, unknown>} */ (value)
+    : {};
+}
+
+/**
+ * HTTP client for editor-specific draft and deploy-retry operations.
+ *
+ * @param {{
+ *   buildUrl: (path: string) => string,
+ *   fetchImpl?: typeof fetch,
+ * }} options
+ */
+export function createDraftClient(options) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const headers = { 'Content-Type': 'application/json', 'x-caret-request': '1' };
+
+  /** @param {'GET' | 'POST' | 'DELETE'} method @param {string} path @param {string | undefined} body */
+  function request(method, path, body) {
+    return fetchImpl(options.buildUrl(path), {
+      method,
+      headers,
+      credentials: 'same-origin',
+      ...(body === undefined ? {} : { body }),
+    });
+  }
+
+  async function getState() {
+    const response = await requireOk(await request('GET', '/draft', undefined));
+    const data = record(await response.json());
+    return /** @type {DraftState} */ ({
+      count: typeof data.count === 'number' && Number.isFinite(data.count)
+        ? Math.max(0, Math.trunc(data.count))
+        : 0,
+      canPublish: data.canPublish !== false,
+      retryRebuild: data.retryRebuild === true,
+    });
+  }
+
+  async function publish() {
+    const response = await requireOk(await request('POST', '/publish', '{}'));
+    return /** @type {unknown} */ (await response.json());
+  }
+
+  async function discard() {
+    await requireOk(await request('DELETE', '/draft', undefined));
+  }
+
+  async function retryDeployment() {
+    const response = await requireOk(await request(
+      'POST',
+      '/publish',
+      JSON.stringify({ retryRebuild: true }),
+    ));
+    const data = record(await response.json());
+    const rebuild = record(data.rebuild);
+    if (rebuild.ok !== true) throw new CmsDraftRequestError('Deployment retry failed');
+    return /** @type {RetryDeploymentResult} */ ({
+      deploymentTracked: data.deploymentTracked === true,
+    });
+  }
+
+  return { getState, publish, discard, retryDeployment };
+}

package/static/cms/editor/guards.js

@@ -1,3 +1,4 @@
+/** @param {{ dirtyEls: Set<Element> }} state */
 export function mountEditorGuards(state) {
   document.body.classList.add('cms-edit-mode');
 
@@ -15,6 +16,25 @@ export function mountEditorGuards(state) {
       const target = e.target;
       if (!(target instanceof Element)) return;
 
+      // Preserve the browser's native open-in-new-tab gesture for editable
+      // links. A normal click still enters editing below.
+      if (e.metaKey || e.ctrlKey) {
+        const modifierLink = target.closest('a');
+        if (modifierLink?.matches('[data-caret]') || modifierLink?.querySelector('[data-caret]')) {
+          e.preventDefault();
+          e.stopPropagation();
+          try {
+            const destination = new URL(modifierLink.href, window.location.href);
+            if (['http:', 'https:', 'mailto:', 'tel:'].includes(destination.protocol)) {
+              window.open(destination.href, '_blank', 'noopener,noreferrer');
+            }
+          } catch {
+            // Malformed destinations never execute from edit mode.
+          }
+          return;
+        }
+      }
+
       // Allow clicks inside the CMS toolbar
       if (target.closest('.cms-toolbar')) return;
 

package/static/cms/editor/helpers.js

@@ -1,3 +1,21 @@
+/**
+ * @typedef {object} ParsedCaretBinding
+ * @property {string | null} collection
+ * @property {string | null} id
+ * @property {string} field
+ */
+
+/**
+ * @typedef {object} ResolvedCaretBinding
+ * @property {string} collection
+ * @property {string} id
+ * @property {string} field
+ */
+
+/**
+ * @param {string} attr
+ * @returns {ParsedCaretBinding | null}
+ */
 export function parseCaretAttr(attr) {
   const parts = attr.split('::');
   if (parts.length === 3) return { collection: parts[0], id: parts[1], field: parts[2] };
@@ -11,6 +29,9 @@ export function parseCaretAttr(attr) {
  * If the binding already has collection+id, returns as-is.
  * If field-only, walks up to nearest [data-caret-scope] ancestor.
  * Returns null if scope cannot be resolved.
+ * @param {Element} el
+ * @param {ParsedCaretBinding | null} parsed
+ * @returns {ResolvedCaretBinding | null}
  */
 export function resolveBinding(el, parsed) {
   if (!parsed) return null;
@@ -18,7 +39,9 @@ export function resolveBinding(el, parsed) {
   // segment ("::x::y") must stay a (rejected) triple like the server treats
   // it, not silently fall back to scope resolution and save elsewhere.
   // Held to the rewrite engine by tests/unit/caret-parser-parity.test.ts.
-  if (parsed.collection !== null && parsed.id !== null) return parsed;
+  if (parsed.collection !== null && parsed.id !== null) {
+    return { collection: parsed.collection, id: parsed.id, field: parsed.field };
+  }
 
   // Walk up to find nearest data-caret-scope
   let node = el.parentElement;
@@ -38,6 +61,8 @@ export function resolveBinding(el, parsed) {
 /**
  * Get the full data-caret key for an element, resolving scope if needed.
  * Returns "collection::id::field" or null if unresolvable.
+ * @param {Element} el
+ * @returns {string | null}
  */
 export function getResolvedKey(el) {
   const attr = el.getAttribute('data-caret');
@@ -48,6 +73,10 @@ export function getResolvedKey(el) {
   return `${resolved.collection}::${resolved.id}::${resolved.field}`;
 }
 
+/**
+ * @param {Element} el
+ * @param {boolean} success
+ */
 export function flash(el, success) {
   const cls = success ? 'cms-saved' : 'cms-error';
   el.classList.add(cls);

package/static/cms/editor/highlight.js

@@ -14,6 +14,7 @@
 
 let highlightActive = false;
 
+/** @param {Element} highlightBtn @param {(message: string, type: 'success' | 'error') => void} showToast */
 export function toggleHighlight(highlightBtn, showToast) {
   highlightActive = !highlightActive;
   document.body.classList.toggle('cms-highlight-all', highlightActive);

package/static/cms/editor/image-edit.js

@@ -2,6 +2,40 @@ import { buildCmsUrl } from './config.js';
 import { uploadHeaders } from './security.js';
 import { resolveBinding } from './helpers.js';
 
+/** @typedef {{ collection: string, id: string, field: string }} ResolvedCaretBinding */
+/** @typedef {{ collection: string | null, id: string | null, field: string }} ParsedCaretBinding */
+/** @typedef {{ ok: true, revision?: number } | { ok: false, reason: 'conflict' | 'unauthorized' | 'error', latestValue?: unknown }} SaveResult */
+/**
+ * @typedef {((message: string, kind: 'success' | 'error') => unknown) & {
+ *   conflict: (options: {
+ *     message: string,
+ *     onKeepMine: () => void | Promise<void>,
+ *     onLoadLatest: () => void,
+ *   }) => unknown,
+ * }} ConflictToast
+ */
+
+/**
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function readUploadUrl(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const url = /** @type {Record<string, unknown>} */ (value).url;
+  return typeof url === 'string' && url.trim() ? url.trim() : null;
+}
+
+/**
+ * @param {object} options
+ * @param {(attr: string) => ParsedCaretBinding | null} options.parseCaretAttr
+ * @param {(element: Element, success: boolean) => void} options.flash
+ * @param {(file: File) => Promise<File>} options.compressImage
+ * @param {(image: HTMLImageElement, url: string) => void} options.updateEmblaCarousel
+ * @param {(collection: string, id: string, field: string, value: string) => Promise<SaveResult>} options.saveField
+ * @param {(state: 'saving' | 'error', text: string) => void} options.setStatus
+ * @param {ConflictToast} options.showToast
+ * @param {() => void} options.onUnauthorized
+ */
 export function mountImageEditors({
   parseCaretAttr,
   flash,
@@ -12,6 +46,7 @@ export function mountImageEditors({
   showToast,
   onUnauthorized,
 }) {
+  /** @param {string} marker @param {string} src */
   const syncBoundImages = (marker, src) => {
     document.querySelectorAll('[data-caret]').forEach((node) => {
       if (!(node instanceof HTMLImageElement)) return;
@@ -85,6 +120,12 @@ export function mountImageEditors({
     // (we hold the stored `mineUrl`); only writing it into the entry conflicted.
     // Keep the uploaded image shown and let the user choose, rather than
     // silently swapping in whatever landed elsewhere.
+    /**
+     * @param {ResolvedCaretBinding} resolved
+     * @param {string} marker
+     * @param {string} mineUrl
+     * @param {unknown} latestValue
+     */
     const runImageConflict = (resolved, marker, mineUrl, latestValue) => {
       showToast.conflict({
         message: 'This image changed elsewhere while you were editing.',
@@ -146,7 +187,8 @@ export function mountImageEditors({
           return;
         }
         if (!uploadRes.ok) throw new Error('Upload failed');
-        const { url } = await uploadRes.json();
+        const url = readUploadUrl(await uploadRes.json());
+        if (!url) throw new Error('Invalid upload response');
 
         // Point at the durable uploaded URL now, so the shown image survives the
         // optimistic blob being revoked in `finally` (and any conflict prompt).

package/static/cms/editor/image-utils.js

@@ -1,3 +1,9 @@
+/**
+ * @param {File} file
+ * @param {number} [maxWidth]
+ * @param {number} [quality]
+ * @returns {Promise<File>}
+ */
 export async function compressImage(file, maxWidth = 1600, quality = 0.82) {
   if (file.size < 200000 && file.type === 'image/webp') return file;
 
@@ -22,6 +28,10 @@ export async function compressImage(file, maxWidth = 1600, quality = 0.82) {
   canvas.width = width;
   canvas.height = height;
   const ctx = canvas.getContext('2d');
+  if (!ctx) {
+    bitmap.close();
+    return file;
+  }
   ctx.drawImage(bitmap, 0, 0, width, height);
   bitmap.close();
 
@@ -29,7 +39,7 @@ export async function compressImage(file, maxWidth = 1600, quality = 0.82) {
   const isPng = file.type === 'image/png';
   const outType = isPng ? 'image/png' : 'image/webp';
 
-  const blob = await new Promise((resolve) =>
+  const blob = await new Promise((/** @type {(value: Blob | null) => void} */ resolve) =>
     canvas.toBlob((b) => resolve(b), outType, isPng ? undefined : quality),
   );
 
@@ -40,6 +50,10 @@ export async function compressImage(file, maxWidth = 1600, quality = 0.82) {
   return new File([blob], name, { type: outType });
 }
 
+/**
+ * @param {HTMLImageElement} img
+ * @param {string} newUrl
+ */
 export function updateEmblaCarousel(img, newUrl) {
   // Find the closest Embla container
   const emblaContainer = img.closest('.embla');
@@ -47,10 +61,12 @@ export function updateEmblaCarousel(img, newUrl) {
 
   // Find the slide this image belongs to
   const slide = img.closest('.embla__slide');
-  if (!slide) return;
+  if (!(slide instanceof HTMLElement)) return;
 
-  const slideIndex = parseInt(slide.dataset.index, 10);
-  if (isNaN(slideIndex)) return;
+  const index = slide.dataset.index;
+  if (!index) return;
+  const slideIndex = Number.parseInt(index, 10);
+  if (Number.isNaN(slideIndex)) return;
 
   // Update the data-full attribute for lightbox
   slide.dataset.full = newUrl;
@@ -59,7 +75,7 @@ export function updateEmblaCarousel(img, newUrl) {
   const thumbBtn = document.querySelector(`.thumb-btn[data-index="${slideIndex}"]`);
   if (thumbBtn) {
     const thumbImg = thumbBtn.querySelector('img');
-    if (thumbImg) {
+    if (thumbImg instanceof HTMLImageElement) {
       thumbImg.src = newUrl;
       // Add a flash effect to show it updated
       thumbBtn.classList.add('cms-thumb-updated');
@@ -69,10 +85,10 @@ export function updateEmblaCarousel(img, newUrl) {
 
   // Update lightbox thumbnails if visible
   const lightboxThumb = document.querySelector(`.lightbox-thumb[data-index="${slideIndex}"]`);
-  if (lightboxThumb) {
+  if (lightboxThumb instanceof HTMLElement) {
     lightboxThumb.dataset.src = newUrl;
     const lbImg = lightboxThumb.querySelector('img');
-    if (lbImg) lbImg.src = newUrl;
+    if (lbImg instanceof HTMLImageElement) lbImg.src = newUrl;
   }
 
   // Dispatch custom event that the product page can listen to

package/static/cms/editor/link-follow.js

@@ -5,22 +5,32 @@
  * module restores a visible way to follow the link without leaving edit mode.
  */
 
+/** @type {HTMLAnchorElement | null} */
 let activeBtn = null;
+/** @type {HTMLAnchorElement | null} */
 let activeAnchor = null;
+/** @type {number | null} */
 let hideTimer = null;
 
+/** @param {string | null} href @returns {boolean} */
 function isFollowableHref(href) {
   if (!href) return false;
   const trimmed = href.trim();
   if (!trimmed || trimmed === "#") return false;
-  if (trimmed.startsWith("javascript:")) return false;
-  return true;
+  try {
+    const url = new URL(trimmed, window.location.href);
+    return ["http:", "https:", "mailto:", "tel:"].includes(url.protocol);
+  } catch {
+    return false;
+  }
 }
 
+/** @param {string} href @returns {boolean} */
 function isExternal(href) {
   return /^https?:\/\//i.test(href);
 }
 
+/** @param {string} href @returns {string} */
 function shortLabel(href) {
   if (isExternal(href)) {
     try {
@@ -32,45 +42,94 @@ function shortLabel(href) {
   return href;
 }
 
+function cancelHide() {
+  if (hideTimer !== null) {
+    clearTimeout(hideTimer);
+    hideTimer = null;
+  }
+}
+
 function removeBtn() {
   if (activeBtn) {
     activeBtn.remove();
     activeBtn = null;
     activeAnchor = null;
   }
-  if (hideTimer) {
-    clearTimeout(hideTimer);
-    hideTimer = null;
-  }
+  cancelHide();
 }
 
+/** @param {HTMLAnchorElement} anchor @param {HTMLAnchorElement} btn */
 function position(anchor, btn) {
+  if (!anchor.isConnected || !btn.isConnected) {
+    removeBtn();
+    return;
+  }
   const rect = anchor.getBoundingClientRect();
-  // Place above the anchor, right-aligned to its right edge so it doesn't
-  // overlap the editable text on hover.
-  const top = rect.top + window.scrollY - btn.offsetHeight - 8;
-  const left = rect.right + window.scrollX - btn.offsetWidth;
-  btn.style.top = `${Math.max(8 + window.scrollY, top)}px`;
-  btn.style.left = `${Math.max(8, left)}px`;
+  if (rect.bottom < 0 || rect.top > window.innerHeight) {
+    removeBtn();
+    return;
+  }
+
+  const gap = 8;
+  const margin = 8;
+  const width = btn.offsetWidth;
+  const height = btn.offsetHeight;
+  const candidates = [
+    { left: rect.right + gap, top: rect.top + (rect.height - height) / 2 },
+    { left: rect.left, top: rect.bottom + gap },
+    { left: rect.left, top: rect.top - height - gap },
+    { left: rect.left - width - gap, top: rect.top + (rect.height - height) / 2 },
+  ];
+  const otherEditables = Array.from(document.querySelectorAll('[data-caret]'))
+    .filter((el) => !anchor.contains(el))
+    .map((el) => el.getBoundingClientRect());
+
+  /** @param {{ left: number, top: number }} candidate */
+  function overlapsEditable(candidate) {
+    const box = {
+      left: candidate.left,
+      top: candidate.top,
+      right: candidate.left + width,
+      bottom: candidate.top + height,
+    };
+    return otherEditables.some((other) =>
+      box.left < other.right && box.right > other.left && box.top < other.bottom && box.bottom > other.top
+    );
+  }
+
+  const placed = candidates.find((candidate) =>
+    candidate.left >= margin
+    && candidate.top >= margin
+    && candidate.left + width <= window.innerWidth - margin
+    && candidate.top + height <= window.innerHeight - margin
+    && !overlapsEditable(candidate)
+  );
+
+  btn.classList.toggle('cms-link-follow-compact', !placed);
+  const fallback = {
+    left: Math.min(window.innerWidth - width - margin, Math.max(margin, rect.right - width)),
+    top: Math.min(window.innerHeight - height - margin, Math.max(margin, rect.top)),
+  };
+  const target = placed || fallback;
+  btn.style.top = `${target.top}px`;
+  btn.style.left = `${target.left}px`;
 }
 
 function scheduleHide() {
-  if (hideTimer) clearTimeout(hideTimer);
+  cancelHide();
   hideTimer = window.setTimeout(removeBtn, 180);
 }
 
+/** @param {HTMLAnchorElement} anchor */
 function show(anchor) {
   if (activeAnchor === anchor && activeBtn) {
-    if (hideTimer) {
-      clearTimeout(hideTimer);
-      hideTimer = null;
-    }
+    cancelHide();
     return;
   }
   removeBtn();
 
   const href = anchor.getAttribute("href");
-  if (!isFollowableHref(href)) return;
+  if (!isFollowableHref(href) || typeof href !== 'string') return;
 
   const external = isExternal(href);
   const btn = document.createElement("a");
@@ -81,20 +140,20 @@ function show(anchor) {
     btn.target = "_blank";
     btn.rel = "noopener noreferrer";
   }
-  btn.innerHTML = `
-    <svg viewBox="0 0 16 16" fill="none" aria-hidden="true">
-      <path d="M5 11 L11 5" stroke="currentColor" stroke-width="1.4" stroke-linecap="square"/>
-      <path d="M6 5 L11 5 L11 10" stroke="currentColor" stroke-width="1.4" stroke-linecap="square"/>
-    </svg>
-    <span>Open ${external ? "link" : "page"}</span>
-    <em>${shortLabel(href)}</em>
-  `;
+  btn.setAttribute('aria-label', `Open ${external ? "link" : "page"}: ${shortLabel(href)}`);
+  const icon = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+  icon.setAttribute('viewBox', '0 0 16 16');
+  icon.setAttribute('fill', 'none');
+  icon.setAttribute('aria-hidden', 'true');
+  icon.innerHTML = '<path d="M5 11 L11 5" stroke="currentColor" stroke-width="1.4" stroke-linecap="square"/><path d="M6 5 L11 5 L11 10" stroke="currentColor" stroke-width="1.4" stroke-linecap="square"/>';
+  const label = document.createElement('span');
+  label.textContent = `Open ${external ? "link" : "page"}`;
+  const destination = document.createElement('em');
+  destination.textContent = shortLabel(href);
+  btn.append(icon, label, destination);
 
   btn.addEventListener("mouseenter", () => {
-    if (hideTimer) {
-      clearTimeout(hideTimer);
-      hideTimer = null;
-    }
+    cancelHide();
   });
   btn.addEventListener("mouseleave", scheduleHide);
 
@@ -105,18 +164,27 @@ function show(anchor) {
 }
 
 export function mountLinkFollowAffordances() {
+  /** @param {Element} target @returns {Element | null} */
+  function editableFromTarget(target) {
+    const direct = target.closest('[data-caret]');
+    if (direct) return direct;
+    return target.closest('.cms-img-wrapper')?.querySelector('img[data-caret]') || null;
+  }
+
+  /** @param {Element} editable @returns {HTMLAnchorElement | null} */
+  function anchorFromEditable(editable) {
+    return editable instanceof HTMLAnchorElement ? editable : editable.closest('a');
+  }
+
   document.addEventListener("mouseover", (e) => {
     const target = e.target;
     if (!(target instanceof Element)) return;
     if (target.closest(".cms-link-follow")) return;
 
-    const editable = target.closest("[data-caret]");
+    const editable = editableFromTarget(target);
     if (!editable) return;
 
-    // Image editables have their own overlay treatment — skip.
-    if (editable instanceof HTMLImageElement) return;
-
-    const anchor = editable.matches("a") ? editable : editable.closest("a");
+    const anchor = anchorFromEditable(editable);
     if (!anchor) return;
 
     show(anchor);
@@ -127,12 +195,8 @@ export function mountLinkFollowAffordances() {
     if (!(target instanceof Element)) return;
     if (target.closest(".cms-link-follow")) return;
 
-    const editable = target.closest("[data-caret]");
-    const anchor = editable
-      ? editable.matches("a")
-        ? editable
-        : editable.closest("a")
-      : null;
+    const editable = editableFromTarget(target);
+    const anchor = editable ? anchorFromEditable(editable) : null;
     if (anchor === activeAnchor) scheduleHide();
   });
 
@@ -141,4 +205,21 @@ export function mountLinkFollowAffordances() {
   };
   window.addEventListener("scroll", reposition, { passive: true });
   window.addEventListener("resize", reposition);
+
+  document.addEventListener('focusin', (e) => {
+    const target = e.target;
+    if (!(target instanceof Element)) return;
+    if (target.closest('.cms-link-follow')) {
+      cancelHide();
+      return;
+    }
+    const editable = editableFromTarget(target);
+    const anchor = editable ? anchorFromEditable(editable) : null;
+    if (anchor) show(anchor);
+  });
+  document.addEventListener('focusout', (e) => {
+    const target = e.target;
+    if (!(target instanceof Element)) return;
+    if (editableFromTarget(target)) scheduleHide();
+  });
 }

package/static/cms/editor/link-ui.css

@@ -148,7 +148,7 @@
    --------------------------------------------------------------------------- */
 
 .cms-link-follow {
-  position: absolute;
+  position: fixed;
   z-index: 100000;
   display: inline-flex;
   align-items: center;
@@ -169,6 +169,15 @@
   animation: cms-link-follow-in 0.16s ease-out;
 }
 
+.cms-link-follow.cms-link-follow-compact span,
+.cms-link-follow.cms-link-follow-compact em {
+  display: none;
+}
+
+.cms-link-follow.cms-link-follow-compact {
+  padding: 7px;
+}
+
 .cms-link-follow:hover {
   background: rgba(59, 130, 246, 0.18);
   border-color: var(--cms-accent);

package/static/cms/editor/linkify.js

@@ -1,3 +1,4 @@
+/** @param {string} s */
 export function escapeHtml(s) {
   return s
     .replace(/&/g, '&')
@@ -6,6 +7,7 @@ export function escapeHtml(s) {
     .replace(/"/g, '"');
 }
 
+/** @param {string} text */
 export function clientLinkify(text) {
   if (!text) return '';