@charlescms/astro 0.1.0

package/src/js-ast.js

@@ -0,0 +1,140 @@
+import { parse, parseExpression } from "@babel/parser";
+
+// AST-based reading of Astro frontmatter, using the Babel parser (full JS/TS
+// grammar, exact source offsets). This is what lets arbitrarily nested const
+// data structures resolve to a precise byte span. It is still NOT a JavaScript
+// evaluator: only string/object/array literal shapes become resolvable; calls,
+// template literals, conditions and identifiers stay dynamic. Anything Babel
+// cannot parse returns null so the caller falls back to the conservative
+// string-aware scanner — a parse problem degrades to a safe skip, never a write.
+const PARSE_OPTIONS = { sourceType: "module", plugins: ["typescript", "topLevelAwait"] };
+
+export function parseFrontmatterModule(code) {
+  try {
+    return parse(code, PARSE_OPTIONS);
+  } catch {
+    return null;
+  }
+}
+
+// Parses a bare value (a JSON data-collection file is one object/array, not a
+// program). Returns the value node or null when it cannot be parsed.
+export function parseValueExpression(code) {
+  try {
+    return parseExpression(code, { plugins: ["typescript"] });
+  } catch {
+    return null;
+  }
+}
+
+// Strips the type-only wrappers that can sit around a value (`x as const`,
+// `x satisfies T`, `x!`, `(x)`) so callers see the underlying literal.
+export function unwrapValue(node) {
+  let current = node;
+  while (current && (current.type === "TSAsExpression" || current.type === "TSSatisfiesExpression"
+    || current.type === "TSNonNullExpression" || current.type === "ParenthesizedExpression")) {
+    current = current.expression;
+  }
+  return current;
+}
+
+// Builds a map of `const NAME` → value tree for every top-level const whose
+// initializer is a resolvable literal shape. Returns null when the frontmatter
+// cannot be parsed, signalling the caller to use the scanner fallback.
+export function buildConstantTrees(code, baseOffset) {
+  const ast = parseFrontmatterModule(code);
+  if (!ast) return null;
+  const trees = new Map();
+  for (const statement of ast.program.body) {
+    if (statement.type !== "VariableDeclaration" || statement.kind !== "const") continue;
+    for (const declaration of statement.declarations) {
+      if (declaration.id.type !== "Identifier" || !declaration.init) continue;
+      const tree = toValueTree(declaration.init, code, baseOffset);
+      if (tree) trees.set(declaration.id.name, tree);
+    }
+  }
+  return trees;
+}
+
+// Resolves a template expression (e.g. `team[0].links.site`) against the const
+// trees, returning the exact source span of the string it points at, or null if
+// the path is dynamic, not a pure data access, or does not land on a string.
+export function resolveExpressionTree(trees, expression) {
+  let node;
+  try {
+    node = parseExpression(expression, { plugins: ["typescript"] });
+  } catch {
+    return null;
+  }
+  const resolved = walkPath(trees, node);
+  return resolved?.type === "string"
+    ? { value: resolved.value, start: resolved.start, end: resolved.end }
+    : null;
+}
+
+// Reduces an initializer AST to the minimal tree we can resolve to exact string
+// spans. Offsets are mapped from the parsed slice to absolute source offsets via
+// baseOffset. Escaped strings are dropped (kept locked) so the existing write
+// path is never asked to re-escape into a JS string literal.
+function toValueTree(node, code, baseOffset) {
+  if (!node) return null;
+  switch (node.type) {
+    case "StringLiteral": {
+      const start = node.start + 1;
+      const end = node.end - 1;
+      const value = code.slice(start, end);
+      if (value.includes("\\")) return null;
+      return { type: "string", value, start: baseOffset + start, end: baseOffset + end };
+    }
+    case "ObjectExpression": {
+      const props = new Map();
+      for (const property of node.properties) {
+        if (property.type !== "ObjectProperty" || property.computed) continue;
+        const key = objectKey(property.key);
+        if (key == null) continue;
+        const child = toValueTree(property.value, code, baseOffset);
+        if (child) props.set(key, child);
+      }
+      return { type: "object", props };
+    }
+    case "ArrayExpression":
+      // Holes (sparse arrays) and non-resolvable elements stay as null so index
+      // access lines up with the source positions.
+      return { type: "array", elements: node.elements.map((element) => toValueTree(element, code, baseOffset)) };
+    case "TSAsExpression":
+    case "TSSatisfiesExpression":
+    case "TSNonNullExpression":
+      // `[...] as const`, `x satisfies T`, `x!` — unwrap the type wrapper.
+      return toValueTree(node.expression, code, baseOffset);
+    default:
+      return null;
+  }
+}
+
+function objectKey(key) {
+  if (key.type === "Identifier") return key.name;
+  if (key.type === "StringLiteral") return key.value;
+  if (key.type === "NumericLiteral") return String(key.value);
+  return null;
+}
+
+// Walks a member/index access chain against the value trees. Only plain data
+// access is followed — a call, optional chain, or computed non-literal property
+// returns null so the expression stays dynamic.
+function walkPath(trees, node) {
+  if (!node) return null;
+  if (node.type === "Identifier") return trees.get(node.name) || null;
+  if (node.type === "TSNonNullExpression") return walkPath(trees, node.expression);
+  if (node.type === "MemberExpression" && !node.optional) {
+    const base = walkPath(trees, node.object);
+    if (!base) return null;
+    if (node.computed) {
+      const property = node.property;
+      if (property.type === "NumericLiteral" && base.type === "array") return base.elements[property.value] || null;
+      if (property.type === "StringLiteral" && base.type === "object") return base.props.get(property.value) || null;
+      return null;
+    }
+    if (node.property.type === "Identifier" && base.type === "object") return base.props.get(node.property.name) || null;
+  }
+  return null;
+}

