@caretcms/core 0.3.0 → 0.4.0

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

@@ -23,6 +23,22 @@ import { createSpacingDragController } from './spacing-drag.js';
 import { bindDragSourceHandlers, bindDropTargetHandlers } from './reorder.js';
 import { bindSectionActivation } from './activation.js';
 
+/** @typedef {import('./model.js').Section} Section */
+/** @typedef {import('./page-context.js').PageContext} PageContext */
+/** @typedef {{ collection: string | null, id: string | null, field: string }} ParsedCaretBinding */
+/** @typedef {ReturnType<typeof createSpacingDragController>} SpacingDragController */
+/** @typedef {'saving' | 'idle' | 'error'} ToolbarStatusState */
+/** @typedef {'success' | 'error'} ToastType */
+
+/**
+ * @param {{
+ *   parseCaretAttr: (value: string) => ParsedCaretBinding | null,
+ *   setStatus: (type: ToolbarStatusState, message: string) => void,
+ *   showToast: (message: string, type?: ToastType) => void,
+ *   onUnauthorized: () => void,
+ *   onCanvasStructureChanged?: () => void,
+ * }} options
+ */
 export function mountSectionControls({
   parseCaretAttr,
   setStatus,
@@ -30,33 +46,46 @@ export function mountSectionControls({
   onUnauthorized,
   onCanvasStructureChanged,
 }) {
+  /** @type {HTMLElement[]} */
   let sectionNodes = Array.from(
     document.querySelectorAll('[data-caret-section][data-caret-section-id]'),
-  );
+  ).filter((node) => node instanceof HTMLElement);
   if (!sectionNodes.length) return;
 
-  const pageContext = getPageContext(parseCaretAttr, sectionNodes);
-  if (!pageContext) return;
+  const detectedPageContext = getPageContext(parseCaretAttr, sectionNodes);
+  if (!detectedPageContext) return;
+  /** @type {PageContext} */
+  const pageContext = detectedPageContext;
 
+  /** @type {Section[]} */
   let sections = sectionsFromDom(sectionNodes);
+  /** @type {Record<string, unknown>} */
   let entryData = {};
   let revision = 0;
   let busy = false;
+  /** @type {string | null} */
   let dragSourceId = null;
   let refreshRequired = false;
 
+  /** @type {Map<string, HTMLElement>} */
   const sectionNodeById = new Map();
+  /** @type {Map<string, HTMLButtonElement>} */
   const toggleButtonsById = new Map();
+  /** @type {Map<string, HTMLButtonElement>} */
   const spacingButtonsById = new Map();
+  /** @type {Map<string, HTMLButtonElement>} */
   const gapHandlesById = new Map();
+  /** @type {Map<string, HTMLElement>} */
   const sectionTemplateByKey = new Map();
+  /** @type {SpacingDragController | null} */
   let spacingDragController = null;
 
   sectionNodes.forEach((sectionNode) => {
     if (!(sectionNode instanceof HTMLElement)) return;
     const sectionKey = sectionNode.getAttribute('data-caret-section') || 'home.hero';
     if (sectionTemplateByKey.has(sectionKey)) return;
-    sectionTemplateByKey.set(sectionKey, sectionNode.cloneNode(true));
+    const cloned = sectionNode.cloneNode(true);
+    if (cloned instanceof HTMLElement) sectionTemplateByKey.set(sectionKey, cloned);
   });
 
   document
@@ -70,7 +99,8 @@ export function mountSectionControls({
         '[data-caret-section][data-caret-section-id]',
       );
       if (!(contentNode instanceof HTMLElement)) return;
-      sectionTemplateByKey.set(sectionKey, contentNode.cloneNode(true));
+      const cloned = contentNode.cloneNode(true);
+      if (cloned instanceof HTMLElement) sectionTemplateByKey.set(sectionKey, cloned);
     });
 
   const addPicker = createAddPicker({
@@ -97,6 +127,7 @@ export function mountSectionControls({
     },
   });
 
+  /** @param {Section[]} sectionList @returns {Section[]} */
   function serializeSectionsForLayout(sectionList) {
     return sectionList.map((section) => ({
       id: section.id,
@@ -130,16 +161,17 @@ export function mountSectionControls({
     document.body.classList.remove('cms-spacing-dragging');
   }
 
+  /** @param {boolean} disabled */
   function setControlsDisabled(disabled) {
     const shouldDisable = disabled || refreshRequired;
     document.querySelectorAll('.cms-section-btn').forEach((button) => {
-      button.disabled = shouldDisable;
+      if (button instanceof HTMLButtonElement) button.disabled = shouldDisable;
     });
     document.querySelectorAll('.cms-section-insert-handle').forEach((button) => {
-      button.disabled = shouldDisable;
+      if (button instanceof HTMLButtonElement) button.disabled = shouldDisable;
     });
     document.querySelectorAll('.cms-section-gap-handle').forEach((button) => {
-      button.disabled = shouldDisable;
+      if (button instanceof HTMLButtonElement) button.disabled = shouldDisable;
     });
     addPicker.setDisabled(shouldDisable);
     spacingPicker.setDisabled(shouldDisable);
@@ -162,6 +194,7 @@ export function mountSectionControls({
       busy || refreshRequired || Boolean(dragSourceId) || Boolean(spacingDragController?.isDragging()),
   });
 
+  /** @param {string} sectionId @param {string | undefined} spacingY */
   function setNodeSpacingPreview(sectionId, spacingY) {
     const node = sectionNodeById.get(sectionId);
     if (!(node instanceof HTMLElement)) return;
@@ -172,6 +205,7 @@ export function mountSectionControls({
     }
   }
 
+  /** @param {string} sectionId */
   function updateSpacingUi(sectionId) {
     const section = sections.find((item) => item.id === sectionId);
     if (!section) return;
@@ -191,6 +225,7 @@ export function mountSectionControls({
     }
   }
 
+  /** @param {string} sectionId */
   function updateToggleUi(sectionId) {
     const section = sections.find((item) => item.id === sectionId);
     if (!section) return;
@@ -200,6 +235,7 @@ export function mountSectionControls({
     }
   }
 
+  /** @param {string} sectionId @param {boolean} enabled */
   function setSectionEnabledPreview(sectionId, enabled) {
     const node = sectionNodeById.get(sectionId);
     if (!(node instanceof HTMLElement)) return;
@@ -207,6 +243,7 @@ export function mountSectionControls({
     node.setAttribute('data-caret-section-enabled', enabled === false ? 'false' : 'true');
   }
 
+  /** @param {string} sectionId @param {string} sectionKey @returns {Section} */
   function getSectionSnapshot(sectionId, sectionKey) {
     return sections.find((item) => item.id === sectionId) || {
       id: sectionId,
@@ -215,6 +252,7 @@ export function mountSectionControls({
     };
   }
 
+  /** @param {string} sectionId @param {number} order @param {string} sectionKey */
   function updateSectionChip(sectionId, order, sectionKey) {
     const node = sectionNodeById.get(sectionId);
     if (!(node instanceof HTMLElement)) return;
@@ -226,6 +264,7 @@ export function mountSectionControls({
     }
   }
 
+  /** @param {HTMLElement} sectionNode @param {number} sectionIndex */
   function mountSectionNode(sectionNode, sectionIndex) {
     if (!(sectionNode instanceof HTMLElement)) return;
 
@@ -362,6 +401,7 @@ export function mountSectionControls({
     updateSectionChip(sectionId, sectionIndex + 1, sectionKey);
   }
 
+  /** @param {Section[]} nextSections @returns {boolean} */
   function applySectionsToCanvas(nextSections) {
     if (!Array.isArray(nextSections) || !nextSections.length) return false;
 
@@ -376,6 +416,7 @@ export function mountSectionControls({
       existingById.set(id, node);
     });
 
+    /** @type {HTMLElement[]} */
     const nextNodes = [];
     let structureChanged = false;
 
@@ -441,6 +482,9 @@ export function mountSectionControls({
     return true;
   }
 
+  /**
+   * @param {{ statusMessage: string, toastMessage: string, statusType?: ToolbarStatusState, toastType?: ToastType }} options
+   */
   function markRefreshRequired({
     statusMessage,
     toastMessage,
@@ -480,6 +524,7 @@ export function mountSectionControls({
     showToast('Layout conflict resolved with latest content.', 'success');
   }
 
+  /** @param {string} sectionId @param {unknown} spacingValue @returns {boolean} */
   function applySectionSpacing(sectionId, spacingValue) {
     const index = sections.findIndex((section) => section.id === sectionId);
     if (index === -1) return false;
@@ -493,6 +538,11 @@ export function mountSectionControls({
     return true;
   }
 
+  /**
+   * @param {string} action
+   * @param {string} sectionId
+   * @param {{ sectionKey?: unknown, spacingY?: unknown }} [payload]
+   */
   function mutateSections(action, sectionId, payload) {
     const result = mutateSectionsModel({
       sections,
@@ -523,6 +573,7 @@ export function mountSectionControls({
     },
   });
 
+  /** @param {string} successMessage */
   async function persistWithReload(successMessage) {
     if (!canEditLayout()) return;
     if (busy) return;
@@ -535,6 +586,7 @@ export function mountSectionControls({
 
     try {
       const result = await savePageLayout({
+        collection: pageContext.collection,
         id: pageContext.id,
         sections,
         expectedRevision: revision,

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

@@ -1,33 +1,60 @@
 import { HOME_SECTION_KEYS } from './constants.js';
 import { normalizeSpacingY, isRecord } from './utils.js';
 
+/** @typedef {{ id: string, key: string, enabled: boolean, spacing_y?: string }} Section */
+
+/** @type {Record<string, string>} */
 const LEGACY_SECTION_KEY_MAP = {
   'home.trust_badges': 'home.logo_bar',
   'home.featured': 'home.features',
 };
 
+/** @param {unknown} rawKey @returns {string | null} */
 function normalizeSectionKey(rawKey) {
   if (typeof rawKey !== 'string') return null;
   const mapped = LEGACY_SECTION_KEY_MAP[rawKey] || rawKey;
   return HOME_SECTION_KEYS.includes(mapped) ? mapped : null;
 }
 
+/**
+ * @param {string} preferred
+ * @param {string} key
+ * @param {number} index
+ * @param {Set<string>} usedIds
+ * @returns {string}
+ */
+function uniqueSectionId(preferred, key, index, usedIds) {
+  const base = preferred.trim() || `sec-${key.replace(/\./g, '-')}-${index + 1}`;
+  let id = base;
+  let suffix = 2;
+  while (usedIds.has(id)) {
+    id = `${base}-${suffix}`;
+    suffix++;
+  }
+  usedIds.add(id);
+  return id;
+}
+
+/** @param {unknown} entryData @param {Section[]} fallbackFromDom @returns {Section[]} */
 export function normalizeSectionsFromData(entryData, fallbackFromDom) {
+  if (!isRecord(entryData)) return fallbackFromDom;
   const layout = isRecord(entryData.layout) ? entryData.layout : {};
   const raw = Array.isArray(layout.sections) ? layout.sections : null;
 
   if (!raw) return fallbackFromDom;
 
+  const usedIds = new Set();
   const normalized = raw
     .map((item, index) => {
       if (!isRecord(item)) return null;
       const key = normalizeSectionKey(item.key);
       if (!key) return null;
 
-      const id =
+      const preferredId =
         typeof item.id === 'string' && item.id.trim()
           ? item.id.trim()
           : `sec-${key.replace(/\./g, '-')}-${index + 1}`;
+      const id = uniqueSectionId(preferredId, key, index, usedIds);
 
       return {
         id,
@@ -36,13 +63,15 @@ export function normalizeSectionsFromData(entryData, fallbackFromDom) {
         spacing_y: normalizeSpacingY(item.spacing_y),
       };
     })
-    .filter(Boolean);
+    .filter((section) => section !== null);
 
   if (!normalized.length) return fallbackFromDom;
   return normalized;
 }
 
+/** @param {Element[]} sectionNodes @returns {Section[]} */
 export function sectionsFromDom(sectionNodes) {
+  const usedIds = new Set();
   return sectionNodes
     .map((el, index) => {
       const rawKey = el.getAttribute('data-caret-section') || 'home.hero';
@@ -50,16 +79,21 @@ export function sectionsFromDom(sectionNodes) {
       if (!key) return null;
 
       const fallbackId = `sec-${key.replace(/\./g, '-')}-${index + 1}`;
+      const rawId = el.getAttribute('data-caret-section-id') || fallbackId;
       return {
-        id: el.getAttribute('data-caret-section-id') || fallbackId,
+        id: uniqueSectionId(rawId, key, index, usedIds),
         key,
         enabled: true,
         spacing_y: normalizeSpacingY(el.getAttribute('data-caret-spacing-y')),
       };
     })
-    .filter(Boolean);
+    .filter((section) => section !== null);
 }
 
+/**
+ * @param {{ sections: Section[], sourceId: string, targetId: string, placeAfter: boolean }} options
+ * @returns {Section[]}
+ */
 export function reorderByDrag({ sections, sourceId, targetId, placeAfter }) {
   if (sourceId === targetId) return sections;
 
@@ -69,6 +103,7 @@ export function reorderByDrag({ sections, sourceId, targetId, placeAfter }) {
 
   const next = [...sections];
   const [source] = next.splice(sourceIndex, 1);
+  if (!source) return sections;
   const currentTargetIndex = next.findIndex((section) => section.id === targetId);
   const insertIndex = currentTargetIndex + (placeAfter ? 1 : 0);
   next.splice(insertIndex, 0, source);

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

@@ -5,6 +5,19 @@ import {
   normalizeSpacingY,
 } from './utils.js';
 
+/** @typedef {import('./model.js').Section} Section */
+/** @typedef {{ sectionKey?: unknown, spacingY?: unknown }} MutationPayload */
+
+/**
+ * @param {{
+ *   sections: Section[],
+ *   action: string,
+ *   sectionId: string,
+ *   payload?: MutationPayload,
+ *   applySpacing: (sectionId: string, spacingY: string | undefined) => boolean,
+ * }} options
+ * @returns {{ ok: true, message: string, sections: Section[] } | { ok: false, message: string }}
+ */
 export function mutateSections({
   sections,
   action,
@@ -33,6 +46,7 @@ export function mutateSections({
 
   if (action === 'duplicate') {
     const source = sections[index];
+    if (!source) return { ok: false, message: 'Section not found' };
     const duplicate = {
       ...source,
       id: `${source.id}-copy-${Math.random().toString(36).slice(2, 5)}`,
@@ -55,6 +69,7 @@ export function mutateSections({
 
   if (action === 'toggle') {
     const section = sections[index];
+    if (!section) return { ok: false, message: 'Section not found' };
     const enabledCount = sections.filter((item) => item.enabled).length;
     if (section.enabled && enabledCount <= 1) {
       return { ok: false, message: 'At least one section must remain visible' };

package/static/cms/editor/section-controls/page-context.js

@@ -1,3 +1,11 @@
+/** @typedef {{ collection: string, id: string }} PageContext */
+/** @typedef {{ collection: string | null, id: string | null, field: string }} ParsedCaretBinding */
+
+/**
+ * @param {(value: string) => ParsedCaretBinding | null} parseCaretAttr
+ * @param {Element[]} sectionNodes
+ * @returns {PageContext | null}
+ */
 export function getPageContext(parseCaretAttr, sectionNodes) {
   for (const sectionNode of sectionNodes) {
     if (!(sectionNode instanceof Element)) continue;
@@ -19,6 +27,7 @@ export function getPageContext(parseCaretAttr, sectionNodes) {
     const parsed = parseCaretAttr(attr);
     if (!parsed) continue;
     if (parsed.collection !== 'pages') continue;
+    if (!parsed.id) continue;
 
     return {
       collection: parsed.collection,

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

@@ -1,6 +1,10 @@
 import { HOME_SECTION_KEYS, SPACING_Y_OPTIONS } from './constants.js';
 import { humanizeSectionKey } from './utils.js';
 
+/**
+ * @param {{ picker: HTMLElement, getAnchor: () => HTMLButtonElement | null }} options
+ * @returns {() => void}
+ */
 function attachGlobalPositioning({ picker, getAnchor }) {
   function position() {
     const anchorButton = getAnchor();
@@ -25,6 +29,9 @@ function attachGlobalPositioning({ picker, getAnchor }) {
   return position;
 }
 
+/**
+ * @param {{ picker: HTMLElement, getAnchor: () => HTMLButtonElement | null, close: () => void }} options
+ */
 function attachOutsideClose({ picker, getAnchor, close }) {
   document.addEventListener('click', (event) => {
     if (picker.hidden) return;
@@ -38,9 +45,13 @@ function attachOutsideClose({ picker, getAnchor, close }) {
   });
 }
 
+/** @param {{ onPick: (sectionId: string, key: string) => void }} options */
 export function createAddPicker({ onPick }) {
   const picker = document.createElement('div');
+  picker.id = 'cms-section-add-picker';
   picker.className = 'cms-section-add-picker';
+  picker.setAttribute('role', 'dialog');
+  picker.setAttribute('aria-label', 'Insert section');
   picker.hidden = true;
   picker.innerHTML = `
     <div class="cms-section-add-picker-head">Insert Section</div>
@@ -59,10 +70,13 @@ export function createAddPicker({ onPick }) {
 
   document.body.appendChild(picker);
 
+  /** @type {string | null} */
   let openForSectionId = null;
+  /** @type {HTMLButtonElement | null} */
   let anchorButton = null;
 
   function close() {
+    anchorButton?.setAttribute('aria-expanded', 'false');
     picker.hidden = true;
     picker.classList.remove('open');
     openForSectionId = null;
@@ -74,14 +88,28 @@ export function createAddPicker({ onPick }) {
     getAnchor: () => anchorButton,
   });
 
+  /** @param {HTMLButtonElement} button @param {string} sectionId */
   function open(button, sectionId) {
     anchorButton = button;
     openForSectionId = sectionId;
+    button.setAttribute('aria-haspopup', 'dialog');
+    button.setAttribute('aria-controls', picker.id);
+    button.setAttribute('aria-expanded', 'true');
     picker.hidden = false;
     picker.classList.add('open');
     position();
+    const firstButton = picker.querySelector('button');
+    if (firstButton instanceof HTMLButtonElement) firstButton.focus();
   }
 
+  picker.addEventListener('keydown', (event) => {
+    if (event.key !== 'Escape') return;
+    event.preventDefault();
+    const previousAnchor = anchorButton;
+    close();
+    previousAnchor?.focus();
+  });
+
   picker.addEventListener('click', (event) => {
     const target = event.target;
     if (!(target instanceof Element)) return;
@@ -104,17 +132,22 @@ export function createAddPicker({ onPick }) {
   return {
     open,
     close,
+    /** @param {boolean} disabled */
     setDisabled(disabled) {
       picker.querySelectorAll('.cms-section-add-option').forEach((button) => {
-        button.disabled = disabled;
+        if (button instanceof HTMLButtonElement) button.disabled = disabled;
       });
     },
   };
 }
 
+/** @param {{ onPick: (sectionId: string, value: string) => void }} options */
 export function createSpacingPicker({ onPick }) {
   const picker = document.createElement('div');
+  picker.id = 'cms-section-spacing-picker';
   picker.className = 'cms-section-add-picker cms-section-spacing-picker';
+  picker.setAttribute('role', 'dialog');
+  picker.setAttribute('aria-label', 'Vertical spacing');
   picker.hidden = true;
   picker.innerHTML = `
     <div class="cms-section-add-picker-head">Vertical Spacing</div>
@@ -133,10 +166,13 @@ export function createSpacingPicker({ onPick }) {
 
   document.body.appendChild(picker);
 
+  /** @type {string | null} */
   let openForSectionId = null;
+  /** @type {HTMLButtonElement | null} */
   let anchorButton = null;
 
   function close() {
+    anchorButton?.setAttribute('aria-expanded', 'false');
     picker.hidden = true;
     picker.classList.remove('open');
     openForSectionId = null;
@@ -148,9 +184,13 @@ export function createSpacingPicker({ onPick }) {
     getAnchor: () => anchorButton,
   });
 
+  /** @param {HTMLButtonElement} button @param {string} sectionId @param {unknown} currentValue */
   function open(button, sectionId, currentValue) {
     anchorButton = button;
     openForSectionId = sectionId;
+    button.setAttribute('aria-haspopup', 'dialog');
+    button.setAttribute('aria-controls', picker.id);
+    button.setAttribute('aria-expanded', 'true');
     picker.hidden = false;
     picker.classList.add('open');
 
@@ -163,8 +203,18 @@ export function createSpacingPicker({ onPick }) {
     });
 
     position();
+    const selectedButton = picker.querySelector('button.active, button');
+    if (selectedButton instanceof HTMLButtonElement) selectedButton.focus();
   }
 
+  picker.addEventListener('keydown', (event) => {
+    if (event.key !== 'Escape') return;
+    event.preventDefault();
+    const previousAnchor = anchorButton;
+    close();
+    previousAnchor?.focus();
+  });
+
   picker.addEventListener('click', (event) => {
     const target = event.target;
     if (!(target instanceof Element)) return;
@@ -187,9 +237,10 @@ export function createSpacingPicker({ onPick }) {
   return {
     open,
     close,
+    /** @param {boolean} disabled */
     setDisabled(disabled) {
       picker.querySelectorAll('.cms-section-add-option').forEach((button) => {
-        button.disabled = disabled;
+        if (button instanceof HTMLButtonElement) button.disabled = disabled;
       });
     },
   };

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

@@ -1,5 +1,16 @@
 import { reorderByDrag } from './model.js';
 
+/** @typedef {import('./model.js').Section} Section */
+
+/**
+ * @param {{
+ *   controls: HTMLElement,
+ *   sectionId: string,
+ *   sectionNode: HTMLElement,
+ *   setDragSourceId: (sectionId: string | null) => void,
+ *   clearDropIndicators: () => void,
+ * }} options
+ */
 export function bindDragSourceHandlers({
   controls,
   sectionId,
@@ -29,6 +40,18 @@ export function bindDragSourceHandlers({
   });
 }
 
+/**
+ * @param {{
+ *   sectionNode: HTMLElement,
+ *   sectionId: string,
+ *   isBusy: () => boolean,
+ *   getDragSourceId: () => string | null,
+ *   getSections: () => Section[],
+ *   setSections: (sections: Section[]) => void,
+ *   clearDropIndicators: () => void,
+ *   onReordered: () => void,
+ * }} options
+ */
 export function bindDropTargetHandlers({
   sectionNode,
   sectionId,

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

@@ -1,10 +1,16 @@
+/**
+ * @param {{ sectionNodeById: Map<string, HTMLElement>, isSelectionLocked: () => boolean }} options
+ */
 export function createSectionSelectionController({
   sectionNodeById,
   isSelectionLocked,
 }) {
+  /** @type {string | null} */
   let activeSectionId = null;
+  /** @type {IntersectionObserver | null} */
   let observer = null;
 
+  /** @param {string} sectionId */
   function setActiveSection(sectionId) {
     if (!sectionId || activeSectionId === sectionId) return;
     activeSectionId = sectionId;

package/static/cms/editor/section-controls/spacing-drag.js

@@ -1,6 +1,19 @@
 import { SPACING_Y_VALUES } from './constants.js';
 import { spacingIndex } from './utils.js';
 
+/** @typedef {{ sectionId: string, startY: number, startIndex: number, currentIndex: number, changed: boolean, handle: HTMLButtonElement }} SpacingDragState */
+
+/**
+ * @param {{
+ *   isBusy: () => boolean,
+ *   isReordering: () => boolean,
+ *   closePickers: () => void,
+ *   getSectionSpacing: (sectionId: string) => string | undefined,
+ *   updateSpacingByToken: (sectionId: string, token: string) => boolean,
+ *   setActiveSection: (sectionId: string) => void,
+ *   onCommitted: (sectionId: string) => void,
+ * }} options
+ */
 export function createSpacingDragController({
   isBusy,
   isReordering,
@@ -10,6 +23,7 @@ export function createSpacingDragController({
   setActiveSection,
   onCommitted,
 }) {
+  /** @type {SpacingDragState | null} */
   let dragState = null;
 
   function stop() {
@@ -22,6 +36,7 @@ export function createSpacingDragController({
     dragState = null;
   }
 
+  /** @param {PointerEvent} event @param {string} sectionId @param {HTMLButtonElement} handle */
   function start(event, sectionId, handle) {
     if (isBusy()) return;
 
@@ -47,6 +62,7 @@ export function createSpacingDragController({
     window.addEventListener('pointercancel', onEnd, { once: true });
   }
 
+  /** @param {PointerEvent} event */
   function onMove(event) {
     if (!dragState || isBusy() || isReordering()) return;
 

package/static/cms/editor/section-controls/ui-elements.js

@@ -1,5 +1,8 @@
 import { spacingToken, humanizeSectionKey } from './utils.js';
 
+/** @typedef {import('./model.js').Section} Section */
+
+/** @returns {HTMLDivElement} */
 export function createSectionControlsElement() {
   const controls = document.createElement('div');
   controls.className = 'cms-section-controls';
@@ -17,6 +20,7 @@ export function createSectionControlsElement() {
   return controls;
 }
 
+/** @param {Section} section @param {number} order @returns {HTMLDivElement} */
 export function createSectionBadge(section, order) {
   const badge = document.createElement('div');
   badge.className = 'cms-section-chip';
@@ -24,11 +28,13 @@ export function createSectionBadge(section, order) {
   return badge;
 }
 
+/** @param {Section} section @returns {HTMLButtonElement} */
 export function createSpacingDragHandle(section) {
   const handle = document.createElement('button');
   handle.type = 'button';
   handle.className = 'cms-section-gap-handle';
   handle.title = 'Drag vertically to resize section spacing';
+  handle.setAttribute('aria-label', 'Resize vertical section spacing');
   handle.dataset.sectionId = section.id;
   handle.innerHTML = `
     <span class="cms-section-gap-grip"></span>
@@ -41,6 +47,7 @@ export function createSpacingDragHandle(section) {
   return handle;
 }
 
+/** @returns {HTMLButtonElement} */
 export function createInsertHandle() {
   const handle = document.createElement('button');
   handle.type = 'button';