@caretcms/core 0.3.0 → 0.4.0

package/static/cms/editor/rich-toolbar.js

@@ -6,12 +6,21 @@
  * cross-browser approach for contenteditable formatting).
  */
 
-import { sanitizeHtml } from './sanitize.js';
+/** @typedef {{ dirtyEls: Set<Element>, linkPopupEl: HTMLElement | null }} RichEditorState */
+/** @typedef {(url: string | null) => void} LinkApplyCallback */
+/** @typedef {(rect: DOMRect | DOMRectReadOnly, initialUrl: string, onApply: LinkApplyCallback) => void} ShowLinkPopup */
+/** @typedef {{ sep?: boolean, cmd?: string, label?: string, title?: string, style?: string, isLink?: boolean }} ToolbarItem */
 
+/** @type {HTMLDivElement | null} */
 let toolbar = null;
+/** @type {HTMLElement | null} */
 let currentRichEl = null;
+/** @type {ShowLinkPopup | null} */
 let showLinkPopupFn = null;
+/** @type {RichEditorState | null} */
+let editorState = null;
 
+/** @type {ToolbarItem[]} */
 const BUTTONS = [
   { cmd: 'bold', label: 'B', title: 'Bold (Ctrl+B)', style: 'font-weight:700' },
   { cmd: 'italic', label: 'I', title: 'Italic (Ctrl+I)', style: 'font-style:italic' },
@@ -20,6 +29,7 @@ const BUTTONS = [
   { cmd: 'removeFormat', label: 'T\u2093', title: 'Clear formatting' },
 ];
 
+/** @returns {HTMLDivElement} */
 function createToolbar() {
   const el = document.createElement('div');
   el.className = 'cms-rich-toolbar';
@@ -32,19 +42,21 @@ function createToolbar() {
       el.appendChild(sep);
       continue;
     }
+    if (!btn.cmd) continue;
+    const command = btn.cmd;
 
     const button = document.createElement('button');
     button.type = 'button';
     button.className = 'cms-rich-toolbar-btn';
-    button.title = btn.title;
-    button.dataset.cmd = btn.cmd;
+    button.title = btn.title || '';
+    button.dataset.cmd = command;
     if (btn.style) button.style.cssText = btn.style;
 
     // Use text for simple labels, innerHTML for the link icon
     if (btn.isLink) {
       button.innerHTML = `<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M10 13a5 5 0 007.54.54l3-3a5 5 0 00-7.07-7.07l-1.72 1.71"/><path d="M14 11a5 5 0 00-7.54-.54l-3 3a5 5 0 007.07 7.07l1.71-1.71"/></svg>`;
     } else {
-      button.textContent = btn.label;
+      button.textContent = btn.label || '';
     }
 
     button.addEventListener('mousedown', (e) => {
@@ -52,7 +64,8 @@ function createToolbar() {
       if (btn.isLink) {
         handleLinkButton();
       } else {
-        document.execCommand(btn.cmd, false, null);
+        document.execCommand(command);
+        if (currentRichEl) editorState?.dirtyEls.add(currentRichEl);
         updateActiveStates();
       }
     });
@@ -69,10 +82,12 @@ function createToolbar() {
 
 function handleLinkButton() {
   const sel = window.getSelection();
-  if (!sel || sel.isCollapsed || !currentRichEl) return;
+  if (!sel || sel.isCollapsed || sel.rangeCount === 0 || !currentRichEl) return;
 
   const range = sel.getRangeAt(0).cloneRange();
   const selRect = range.getBoundingClientRect();
+  const target = currentRichEl;
+  const selectedText = sel.toString();
 
   // Check if selection is already a link
   const anchorNode = sel.anchorNode;
@@ -81,18 +96,32 @@ function handleLinkButton() {
     : anchorNode instanceof Element ? anchorNode.closest('a') : null;
   const initialUrl = existingLink?.getAttribute('href') || '';
 
+  function liveExistingLink() {
+    if (!existingLink) return null;
+    if (target.contains(existingLink)) return existingLink;
+    return Array.from(target.querySelectorAll('a')).find((link) =>
+      link.getAttribute('href') === initialUrl && link.textContent === selectedText
+    ) || null;
+  }
+
   if (showLinkPopupFn) {
     showLinkPopupFn(selRect, initialUrl, (url) => {
-      currentRichEl?.focus();
+      target.focus();
+      const link = liveExistingLink();
 
       if (url) {
         const newSel = window.getSelection();
+        if (!newSel) {
+          if (editorState) editorState.linkPopupEl = null;
+          hide();
+          return;
+        }
         newSel.removeAllRanges();
         newSel.addRange(range);
 
-        if (existingLink) {
+        if (link) {
           // Update existing link
-          existingLink.setAttribute('href', url);
+          link.setAttribute('href', url);
         } else {
           document.execCommand('createLink', false, url);
         }
@@ -109,13 +138,19 @@ function handleLinkButton() {
             newLink.setAttribute('rel', 'noopener noreferrer');
           }
         }
-      } else if (url === '' && existingLink) {
+        editorState?.dirtyEls.add(target);
+      } else if (url === '' && link) {
         // Empty URL = unlink
-        document.execCommand('unlink', false, null);
+        document.execCommand('unlink');
+        editorState?.dirtyEls.add(target);
       }
 
+      if (editorState) editorState.linkPopupEl = null;
       hide();
     });
+    // showLinkPopup dismisses any prior popover first, which clears this state.
+    // Claim the new popover only after it has completed that cleanup.
+    if (editorState) editorState.linkPopupEl = target;
   }
 }
 
@@ -123,8 +158,9 @@ function updateActiveStates() {
   if (!toolbar) return;
   const buttons = toolbar.querySelectorAll('.cms-rich-toolbar-btn[data-cmd]');
   for (const btn of buttons) {
+    if (!(btn instanceof HTMLButtonElement)) continue;
     const cmd = btn.dataset.cmd;
-    if (cmd === 'createLink' || cmd === 'removeFormat') continue;
+    if (!cmd || cmd === 'createLink' || cmd === 'removeFormat') continue;
     try {
       btn.classList.toggle('active', document.queryCommandState(cmd));
     } catch {
@@ -133,8 +169,9 @@ function updateActiveStates() {
   }
 }
 
+/** @param {Selection} sel */
 function position(sel) {
-  if (!toolbar || !sel || sel.isCollapsed) return;
+  if (!toolbar || sel.isCollapsed || sel.rangeCount === 0) return;
 
   const range = sel.getRangeAt(0);
   const rect = range.getBoundingClientRect();
@@ -154,6 +191,7 @@ function position(sel) {
   toolbar.style.top = `${top}px`;
 }
 
+/** @param {Selection} sel */
 function show(sel) {
   if (!toolbar) toolbar = createToolbar();
   toolbar.style.display = 'flex';
@@ -182,7 +220,7 @@ function onSelectionChange() {
     ? anchor.closest('[data-caret-rich], [data-caret-md]')
     : anchor?.parentElement?.closest('[data-caret-rich], [data-caret-md]');
 
-  if (!richEl) {
+  if (!(richEl instanceof HTMLElement)) {
     hide();
     return;
   }
@@ -193,9 +231,14 @@ function onSelectionChange() {
 
 /**
  * Mount the rich text toolbar. Call once during editor boot.
- * @param {{ state: object, showToast: Function, showLinkPopup?: Function }} opts
+ * @param {object} options
+ * @param {RichEditorState} options.state
+ * @param {(message: string, kind: 'success' | 'error') => unknown} options.showToast
+ * @param {ShowLinkPopup} [options.showLinkPopup]
  */
 export function mountRichToolbar({ state, showToast, showLinkPopup }) {
+  editorState = state;
+  void showToast;
   showLinkPopupFn = showLinkPopup || null;
   document.addEventListener('selectionchange', onSelectionChange);
 }

package/static/cms/editor/sanitize.js

@@ -10,9 +10,10 @@
 // import it). They are `export`ed so tests/unit/sanitizer-parity.test.ts can
 // assert they never drift from the source of truth — CI fails on divergence.
 export const ALLOWED_TAGS = new Set([
-  'b', 'strong', 'i', 'em', 'u', 's', 'a', 'br', 'sub', 'sup', 'span',
+  'b', 'strong', 'i', 'em', 'u', 's', 'a', 'br', 'sub', 'sup', 'span', 'code',
 ]);
 
+/** @type {Readonly<Record<string, ReadonlySet<string>>>} */
 export const ALLOWED_ATTRS = {
   a: new Set(['href', 'target', 'rel']),
 };
@@ -50,9 +51,12 @@ export function classAllowed(cls, patterns) {
 export function sanitizeHtml(html, options) {
   if (!html) return '';
 
+  const injected = typeof window !== 'undefined'
+    ? /** @type {Window & { __CARET__?: { allowedClasses?: Record<string, readonly string[]> } }} */ (window).__CARET__
+    : undefined;
   const allowedClasses =
     options?.allowedClasses ??
-    (typeof window !== 'undefined' ? window.__CARET__?.allowedClasses : undefined) ??
+    injected?.allowedClasses ??
     null;
 
   const doc = new DOMParser().parseFromString(`<body>${html}</body>`, 'text/html');

package/static/cms/editor/save-queue.js

@@ -1,26 +1,55 @@
-import { buildCmsUrl } from './config.js';
+import { buildCmsUrl, isPolicyDraftMode } from './config.js';
 import { mutateHeaders, readHeaders } from './security.js';
 
+/** @typedef {{ revision: number, data: Record<string, unknown> }} EntrySnapshot */
+/**
+ * @typedef {{ ok: true, revision?: number }
+ *   | { ok: false, reason: 'conflict', currentRevision?: number, latestValue?: string }
+ *   | { ok: false, reason: 'unauthorized' | 'error' }} SaveResult
+ */
+/** @typedef {'saving' | 'idle' | 'error'} SaveStatus */
+/** @typedef {{ type: 'save_field', collection: string, id: string, field: string, value: string, expectedRevision?: number }} SaveFieldPayload */
+
+/** @param {string} collection @param {string} id @returns {string} */
 function entryKey(collection, id) {
   return `${collection}::${id}`;
 }
 
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
 function isRecord(value) {
-  return typeof value === 'object' && value !== null;
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** @param {unknown} value @returns {value is number} */
+function isRevision(value) {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
 }
 
+/** @param {unknown} data @param {string} path @returns {string | undefined} */
 function getNestedStringValue(data, path) {
   if (!isRecord(data)) return undefined;
 
+  /** @type {unknown} */
   let current = data;
   for (const segment of path.split('.')) {
-    if (!isRecord(current) && !Array.isArray(current)) return undefined;
-    current = current[segment];
+    if (Array.isArray(current)) {
+      if (!/^\d+$/.test(segment)) return undefined;
+      current = current[Number(segment)];
+    } else if (isRecord(current)) {
+      if (!Object.hasOwn(current, segment)) return undefined;
+      current = current[segment];
+    } else return undefined;
   }
 
   return typeof current === 'string' ? current : undefined;
 }
 
+/**
+ * @param {string} collection
+ * @param {string} id
+ * @param {() => void} onUnauthorized
+ * @returns {Promise<EntrySnapshot | null>}
+ */
 async function fetchEntrySnapshot(collection, id, onUnauthorized) {
   const res = await fetch(buildCmsUrl('/entries', { collection, id }), {
     headers: readHeaders(),
@@ -32,27 +61,42 @@ async function fetchEntrySnapshot(collection, id, onUnauthorized) {
   if (!res.ok) throw new Error('Failed to load entry');
 
   const json = await res.json();
-  const entry = Array.isArray(json.entries) ? json.entries[0] : null;
-  if (!entry || !isRecord(entry.data)) {
+  if (!isRecord(json) || !Array.isArray(json.entries)) {
+    throw new Error('Invalid entry response');
+  }
+  const entry = json.entries[0];
+  if (entry === undefined) {
     return { revision: 0, data: {} };
   }
+  if (!isRecord(entry) || !isRecord(entry.data) || !isRevision(entry.revision)) {
+    throw new Error('Invalid entry response');
+  }
 
   return {
-    revision: Number.isInteger(entry.revision) ? entry.revision : 0,
+    revision: entry.revision,
     data: entry.data,
   };
 }
 
+/**
+ * @param {object} options
+ * @param {(status: SaveStatus, message: string) => void} options.setStatus
+ * @param {() => void} options.onUnauthorized
+ * @returns {(collection: string, id: string, field: string, value: string) => Promise<SaveResult>}
+ */
 export function createSaveField({ setStatus, onUnauthorized }) {
+  /** @type {Promise<unknown>} */
   let saveQueue = Promise.resolve();
+  /** @type {Map<string, number>} */
   const revisionByEntry = new Map();
+  /** @type {Map<string, Promise<number | null>>} */
   const revisionLoadByEntry = new Map();
 
+  /** @param {string} collection @param {string} id @returns {Promise<number | null>} */
   async function ensureRevision(collection, id) {
     const key = entryKey(collection, id);
-    if (revisionByEntry.has(key)) {
-      return revisionByEntry.get(key);
-    }
+    const cached = revisionByEntry.get(key);
+    if (cached !== undefined) return cached;
 
     const inFlight = revisionLoadByEntry.get(key);
     if (inFlight) return inFlight;
@@ -70,6 +114,10 @@ export function createSaveField({ setStatus, onUnauthorized }) {
     return task;
   }
 
+  /**
+   * @param {string} collection @param {string} id @param {string} field
+   * @returns {Promise<{ currentRevision: number | undefined, latestValue: string | undefined }>}
+   */
   async function readLatestFieldValue(collection, id, field) {
     const snapshot = await fetchEntrySnapshot(collection, id, onUnauthorized);
     if (!snapshot) return { currentRevision: undefined, latestValue: undefined };
@@ -81,6 +129,10 @@ export function createSaveField({ setStatus, onUnauthorized }) {
     };
   }
 
+  /**
+   * @param {string} collection @param {string} id @param {string} field @param {string} value
+   * @returns {Promise<SaveResult>}
+   */
   async function execSave(collection, id, field, value) {
     setStatus('saving', 'Saving...');
     const key = entryKey(collection, id);
@@ -91,6 +143,7 @@ export function createSaveField({ setStatus, onUnauthorized }) {
         return { ok: false, reason: 'unauthorized' };
       }
 
+      /** @type {SaveFieldPayload} */
       const body = { type: 'save_field', collection, id, field, value };
       if (typeof expectedRevision === 'number') {
         body.expectedRevision = expectedRevision;
@@ -106,16 +159,18 @@ export function createSaveField({ setStatus, onUnauthorized }) {
         return { ok: false, reason: 'unauthorized' };
       }
 
-      const json = await res.json().catch(() => ({}));
+      const parsed = await res.json().catch(() => null);
+      const json = isRecord(parsed) ? parsed : {};
       if (!res.ok) {
         if (res.status === 409) {
-          const currentRevision = Number.isInteger(json.currentRevision)
+          const currentRevision = isRevision(json.currentRevision)
             ? json.currentRevision
             : undefined;
           if (typeof currentRevision === 'number') {
             revisionByEntry.set(key, currentRevision);
           }
 
+          /** @type {{ currentRevision: number | undefined, latestValue: string | undefined }} */
           let latest = { currentRevision: undefined, latestValue: undefined };
           try {
             latest = await readLatestFieldValue(collection, id, field);
@@ -138,16 +193,18 @@ export function createSaveField({ setStatus, onUnauthorized }) {
         return { ok: false, reason: 'error' };
       }
 
-      const nextRevision = Number.isInteger(json.revision)
+      const fallbackRevision = typeof expectedRevision === 'number' && expectedRevision < Number.MAX_SAFE_INTEGER
+        ? expectedRevision + 1
+        : undefined;
+      const nextRevision = isRevision(json.revision)
         ? json.revision
-        : typeof expectedRevision === 'number'
-          ? expectedRevision + 1
-          : undefined;
+        : fallbackRevision;
       if (typeof nextRevision === 'number') {
         revisionByEntry.set(key, nextRevision);
       }
 
-      setStatus('idle', 'Saved');
+      setStatus('idle', isPolicyDraftMode() ? 'Draft saved' : 'Saved');
+      if (isPolicyDraftMode()) window.dispatchEvent(new CustomEvent('cms:draftSaved'));
       return { ok: true, revision: nextRevision };
     } catch {
       setStatus('error', 'Save failed');
@@ -155,6 +212,7 @@ export function createSaveField({ setStatus, onUnauthorized }) {
     }
   }
 
+  /** @param {string} collection @param {string} id @param {string} field @param {string} value */
   return function saveField(collection, id, field, value) {
     const task = saveQueue.then(() => execSave(collection, id, field, value));
     saveQueue = task.then(

package/static/cms/editor/section-controls/activation.js

@@ -1,3 +1,6 @@
+/**
+ * @param {{ sectionNode: HTMLElement, sectionId: string, setActiveSection: (sectionId: string) => void }} options
+ */
 export function bindSectionActivation({ sectionNode, sectionId, setActiveSection }) {
   sectionNode.addEventListener('mouseenter', () => setActiveSection(sectionId));
   sectionNode.addEventListener('focusin', () => setActiveSection(sectionId));

package/static/cms/editor/section-controls/api.js

@@ -2,6 +2,17 @@ import { buildCmsUrl } from '../config.js';
 import { isRecord } from './utils.js';
 import { mutateHeaders, readHeaders } from '../security.js';
 
+/** @typedef {import('./model.js').Section} Section */
+
+/** @param {unknown} value @returns {value is number} */
+function isRevision(value) {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+/**
+ * @param {{ collection: string, id: string, onUnauthorized: () => void }} options
+ * @returns {Promise<{ data: Record<string, unknown>, revision: number } | null>}
+ */
 export async function fetchPageEntry({ collection, id, onUnauthorized }) {
   const res = await fetch(buildCmsUrl('/entries', { collection, id }), {
     headers: readHeaders(),
@@ -13,18 +24,23 @@ export async function fetchPageEntry({ collection, id, onUnauthorized }) {
   if (!res.ok) throw new Error('Failed to load page data');
 
   const json = await res.json();
-  const entry = Array.isArray(json.entries) ? json.entries[0] : null;
-  if (!entry || !isRecord(entry.data)) {
+  const entry = isRecord(json) && Array.isArray(json.entries) ? json.entries[0] : null;
+  if (!isRecord(entry) || !isRecord(entry.data)) {
     throw new Error('Page entry not found');
   }
 
   return {
     data: entry.data,
-    revision: Number.isInteger(entry.revision) ? entry.revision : 0,
+    revision: isRevision(entry.revision) ? entry.revision : 0,
   };
 }
 
+/**
+ * @param {{ collection: string, id: string, sections: Section[], expectedRevision: number, onUnauthorized: () => void }} options
+ * @returns {Promise<{ ok: true, revision: number } | { ok: false, reason: 'unauthorized' | 'conflict' | 'error', currentRevision?: number | null, error?: string }>}
+ */
 export async function savePageLayout({
+  collection,
   id,
   sections,
   expectedRevision,
@@ -35,6 +51,7 @@ export async function savePageLayout({
     headers: await mutateHeaders(),
     body: JSON.stringify({
       type: 'update_page_layout',
+      collection,
       id,
       sections,
       expectedRevision,
@@ -46,13 +63,14 @@ export async function savePageLayout({
     return { ok: false, reason: 'unauthorized' };
   }
 
-  const json = await res.json().catch(() => ({}));
+  const rawJson = await res.json().catch(() => ({}));
+  const json = isRecord(rawJson) ? rawJson : {};
   if (!res.ok) {
     if (res.status === 409) {
       return {
         ok: false,
         reason: 'conflict',
-        currentRevision: Number.isInteger(json.currentRevision) ? json.currentRevision : null,
+        currentRevision: isRevision(json.currentRevision) ? json.currentRevision : null,
       };
     }
     const issue = Array.isArray(json.issues) ? json.issues[0] : null;
@@ -78,9 +96,9 @@ export async function savePageLayout({
   return {
     ok: true,
     revision:
-      Number.isInteger(json.revision)
+      isRevision(json.revision)
         ? json.revision
-        : Number.isInteger(expectedRevision)
+        : isRevision(expectedRevision)
           ? expectedRevision + 1
           : 1,
   };