@caretcms/core 0.1.2 → 0.3.0

package/static/cms/editor/guards.js

@@ -2,7 +2,7 @@ export function mountEditorGuards(state) {
   document.body.classList.add('cms-edit-mode');
 
   window.addEventListener('beforeunload', (e) => {
-    if (state.dirtyEl) {
+    if (state.dirtyEls.size > 0) {
       e.preventDefault();
       e.returnValue = '';
     }

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

@@ -72,6 +72,7 @@ export function mountImageEditors({
     const input = document.createElement('input');
     input.type = 'file';
     input.accept = 'image/jpeg,image/png,image/webp,image/avif';
+    input.setAttribute('aria-label', 'Upload replacement image');
     input.style.display = 'none';
     wrapper.appendChild(input);
 
@@ -80,6 +81,34 @@ export function mountImageEditors({
       input.click();
     });
 
+    // Save-conflict resolution for images: the upload itself already succeeded
+    // (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.
+    const runImageConflict = (resolved, marker, mineUrl, latestValue) => {
+      showToast.conflict({
+        message: 'This image changed elsewhere while you were editing.',
+        onKeepMine: async () => {
+          setStatus('saving', 'Saving...');
+          const retry = await saveField(resolved.collection, resolved.id, resolved.field, mineUrl);
+          flash(img, retry.ok);
+          if (retry.ok) {
+            syncBoundImages(marker, mineUrl);
+            showToast('Your image saved', 'success');
+          } else if (retry.reason === 'conflict') {
+            runImageConflict(resolved, marker, mineUrl, retry.latestValue);
+          } else if (retry.reason !== 'unauthorized') {
+            showToast('Failed to save image. Try again.', 'error');
+          }
+        },
+        onLoadLatest: () => {
+          const src = typeof latestValue === 'string' ? latestValue : mineUrl;
+          syncBoundImages(marker, src);
+          showToast('Loaded latest image', 'success');
+        },
+      });
+    };
+
     input.addEventListener('change', async () => {
       const file = input.files?.[0];
       if (!file) return;
@@ -110,27 +139,29 @@ export function mountImageEditors({
           body: formData,
         });
         if (uploadRes.status === 401) {
+          // Restore the real image before the redirect — the optimistic blob is
+          // revoked in `finally`, so leaving it as src would flash a broken image.
+          img.src = originalSrc;
           onUnauthorized();
           return;
         }
         if (!uploadRes.ok) throw new Error('Upload failed');
         const { url } = await uploadRes.json();
 
+        // Point at the durable uploaded URL now, so the shown image survives the
+        // optimistic blob being revoked in `finally` (and any conflict prompt).
+        img.src = url;
+
         const result = await saveField(resolved.collection, resolved.id, resolved.field, url);
         if (result.ok) {
           syncBoundImages(marker, url);
           showToast('Image updated', 'success');
-        } else {
-          const rollbackSrc =
-            result.reason === 'conflict' && typeof result.latestValue === 'string'
-              ? result.latestValue
-              : originalSrc;
-          syncBoundImages(marker, rollbackSrc);
-          if (result.reason === 'conflict') {
-            showToast('Image changed elsewhere. Loaded latest image.', 'error');
-          } else if (result.reason !== 'unauthorized') {
-            showToast('Failed to save image. Changes reverted.', 'error');
-          }
+        } else if (result.reason === 'conflict') {
+          // Keep the uploaded image shown; let the user choose.
+          runImageConflict(resolved, marker, url, result.latestValue);
+        } else if (result.reason !== 'unauthorized') {
+          syncBoundImages(marker, originalSrc);
+          showToast('Failed to save image. Changes reverted.', 'error');
         }
 
         flash(img, result.ok);

package/static/cms/editor/image.css

@@ -65,10 +65,16 @@
   z-index: 11;
 }
 
-.cms-img-wrapper:hover .cms-img-overlay {
+.cms-img-wrapper:hover .cms-img-overlay,
+.cms-img-wrapper:focus-within .cms-img-overlay {
   opacity: 1;
 }
 
+.cms-img-overlay:focus-visible {
+  outline: 2px solid var(--cms-accent, #3b82f6);
+  outline-offset: -2px;
+}
+
 .cms-img-overlay-content {
   display: flex;
   flex-direction: column;

package/static/cms/editor/md-block-edit.js

@@ -0,0 +1,176 @@
+/**
+ * Inline editing for markdown body blocks (`data-caret-md`).
+ *
+ * A stamped block (paragraph / heading / list item, bound by the render-time
+ * mdast plugin) becomes contenteditable; the floating rich toolbar provides
+ * bold/italic/link. On blur the block's sanitized inner HTML is sent as an
+ * `md_block` mutation — the server derives the markdown, verifies the source
+ * range hash, and stores the draft in the editor's overlay. The `.md` file is
+ * only touched at Publish.
+ *
+ * No `expectedRevision` is sent: body drafts live in a PER-EDITOR overlay, so
+ * there is no cross-editor race on the draft itself — the source-range hash in
+ * `data-caret-md-src` is the staleness guard that matters, and a 409 here
+ * means the underlying file changed (publish, external edit) and the page must
+ * be reloaded to pick up fresh stamps.
+ */
+
+import { serializeBlock, domToSNodes, SerializeError } from './md-serialize.js';
+import { sanitizeHtml } from './sanitize.js';
+import { buildCmsUrl } from './config.js';
+import { mutateHeaders } from './security.js';
+
+const snapshots = new WeakMap();
+
+// All md-block saves are chained through one queue (same pattern as
+// save-queue.js): two fast blur-saves of the same block can otherwise race on
+// the network and land out of order — both return ok, and the older content
+// silently wins. A per-element generation counter additionally drops a queued
+// save that a newer blur has superseded.
+let saveChain = Promise.resolve();
+const generations = new WeakMap();
+
+function enqueueSave(task) {
+  const run = saveChain.then(task, task);
+  saveChain = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  return run;
+}
+
+/** Parse `collection::id::body::blockPath`, or null. */
+function parseMdBinding(raw) {
+  const parts = (raw || '').split('::');
+  if (parts.length !== 4 || parts[2] !== 'body') return null;
+  if (!/^\d+(\.\d+)*$/.test(parts[3])) return null;
+  return { collection: parts[0], id: parts[1], blockPath: parts[3] };
+}
+
+/** Serialization context from the DOM — mirrors the server's derivation. */
+function blockContextOf(el) {
+  const heading = /^h([1-6])$/.exec(el.tagName.toLowerCase());
+  if (heading) return { block: 'heading', level: Number(heading[1]) };
+  const nested = el.tagName.toLowerCase() === 'li' || el.closest('li, blockquote') !== null;
+  return { block: 'paragraph', nested };
+}
+
+async function saveMdBlock(binding, src, html) {
+  const res = await fetch(buildCmsUrl('/mutate'), {
+    method: 'POST',
+    headers: await mutateHeaders(),
+    body: JSON.stringify({
+      type: 'md_block',
+      collection: binding.collection,
+      id: binding.id,
+      blockPath: binding.blockPath,
+      src,
+      html,
+    }),
+  });
+  if (res.status === 401) return { ok: false, reason: 'unauthorized' };
+  if (res.status === 409) return { ok: false, reason: 'stale' };
+  if (!res.ok) return { ok: false, reason: 'error' };
+  return { ok: true };
+}
+
+export function mountMdBlockEditors({ state, flash, showToast, onUnauthorized }) {
+  document.querySelectorAll('[data-caret-md]').forEach((el) => {
+    if (!(el instanceof HTMLElement)) return;
+    if (el.dataset.caretMdMounted === 'true') return;
+
+    const binding = parseMdBinding(el.getAttribute('data-caret-md'));
+    const src = el.getAttribute('data-caret-md-src') || '';
+    if (!binding || !src) return;
+    el.dataset.caretMdMounted = 'true';
+
+    const ctx = blockContextOf(el);
+
+    el.setAttribute('contenteditable', 'true');
+    el.classList.add('cms-editable', 'cms-md-block');
+
+    el.addEventListener('keydown', (event) => {
+      if (event.key !== 'Enter') return;
+      if (event.shiftKey && ctx.block === 'paragraph' && !ctx.nested) {
+        return; // hard break in a top-level paragraph — allowed
+      }
+      event.preventDefault();
+      showToast(
+        event.shiftKey
+          ? 'Line breaks are not supported in this block'
+          : 'Adding new blocks is coming in a future version',
+        'error',
+      );
+    });
+
+    el.addEventListener('focus', () => {
+      snapshots.set(el, el.innerHTML);
+    });
+
+    el.addEventListener('input', () => {
+      if (el.innerHTML !== snapshots.get(el)) state.dirtyEls.add(el);
+      else state.dirtyEls.delete(el);
+    });
+
+    el.addEventListener('blur', async () => {
+      if (el._caretSkipSave) {
+        el._caretSkipSave = false;
+        state.dirtyEls.delete(el);
+        el.innerHTML = snapshots.get(el) || '';
+        return;
+      }
+
+      const snapshot = snapshots.get(el) ?? '';
+      const clean = sanitizeHtml(el.innerHTML);
+      el.innerHTML = clean; // normalize what the user sees to what will save
+      if (clean === snapshot) return;
+
+      // Pre-flight the serialization locally so unrepresentable content fails
+      // with an immediate message instead of a server round-trip. The server
+      // re-derives independently — this is UX, not the trust boundary.
+      try {
+        serializeBlock(domToSNodes(el), ctx);
+      } catch (error) {
+        if (error instanceof SerializeError) {
+          showToast('This formatting cannot be saved in a markdown block', 'error');
+          state.dirtyEls.add(el);
+          return;
+        }
+        throw error;
+      }
+
+      const generation = (generations.get(el) ?? 0) + 1;
+      generations.set(el, generation);
+
+      el.classList.add('cms-saving');
+      const result = await enqueueSave(() => {
+        // A newer blur queued behind us supersedes this content — skip so the
+        // older payload can't overwrite the newer draft.
+        if (generations.get(el) !== generation) return { ok: true, skipped: true };
+        return saveMdBlock(binding, src, clean);
+      });
+      el.classList.remove('cms-saving');
+      if (result.skipped) return;
+      flash(el, result.ok);
+
+      if (result.ok) {
+        state.dirtyEls.delete(el);
+        snapshots.set(el, clean);
+        showToast('Draft saved — publish to update the file', 'success');
+        // Signal the toolbar so server-delivery mode reveals its Publish/Discard
+        // controls (hidden until a body draft is pending).
+        window.dispatchEvent(new CustomEvent('cms:draftSaved'));
+      } else if (result.reason === 'stale') {
+        state.dirtyEls.delete(el);
+        el.innerHTML = snapshot;
+        showToast('This content changed since the page loaded. Reload to edit it.', 'error');
+      } else if (result.reason === 'unauthorized') {
+        onUnauthorized();
+      } else {
+        state.dirtyEls.delete(el);
+        el.innerHTML = snapshot;
+        showToast('Failed to save. Changes reverted.', 'error');
+      }
+    });
+  });
+}

package/static/cms/editor/md-serialize.js

@@ -0,0 +1,301 @@
+/**
+ * DOM → markdown block serializer (browser side).
+ *
+ * NOTE: `serializeBlock` and its helpers below are a HAND MIRROR of
+ * src/markdown/serialize.ts (this file ships as raw unbundled JS and can't
+ * import it). tests/unit/md-serialize-parity.test.ts runs both implementations
+ * over a shared corpus of node trees and fails CI on any divergence.
+ *
+ * `domToSNodes` is the only DOM-touching part: it converts a block element's
+ * child nodes into the same minimal tree the TS serializer is tested against,
+ * so the serialization logic itself stays DOM-free and parity-checkable.
+ *
+ * @typedef {{ type: 'text', value: string }
+ *   | { type: 'element', tag: string, attrs: Record<string,string>, children: SNode[] }} SNode
+ */
+
+export class SerializeError extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = 'SerializeError';
+  }
+}
+
+const INLINE_ESCAPE_RE = /[\\`*_[\]<&>~]/g;
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeText(value) {
+  // Collapse ASCII whitespace runs to a single space FIRST — matches HTML
+  // rendering and makes <br> the serializer's only newline source. nbsp is
+  // deliberately NOT collapsed.
+  return value.replace(/[ \t\r\n]+/g, ' ').replace(INLINE_ESCAPE_RE, (c) => `\\${c}`);
+}
+
+/**
+ * @param {string} md
+ * @returns {string}
+ */
+function escapeLineStart(md) {
+  const ws = /^\s*/.exec(md)[0];
+  const rest = md.slice(ws.length);
+
+  const ordered = /^(\d{1,9})([.)])(\s|$)/.exec(rest);
+  if (ordered) {
+    return `${ws}${ordered[1]}\\${ordered[2]}${rest.slice(ordered[1].length + 1)}`;
+  }
+
+  // Dash/equals runs cover setext underlines (ONE-or-more `-`/`=`) and
+  // thematic breaks with interior spaces; `*`/`_` variants are already
+  // neutralized by escapeText.
+  const marker =
+    /^(?:#{1,6}(?=\s|$)|>|[-+*](?=\s|$)|-(?:[ \t]*-)*[ \t]*$|=(?:[ \t]*=)*[ \t]*$|~{3,}|`{3,}|\|)/.test(
+      rest,
+    );
+  return marker ? `${ws}\\${rest}` : md;
+}
+
+/**
+ * @param {Extract<SNode, { type: 'element' }>} node
+ * @returns {string}
+ */
+function tagOf(node) {
+  const t = node.tag.toLowerCase();
+  if (t === 'b') return 'strong';
+  if (t === 'i') return 'em';
+  return t;
+}
+
+/**
+ * @param {readonly SNode[]} nodes
+ * @returns {string}
+ */
+function rawText(nodes) {
+  let out = '';
+  for (const n of nodes) {
+    if (n.type === 'text') out += n.value;
+    else if (n.tag.toLowerCase() === 'br') out += ' ';
+    else out += rawText(n.children);
+  }
+  return out;
+}
+
+/**
+ * @param {string} content
+ * @returns {string}
+ */
+function codeSpan(content) {
+  if (content === '') return '``';
+  const runs = content.match(/`+/g) ?? [];
+  let fenceLen = 1;
+  while (runs.some((r) => r.length === fenceLen)) fenceLen++;
+  const fence = '`'.repeat(fenceLen);
+  const needsPad =
+    content.startsWith('`') ||
+    content.endsWith('`') ||
+    (content.startsWith(' ') && content.endsWith(' ') && content.trim() !== '');
+  return needsPad ? `${fence} ${content} ${fence}` : `${fence}${content}${fence}`;
+}
+
+/**
+ * @param {string} href
+ * @returns {string}
+ */
+function linkDestination(href) {
+  // Control chars (incl. \n, \r) have no representable escape in either
+  // destination form — hard-fail rather than inject markdown structure.
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f]/u.test(href)) {
+    throw new SerializeError('control character in link destination');
+  }
+  if (/^[^\s<>()\\]*$/.test(href)) return href;
+  return `<${href.replace(/([<>\\])/g, '\\$1')}>`;
+}
+
+/**
+ * @param {Record<string,string>} a
+ * @param {Record<string,string>} b
+ * @returns {boolean}
+ */
+function sameAttrs(a, b) {
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  return ka.length === kb.length && ka.every((k) => a[k] === b[k]);
+}
+
+/**
+ * @param {readonly SNode[]} nodes
+ * @returns {SNode[]}
+ */
+function mergeAdjacent(nodes) {
+  /** @type {SNode[]} */
+  const out = [];
+  for (const node of nodes) {
+    const prev = out[out.length - 1];
+    if (node.type === 'text' && prev?.type === 'text') {
+      prev.value += node.value;
+      continue;
+    }
+    if (
+      node.type === 'element' &&
+      prev?.type === 'element' &&
+      tagOf(prev) === tagOf(node) &&
+      tagOf(node) !== 'br' &&
+      sameAttrs(prev.attrs, node.attrs)
+    ) {
+      prev.children = [...prev.children, ...node.children];
+      continue;
+    }
+    out.push(node.type === 'text' ? { ...node } : { ...node, children: [...node.children] });
+  }
+  return out;
+}
+
+/**
+ * @param {readonly SNode[]} nodes
+ * @param {number} i
+ * @returns {string}
+ */
+function nextLeadChar(nodes, i) {
+  const next = nodes[i + 1];
+  if (!next) return '';
+  if (next.type === 'text') return next.value[0] ?? '';
+  return '<';
+}
+
+/**
+ * @param {readonly SNode[]} nodes
+ * @param {number} i
+ * @param {'*' | '_' | null} prevMarker
+ * @returns {'*' | '_'}
+ */
+function emphasisMarker(nodes, i, prevMarker) {
+  if (prevMarker === null) return '*';
+  const flipped = prevMarker === '*' ? '_' : '*';
+  if (flipped === '_' && /[A-Za-z0-9_]/.test(nextLeadChar(nodes, i))) return '*';
+  return flipped;
+}
+
+/**
+ * @param {readonly SNode[]} rawNodes
+ * @param {{ allowBreak: boolean }} opts
+ * @returns {string}
+ */
+function serializeChildren(rawNodes, opts) {
+  const nodes = mergeAdjacent(rawNodes);
+  let out = '';
+  /** @type {'*' | '_' | null} */
+  let prevMarker = null;
+  for (let i = 0; i < nodes.length; i++) {
+    const node = nodes[i];
+    if (node.type === 'text') {
+      out += escapeText(node.value);
+      prevMarker = null;
+      continue;
+    }
+    const tag = tagOf(node);
+    switch (tag) {
+      case 'strong': {
+        const inner = serializeChildren(node.children, opts);
+        if (inner === '') {
+          prevMarker = null;
+          break;
+        }
+        const m = emphasisMarker(nodes, i, prevMarker);
+        out += `${m}${m}${inner}${m}${m}`;
+        prevMarker = m;
+        break;
+      }
+      case 'em': {
+        const inner = serializeChildren(node.children, opts);
+        if (inner === '') {
+          prevMarker = null;
+          break;
+        }
+        const m = emphasisMarker(nodes, i, prevMarker);
+        out += `${m}${inner}${m}`;
+        prevMarker = m;
+        break;
+      }
+      case 'code': {
+        prevMarker = null;
+        out += codeSpan(rawText(node.children));
+        break;
+      }
+      case 'a': {
+        const href = node.attrs.href;
+        if (href === undefined) throw new SerializeError('<a> without href');
+        prevMarker = null;
+        const inner = serializeChildren(node.children, opts);
+        out += `[${inner}](${linkDestination(href)})`;
+        break;
+      }
+      case 'br': {
+        if (!opts.allowBreak) {
+          throw new SerializeError('hard break not allowed in a nested block');
+        }
+        prevMarker = null;
+        out += '\\\n';
+        break;
+      }
+      default:
+        throw new SerializeError(`unsupported inline element <${node.tag}>`);
+    }
+  }
+  return out;
+}
+
+/**
+ * Serialize the inline children of one block to markdown source.
+ * @param {readonly SNode[]} children
+ * @param {{ block: 'heading', level: number } | { block: 'paragraph', nested: boolean }} ctx
+ * @returns {string}
+ */
+export function serializeBlock(children, ctx) {
+  if (ctx.block === 'heading') {
+    if (!Number.isInteger(ctx.level) || ctx.level < 1 || ctx.level > 6) {
+      throw new SerializeError(`invalid heading level: ${ctx.level}`);
+    }
+    const inline = serializeChildren(children, { allowBreak: false });
+    return `${'#'.repeat(ctx.level)} ${inline}`;
+  }
+  const inline = serializeChildren(children, { allowBreak: !ctx.nested });
+  // Every line (hard breaks are the only line boundary) must be prevented
+  // from opening a new block — CommonMark's block scanner runs before inline
+  // parsing sees the trailing backslash.
+  return inline.split('\\\n').map(escapeLineStart).join('\\\n');
+}
+
+/**
+ * Convert a block element's DOM children into the minimal SNode tree the
+ * serializer consumes. Only `href` is carried (the sole attribute the closed
+ * set represents); every other element passes through so the serializer can
+ * reject anything the sanitizer failed to strip.
+ * @param {Node} element
+ * @returns {SNode[]}
+ */
+export function domToSNodes(element) {
+  /** @type {SNode[]} */
+  const out = [];
+  for (const child of element.childNodes) {
+    if (child.nodeType === 3 /* TEXT_NODE */) {
+      out.push({ type: 'text', value: /** @type {Text} */ (child).data });
+    } else if (child.nodeType === 1 /* ELEMENT_NODE */) {
+      const elem = /** @type {Element} */ (child);
+      /** @type {Record<string,string>} */
+      const attrs = {};
+      const href = elem.getAttribute('href');
+      if (href !== null) attrs.href = href;
+      out.push({
+        type: 'element',
+        tag: elem.tagName.toLowerCase(),
+        attrs,
+        children: domToSNodes(elem),
+      });
+    }
+  }
+  return out;
+}