package/src/markdown-analyzer.js

@@ -0,0 +1,95 @@
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { gfmFromMarkdown } from "mdast-util-gfm";
+import { toString } from "mdast-util-to-string";
+import { gfm } from "micromark-extension-gfm";
+import { getFrontmatter } from "./analyzer.js";
+import { createEntryId } from "./ids.js";
+
+// Maps safe Markdown blocks to exact source ranges. Complex blocks such as code,
+// tables, raw HTML, and ambiguous MDX stay locked because a visual edit could
+// otherwise change their structure or meaning.
+const allowedMarks = new Set(["text", "emphasis", "strong", "inlineCode", "link", "break"]);
+
+/**
+ * Map safe Markdown body blocks to exact source ranges for editing.
+ *
+ * Complex blocks (code, tables, raw HTML, ambiguous MDX) stay locked because a
+ * visual edit could change their structure or meaning.
+ *
+ * @param {string} source Full `.md`/`.mdx` file contents.
+ * @param {string} file File path; non-Markdown inputs return no entries.
+ * @returns {{entries: Object}} Map of entry id → Markdown block descriptor.
+ */
+export function transformMarkdownSource(source, file) {
+  if (!/\.(?:md|mdx)$/.test(file)) return { entries: {} };
+  const frontmatter = getFrontmatter(source);
+  const bodyOffset = frontmatter?.bodyOffset || 0;
+  const body = source.slice(bodyOffset);
+  let tree;
+  try {
+    tree = fromMarkdown(body, {
+      extensions: [gfm()],
+      mdastExtensions: [gfmFromMarkdown()]
+    });
+  } catch {
+    return { entries: {} };
+  }
+
+  const entries = {};
+  for (const node of tree.children || []) {
+    if (node.type === "heading") {
+      addInlineEntry(entries, source, file, node, `h${node.depth}`, bodyOffset);
+    } else if (node.type === "paragraph") {
+      addInlineEntry(entries, source, file, node, "p", bodyOffset);
+    } else if (node.type === "blockquote") {
+      const paragraph = singleParagraph(node.children);
+      if (paragraph) addInlineEntry(entries, source, file, paragraph, "blockquote", bodyOffset);
+    } else if (node.type === "list") {
+      for (const item of node.children || []) {
+        const paragraph = singleParagraph(item.children);
+        if (paragraph) addInlineEntry(entries, source, file, paragraph, "li", bodyOffset);
+      }
+    }
+  }
+  return { entries };
+}
+
+function addInlineEntry(entries, source, file, node, tag, bodyOffset) {
+  const children = node.children || [];
+  if (children.length === 0 || !children.every(isAllowedInlineNode)) return;
+  const first = children[0]?.position?.start?.offset;
+  const last = children.at(-1)?.position?.end?.offset;
+  if (!Number.isInteger(first) || !Number.isInteger(last) || last <= first) return;
+
+  const start = bodyOffset + first;
+  const end = bodyOffset + last;
+  const oldValue = source.slice(start, end);
+  if (!oldValue.trim() || isAmbiguousMdx(file, oldValue)) return;
+
+  // Every inline block is edited as rich text (bold, italic, inline code,
+  // links), so the experience is consistent and a plain paragraph can gain
+  // formatting. The serializer round-trips it back to safe inline Markdown.
+  const operation = { kind: "markdown-block", name: "body", start, end, oldValue };
+  const id = createEntryId(file, [operation]);
+  entries[id] = {
+    id,
+    file,
+    tag,
+    text: toString(node),
+    operations: [operation]
+  };
+}
+
+function isAllowedInlineNode(node) {
+  if (!allowedMarks.has(node.type)) return false;
+  if (node.type === "link" && typeof node.url !== "string") return false;
+  return (node.children || []).every(isAllowedInlineNode);
+}
+
+function singleParagraph(children = []) {
+  return children.length === 1 && children[0].type === "paragraph" ? children[0] : null;
+}
+
+function isAmbiguousMdx(file, value) {
+  return file.endsWith(".mdx") && (/<\/?[A-Za-z]|[{}]/.test(value));
+}

package/src/media-preview.js

@@ -0,0 +1,58 @@
+// In-session previews for replaced/uploaded images.
+//
+// A static host doesn't serve a newly committed asset until the site rebuilds, so
+// pointing an <img> straight at the new path shows a broken image until then — and
+// the preview is lost the moment you navigate away. This registry remembers the
+// chosen file as a blob URL keyed by its committed public path, shows it instantly,
+// and re-applies it every time the editor re-binds the page (across SPA
+// navigation). The committed PATH always remains the value written to source; the
+// blob is display-only and is forgotten on a full reload, by which point the real
+// asset is normally live.
+const previews = new Map(); // "/uploads/x.jpg" -> blob: URL
+
+function normalizePath(path) {
+  return String(path || "").split(/[?#]/)[0];
+}
+
+// Map a repo path (public/uploads/x.jpg) or a public URL (/uploads/x.jpg) to the
+// site-absolute path an <img src> uses.
+export function publicPathFromRepoPath(repoPath) {
+  const clean = normalizePath(repoPath).replace(/^\/+/, "");
+  if (!clean) return "";
+  return `/${clean.startsWith("public/") ? clean.slice("public/".length) : clean}`;
+}
+
+export function registerMediaPreview(publicPath, file) {
+  const key = normalizePath(publicPath);
+  if (!key || !file) return;
+  try {
+    const previous = previews.get(key);
+    if (previous) URL.revokeObjectURL(previous);
+    previews.set(key, URL.createObjectURL(file));
+  } catch {}
+}
+
+export function mediaPreviewFor(path) {
+  return previews.get(normalizePath(path));
+}
+
+// The real committed path for an element, never the display-only blob — used for
+// source writes and for reading a field's value back.
+export function mediaSrcValue(element) {
+  return element?.dataset?.charlescmsMediaPath || element?.getAttribute?.("src") || "";
+}
+
+// Point every <img>/<source> whose committed path has a registered preview at the
+// blob, remembering the real path in a data attribute so reads and serialization
+// keep using the path. Safe to call repeatedly (idempotent).
+export function applyMediaPreviews(root = document) {
+  if (!previews.size || !root?.querySelectorAll) return;
+  for (const node of root.querySelectorAll("img, source")) {
+    const path = normalizePath(node.dataset.charlescmsMediaPath || node.getAttribute("src"));
+    const url = previews.get(path);
+    if (url && node.getAttribute("src") !== url) {
+      node.dataset.charlescmsMediaPath = path;
+      node.setAttribute("src", url);
+    }
+  }
+}

package/src/panel-manager.js

@@ -0,0 +1,133 @@
+// Owns the lifecycle and viewport placement of floating editor panels.
+//
+// Feature modules only create panel markup and call `mountPanel`. This module
+// centralizes cleanup, resize/scroll listeners, mobile placement, and the rule
+// that a panel should avoid covering the element being edited.
+export function createPanelManager({ state }) {
+  function closeEditor() {
+    // Inline editors provide their own finish function because they temporarily
+    // replace page content instead of mounting a separate panel.
+    if (state.active?.inline) {
+      state.active.finish(false);
+      return;
+    }
+    state.active?.cleanup?.();
+    state.active?.dialog?.remove();
+    state.active = null;
+  }
+
+  function mountPanel(dialog, { item = null } = {}) {
+    document.body.append(dialog);
+    const anchor = item?.element || null;
+    const position = () => positionPanel(dialog, anchor);
+    const observer = new ResizeObserver(position);
+    observer.observe(dialog);
+    window.addEventListener("resize", position);
+    window.addEventListener("scroll", position, true);
+    // Enter confirms the panel — a single keystroke to save, like any form. In a
+    // multi-line textarea, plain Enter still inserts a newline; Cmd/Ctrl+Enter
+    // saves there. Escape closes (handled by the panel's own Cancel/×).
+    const onKeydown = (event) => {
+      if (event.key !== "Enter" || event.isComposing) return;
+      if (event.target?.tagName === "BUTTON") return;
+      if (event.target?.tagName === "TEXTAREA" && !(event.metaKey || event.ctrlKey)) return;
+      const save = dialog.querySelector("[data-save], [data-save-section], [data-draft-save]");
+      if (save && !save.disabled) { event.preventDefault(); save.click(); }
+    };
+    dialog.addEventListener("keydown", onKeydown);
+    requestAnimationFrame(() => {
+      position();
+      if (anchor) keepAnchorVisible(anchor, dialog);
+    });
+    state.active = {
+      dialog,
+      item,
+      cleanup() {
+        observer.disconnect();
+        window.removeEventListener("resize", position);
+        window.removeEventListener("scroll", position, true);
+      }
+    };
+  }
+
+  function positionPanel(dialog, anchor) {
+    const viewport = { width: window.innerWidth, height: window.innerHeight };
+    const toolbarTop = state.toolbar?.getBoundingClientRect().top || viewport.height;
+    const margin = viewport.width <= 700 ? 12 : 16;
+    const availableBottom = toolbarTop - margin;
+    dialog.style.maxHeight = `${Math.max(220, availableBottom - margin)}px`;
+
+    // Mobile panels use the full safe width above the toolbar.
+    if (viewport.width <= 700) {
+      dialog.style.left = `${margin}px`;
+      dialog.style.right = `${margin}px`;
+      dialog.style.top = "auto";
+      dialog.style.bottom = `${Math.max(margin, viewport.height - toolbarTop + margin)}px`;
+      return;
+    }
+
+    // Utility panels such as Content and Versions have no page anchor. Keep
+    // those predictably docked top-right instead of inheriting mobile geometry.
+    if (!anchor) {
+      dialog.style.left = "auto";
+      dialog.style.right = `${margin}px`;
+      dialog.style.top = `${margin}px`;
+      dialog.style.bottom = "auto";
+      return;
+    }
+
+    // Anchored desktop editors sit beside the selected element and preserve as
+    // much of the live preview as possible.
+    const anchorRect = anchor.getBoundingClientRect();
+    const panelRect = dialog.getBoundingClientRect();
+    const width = panelRect.width;
+    const height = Math.min(panelRect.height, availableBottom - margin);
+    const gap = 16;
+    const clampX = (value) => Math.max(margin, Math.min(value, viewport.width - width - margin));
+    const clampY = (value) => Math.max(margin, Math.min(value, availableBottom - height));
+    const candidates = [
+      { x: anchorRect.right + gap, y: clampY(anchorRect.top) },
+      { x: anchorRect.left - width - gap, y: clampY(anchorRect.top) },
+      { x: clampX(anchorRect.left), y: anchorRect.bottom + gap },
+      { x: clampX(anchorRect.left), y: anchorRect.top - height - gap },
+      { x: viewport.width - width - margin, y: margin },
+      { x: margin, y: margin }
+    ].map(({ x, y }) => ({ x: clampX(x), y: clampY(y) }));
+
+    // Prefer zero overlap, then the shortest visual distance from the anchor.
+    const best = candidates
+      .map((candidate) => ({
+        ...candidate,
+        score: overlapArea(
+          { left: candidate.x, right: candidate.x + width, top: candidate.y, bottom: candidate.y + height },
+          anchorRect
+        ) * 1000 + Math.abs(candidate.x - anchorRect.left) + Math.abs(candidate.y - anchorRect.top)
+      }))
+      .sort((a, b) => a.score - b.score)[0];
+
+    dialog.style.left = `${best.x}px`;
+    dialog.style.right = "auto";
+    dialog.style.top = `${best.y}px`;
+    dialog.style.bottom = "auto";
+  }
+
+  function keepAnchorVisible(anchor, dialog) {
+    if (window.innerWidth > 700) return;
+    const anchorRect = anchor.getBoundingClientRect();
+    const safeTop = 16;
+    const safeBottom = dialog.getBoundingClientRect().top - 16;
+    if (anchorRect.bottom > safeBottom) {
+      window.scrollBy({ top: anchorRect.bottom - safeBottom, behavior: "smooth" });
+    } else if (anchorRect.top < safeTop) {
+      window.scrollBy({ top: anchorRect.top - safeTop, behavior: "smooth" });
+    }
+  }
+
+  return { closeEditor, mountPanel };
+}
+
+function overlapArea(a, b) {
+  const width = Math.max(0, Math.min(a.right, b.right) - Math.max(a.left, b.left));
+  const height = Math.max(0, Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top));
+  return width * height;
+}