@jxsuite/studio 0.23.2 → 0.25.0

package/src/utils/edit-display.ts

@@ -0,0 +1,298 @@
+/// <reference lib="dom" />
+/**
+ * Edit-mode display transforms — extracted from studio.js (Phase 4i). Pure stateless functions that
+ * convert document trees for visual editing (template expressions, $map, $switch, empty
+ * placeholders).
+ */
+
+import type { JxMutableNode } from "@jxsuite/schema/types";
+
+const mediaTags = new Set(["img", "video", "source", "iframe", "audio"]);
+const TRANSPARENT_PX =
+  "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";
+
+/**
+ * Convert a template string to a displayable expression for edit mode. Replaces ${expr} with ❮ expr
+ * ❯ so the runtime renders it as literal text.
+ *
+ * @param {string} str
+ */
+export function templateToEditDisplay(str: string) {
+  return str.replace(/\$\{([^}]+)\}/g, "\u276A $1 \u276B");
+}
+
+/**
+ * Reverse templateToEditDisplay: walk all text nodes in `el` and replace ❪ expr ❫ back to ${expr}
+ * so the user edits raw template syntax.
+ *
+ * @param {HTMLElement} el
+ */
+export function restoreTemplateExpressions(el: HTMLElement) {
+  const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+  while (walker.nextNode()) {
+    const node = walker.currentNode as Text;
+    if (node.data.includes("\u276A")) {
+      node.data = node.data.replace(/\u276A\s*(.*?)\s*\u276B/g, "${$1}");
+    }
+  }
+}
+
+/**
+ * Prepare a document for edit-mode rendering. Replaces template strings with readable literal text,
+ * $prototype:Array with placeholders, and $ref bindings with display labels. Preserves state so the
+ * runtime can still initialise scope.
+ *
+ * @param {JxMutableNode} node
+ * @returns {JxMutableNode}
+ */
+export function prepareForEditMode(node: JxMutableNode): JxMutableNode {
+  if (!node || typeof node !== "object") return node;
+  if (Array.isArray(node)) return node.map(prepareForEditMode);
+
+  const /** @type {Record<string, unknown>} */ obj = node as Record<string, unknown>;
+
+  const out: Record<string, unknown> = {};
+  let needsMediaPlaceholder = false;
+  const isMediaElement = mediaTags.has((obj.tagName as string) || "");
+
+  // Check if this media element lacks a resolvable src (top-level or in attributes)
+  if (isMediaElement) {
+    const attrs = obj.attributes as Record<string, unknown> | undefined;
+    const topSrc = obj.src;
+    const attrSrc = attrs?.src;
+    const topPoster = obj.poster;
+    const attrPoster = attrs?.poster;
+    const hasSrc = (topSrc && topSrc !== "") || (attrSrc && attrSrc !== "");
+    const hasPoster = (topPoster && topPoster !== "") || (attrPoster && attrPoster !== "");
+    if (!hasSrc && !hasPoster) {
+      needsMediaPlaceholder = true;
+    }
+  }
+
+  for (const [k, v] of Object.entries(obj)) {
+    if (k === "state" || k === "$media" || k === "$elements") {
+      out[k] = v; // preserve as-is for runtime resolution
+    } else if (k === "$props" && v && typeof v === "object") {
+      // Process $props values: convert template strings to display format
+      const propsOut: Record<string, unknown> = {};
+      for (const [pk, pv] of Object.entries(v)) {
+        if (typeof pv === "string" && pv.includes("${")) {
+          const isUrlAttr = pk === "src" || pk === "href" || pk === "poster" || pk === "action";
+          propsOut[pk] = isUrlAttr ? "" : templateToEditDisplay(pv);
+        } else if (pv && typeof pv === "object" && (pv as Record<string, unknown>).$ref) {
+          const ref = (pv as Record<string, unknown>).$ref as string;
+          const label = ref.startsWith("#/state/") ? ref.slice(8) : ref;
+          propsOut[pk] = `{${label}}`;
+        } else {
+          propsOut[pk] = pv;
+        }
+      }
+      out[k] = propsOut;
+    } else if (k === "children") {
+      if (Array.isArray(v)) {
+        out.children = v.map(prepareForEditMode);
+      } else if (
+        v &&
+        typeof v === "object" &&
+        (v as Record<string, unknown>).$prototype === "Array"
+      ) {
+        // Wrap the map template in a visual repeater perimeter
+        const vObj = v as Record<string, unknown>;
+        const template = vObj.map;
+        if (template && typeof template === "object") {
+          out.children = [
+            {
+              tagName: "div",
+              className: "repeater-perimeter",
+              children: [prepareForEditMode(template as JxMutableNode)],
+            },
+          ];
+        } else {
+          out.children = [];
+        }
+      } else {
+        out.children = prepareForEditMode(v as JxMutableNode);
+      }
+    } else if (k === "cases" && obj.$switch && v && typeof v === "object") {
+      // Replace $switch cases with a placeholder showing the first case or a label
+      const caseKeys = Object.keys(v);
+      if (caseKeys.length > 0) {
+        const firstCase = (v as Record<string, unknown>)[caseKeys[0]];
+        if (
+          firstCase &&
+          typeof firstCase === "object" &&
+          !(firstCase as Record<string, unknown>).$ref
+        ) {
+          out.children = [prepareForEditMode(firstCase)];
+        } else {
+          out.children = [
+            {
+              tagName: "div",
+              textContent: `[$switch: ${caseKeys.join(" | ")}]`,
+              style: {
+                fontFamily: "'SF Mono', 'Fira Code', monospace",
+                fontSize: "11px",
+                padding: "6px 10px",
+                background: "color-mix(in srgb, var(--danger) 8%, transparent)",
+                border: "1px dashed color-mix(in srgb, var(--danger) 40%, transparent)",
+                borderRadius: "4px",
+                color: "var(--danger)",
+                fontStyle: "italic",
+              },
+            },
+          ];
+        }
+      }
+    } else if (k === "attributes" && isMediaElement && v && typeof v === "object") {
+      // Process attributes for media elements: replace src/poster with transparent pixel
+      const attrs = v as Record<string, unknown>;
+      const processed: Record<string, unknown> = {};
+      for (const [ak, av] of Object.entries(attrs)) {
+        if (ak === "src" || ak === "poster") {
+          if (typeof av === "string" && av !== "" && !av.includes("${")) {
+            processed[ak] = av;
+          } else {
+            needsMediaPlaceholder = true;
+            processed[ak] = TRANSPARENT_PX;
+          }
+        } else if (typeof av === "string" && av.includes("${")) {
+          const isUrlAttr = ak === "href" || ak === "action";
+          processed[ak] = isUrlAttr ? "" : templateToEditDisplay(av);
+        } else if (av && typeof av === "object" && (av as Record<string, unknown>).$ref) {
+          const ref = (av as Record<string, unknown>).$ref as string;
+          const label = ref.startsWith("#/state/") ? ref.slice(8) : ref;
+          processed[ak] = `{${label}}`;
+        } else {
+          processed[ak] = av;
+        }
+      }
+      out.attributes = processed;
+    } else if (k === "style") {
+      // Replace template strings in style values with empty strings
+      if (v && typeof v === "object") {
+        const s: Record<string, unknown> = {};
+        for (const [sk, sv] of Object.entries(v)) {
+          s[sk] = typeof sv === "string" && sv.includes("${") ? "" : sv;
+        }
+        out.style = s;
+      } else {
+        out.style = v;
+      }
+    } else if (typeof v === "string" && v.includes("${")) {
+      // Template string in a display property → show raw expression
+      const isMediaSrc =
+        (k === "src" || k === "poster") && mediaTags.has((obj.tagName as string) || "");
+      if (isMediaSrc) {
+        needsMediaPlaceholder = true;
+        out[k] = TRANSPARENT_PX;
+      } else {
+        const isUrlAttr = k === "src" || k === "href" || k === "poster" || k === "action";
+        out[k] = isUrlAttr ? "" : templateToEditDisplay(v);
+      }
+    } else if (v && typeof v === "object" && (v as Record<string, unknown>).$ref) {
+      // $ref binding → show ref path as literal text
+      const ref = (v as Record<string, unknown>).$ref as string;
+      const label = ref.startsWith("#/state/") ? ref.slice(8) : ref;
+      const isMediaSrc =
+        (k === "src" || k === "poster") && mediaTags.has((obj.tagName as string) || "");
+      if (isMediaSrc) {
+        needsMediaPlaceholder = true;
+        out[k] = TRANSPARENT_PX;
+      } else {
+        out[k] = `{${label}}`;
+      }
+    } else {
+      // Empty src/poster on media elements → use transparent pixel placeholder
+      if (
+        (k === "src" || k === "poster") &&
+        v === "" &&
+        mediaTags.has((obj.tagName as string) || "")
+      ) {
+        needsMediaPlaceholder = true;
+        out[k] = TRANSPARENT_PX;
+      } else {
+        out[k] = prepareForEditMode(v as JxMutableNode);
+      }
+    }
+  }
+
+  // Mark empty elements with placeholder classes for design-mode visibility
+  if (out.tagName && !out.textContent && !out.innerHTML) {
+    const hasChildren = Array.isArray(out.children) && out.children.length > 0;
+    if (!hasChildren) {
+      const tag = out.tagName as string;
+      const textTags = new Set([
+        "p",
+        "h1",
+        "h2",
+        "h3",
+        "h4",
+        "h5",
+        "h6",
+        "blockquote",
+        "li",
+        "dt",
+        "dd",
+        "th",
+        "td",
+        "span",
+        "strong",
+        "em",
+        "small",
+        "mark",
+        "code",
+        "abbr",
+        "q",
+        "sub",
+        "sup",
+        "time",
+        "a",
+        "button",
+        "label",
+        "legend",
+        "caption",
+        "summary",
+        "pre",
+        "option",
+      ]);
+      const containerTags = new Set([
+        "div",
+        "section",
+        "article",
+        "aside",
+        "header",
+        "footer",
+        "main",
+        "nav",
+        "figure",
+        "figcaption",
+        "details",
+        "fieldset",
+        "form",
+        "ul",
+        "ol",
+        "dl",
+        "table",
+      ]);
+      if (textTags.has(tag)) {
+        out.className = out.className
+          ? out.className + " empty-text-placeholder"
+          : "empty-text-placeholder";
+      } else if (containerTags.has(tag)) {
+        out.className = out.className
+          ? out.className + " empty-container-placeholder"
+          : "empty-container-placeholder";
+      }
+    }
+  }
+
+  // Media elements with missing/dynamic src get a placeholder class
+  if (needsMediaPlaceholder) {
+    const cls = (out.className as string) || "";
+    if (!cls.includes("empty-media-placeholder")) {
+      out.className = cls ? cls + " empty-media-placeholder" : "empty-media-placeholder";
+    }
+  }
+
+  return out;
+}

package/src/utils/{google-fonts.js → google-fonts.ts}

@@ -1,5 +1,7 @@
 /** Google Fonts helpers — shared between head-panel (per-page) and head-editor (project-level). */
 
+import type { JxHeadEntry } from "@jxsuite/schema/types";
+
 export const GFONTS_CSS_PREFIX = "https://fonts.googleapis.com/css2?";
 export const GFONTS_PRECONNECT_ORIGINS = [
   "https://fonts.googleapis.com",
@@ -12,12 +14,12 @@ export const GFONTS_PRECONNECT_ORIGINS = [
  * @param {JxHeadEntry} entry
  * @returns {boolean}
  */
-export function isGoogleFontEntry(entry) {
+export function isGoogleFontEntry(entry: JxHeadEntry) {
   return (
     entry?.tagName === "link" &&
     entry?.attributes?.rel === "stylesheet" &&
     typeof entry?.attributes?.href === "string" &&
-    /** @type {string} */ (entry.attributes.href).startsWith(GFONTS_CSS_PREFIX)
+    (entry.attributes.href as string).startsWith(GFONTS_CSS_PREFIX)
   );
 }
 
@@ -27,11 +29,11 @@ export function isGoogleFontEntry(entry) {
  * @param {JxHeadEntry} entry
  * @returns {boolean}
  */
-export function isGoogleFontPreconnect(entry) {
+export function isGoogleFontPreconnect(entry: JxHeadEntry) {
   return (
     entry?.tagName === "link" &&
     entry?.attributes?.rel === "preconnect" &&
-    GFONTS_PRECONNECT_ORIGINS.includes(/** @type {string} */ (entry?.attributes?.href))
+    GFONTS_PRECONNECT_ORIGINS.includes(entry?.attributes?.href as string)
   );
 }
 
@@ -41,7 +43,7 @@ export function isGoogleFontPreconnect(entry) {
  * @param {string} href
  * @returns {string}
  */
-export function extractFontFamily(href) {
+export function extractFontFamily(href: string) {
   const match = href.match(/family=([^&:]+)/);
   if (!match) return "";
   return decodeURIComponent(match[1].replace(/\+/g, " "));
@@ -53,7 +55,7 @@ export function extractFontFamily(href) {
  * @param {string} family
  * @returns {string}
  */
-export function buildGoogleFontUrl(family) {
+export function buildGoogleFontUrl(family: string) {
   return `${GFONTS_CSS_PREFIX}family=${encodeURIComponent(family).replace(/%20/g, "+")}&display=swap`;
 }
 
@@ -62,17 +64,16 @@ export function buildGoogleFontUrl(family) {
  *
  * @param {JxHeadEntry[]} head
  */
-export function ensureGoogleFontPreconnects(head) {
+export function ensureGoogleFontPreconnects(head: JxHeadEntry[]) {
   for (const origin of GFONTS_PRECONNECT_ORIGINS) {
     const exists = head.some(
-      (/** @type {JxHeadEntry} */ e) =>
+      (e: JxHeadEntry) =>
         e?.tagName === "link" &&
         e?.attributes?.rel === "preconnect" &&
         e?.attributes?.href === origin,
     );
     if (!exists) {
-      /** @type {Record<string, string | boolean>} */
-      const attrs = { rel: "preconnect", href: origin };
+      const attrs: Record<string, string | boolean> = { rel: "preconnect", href: origin };
       if (origin === "https://fonts.gstatic.com") attrs.crossorigin = "";
       head.push({ tagName: "link", attributes: attrs });
     }
@@ -85,10 +86,10 @@ export function ensureGoogleFontPreconnects(head) {
  * @param {JxHeadEntry[]} head
  * @returns {JxHeadEntry[]}
  */
-export function cleanupGoogleFontPreconnects(head) {
-  const hasFont = head.some((/** @type {JxHeadEntry} */ e) => isGoogleFontEntry(e));
+export function cleanupGoogleFontPreconnects(head: JxHeadEntry[]) {
+  const hasFont = head.some((e: JxHeadEntry) => isGoogleFontEntry(e));
   if (!hasFont) {
-    return head.filter((/** @type {JxHeadEntry} */ e) => !isGoogleFontPreconnect(e));
+    return head.filter((e: JxHeadEntry) => !isGoogleFontPreconnect(e));
   }
   return head;
 }

package/src/utils/{inherited-style.js → inherited-style.ts}

@@ -6,6 +6,8 @@
  * on the current tab.
  */
 
+import type { JxStyle } from "@jxsuite/schema/types";
+
 /**
  * Compute the inherited style object for a given breakpoint tab.
  *
@@ -16,35 +18,38 @@
  * @param {string | null} activeSelector — current nested selector, or null
  * @returns {Record<string, string | number>} Inherited style map (prop → value)
  */
-export function computeInheritedStyle(style, mediaNames, activeTab, activeSelector = null) {
+export function computeInheritedStyle(
+  style: JxStyle,
+  mediaNames: string[],
+  activeTab: string | null,
+  activeSelector: string | null = null,
+) {
   if (activeTab === null || mediaNames.length === 0) return {};
 
-  /** @type {Record<string, string | number>} */
-  let inherited = {};
+  let inherited: Record<string, string | number> = {};
 
   if (!activeSelector) {
     // Start with base flat props
     for (const [p, v] of Object.entries(style)) {
-      if (typeof v !== "object") inherited[p] = v ?? "";
+      if (typeof v !== "object") inherited[p] = (v as string | number) ?? "";
     }
     // Layer each media block in order until current tab
     for (const name of mediaNames) {
       if (name === activeTab) break;
-      const block = style[`@${name}`] || {};
+      const block = (style[`@${name}`] || {}) as JxStyle;
       for (const [p, v] of Object.entries(block)) {
-        if (typeof v !== "object") inherited[p] = v ?? "";
+        if (typeof v !== "object") inherited[p] = (v as string | number) ?? "";
       }
     }
   } else {
     // Selector inheritance: base selector → each media's selector block in order
-    const baseSel = style[activeSelector] || {};
+    const baseSel = (style[activeSelector] || {}) as JxStyle;
     for (const [p, v] of Object.entries(baseSel)) {
-      if (typeof v !== "object") inherited[p] = v ?? "";
+      if (typeof v !== "object") inherited[p] = (v as string | number) ?? "";
     }
     for (const name of mediaNames) {
       if (name === activeTab) break;
-      const selBlock =
-        /** @type {Record<string, unknown>} */ (style[`@${name}`] || {})[activeSelector] || {};
+      const selBlock = ((style[`@${name}`] || {}) as Record<string, unknown>)[activeSelector] || {};
       for (const [p, v] of Object.entries(selBlock)) {
         if (typeof v !== "object") inherited[p] = v ?? "";
       }

package/src/utils/{studio-utils.js → studio-utils.ts}

@@ -4,14 +4,16 @@
  * These are all side-effect-free functions used by style/properties/events panels.
  */
 
+import type { ProjectConfig, ContentTypeDef } from "@jxsuite/schema/types";
+
 /**
  * CamelCase → kebab-case for inline style attributes
  *
  * @param {string} str
  * @returns {string}
  */
-export function camelToKebab(str) {
-  return str.replace(/[A-Z]/g, (/** @type {string} */ c) => "-" + c.toLowerCase());
+export function camelToKebab(str: string) {
+  return str.replace(/[A-Z]/g, (c: string) => "-" + c.toLowerCase());
 }
 
 /**
@@ -21,10 +23,14 @@ export function camelToKebab(str) {
  * @param {string} prop
  * @returns {string}
  */
-export function camelToLabel(prop) {
-  return prop
-    .replace(/([A-Z])/g, " $1")
-    .replace(/^./, (/** @type {string} */ c) => c.toUpperCase());
+export function camelToLabel(prop: string) {
+  return prop.replace(/([A-Z])/g, " $1").replace(/^./, (c: string) => c.toUpperCase());
+}
+
+export function toCamelCase(str: string): string {
+  return str
+    .replace(/[^a-zA-Z0-9]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ""))
+    .replace(/^[A-Z]/, (c) => c.toLowerCase());
 }
 
 /**
@@ -34,11 +40,10 @@ export function camelToLabel(prop) {
  * @param {string} val
  * @returns {string}
  */
-export function kebabToLabel(val) {
+export function kebabToLabel(val: string) {
   return val.replace(
     /(^|-)(\w)/g,
-    (/** @type {string} */ _, /** @type {string} */ sep, /** @type {string} */ c) =>
-      (sep ? " " : "") + c.toUpperCase(),
+    (_: string, sep: string, c: string) => (sep ? " " : "") + c.toUpperCase(),
   );
 }
 
@@ -49,7 +54,10 @@ export function kebabToLabel(val) {
  * @param {string} prop
  * @returns {string}
  */
-export function propLabel(entry, prop) {
+export function propLabel(
+  entry: { $label?: string; [key: string]: unknown } | null | undefined,
+  prop: string,
+) {
   return entry?.$label || camelToLabel(prop);
 }
 
@@ -60,13 +68,15 @@ export function propLabel(entry, prop) {
  * @param {string} attr
  * @returns {string}
  */
-export function attrLabel(entry, attr) {
+export function attrLabel(
+  entry: { $label?: string; [key: string]: unknown } | null | undefined,
+  attr: string,
+) {
   if (entry?.$label) return entry.$label;
   if (attr.includes("-"))
     return attr.replace(
       /(^|-)(\w)/g,
-      (/** @type {string} */ _, /** @type {string} */ sep, /** @type {string} */ c) =>
-        (sep ? " " : "") + c.toUpperCase(),
+      (_: string, sep: string, c: string) => (sep ? " " : "") + c.toUpperCase(),
     );
   return camelToLabel(attr);
 }
@@ -77,9 +87,8 @@ export function attrLabel(entry, attr) {
  * @param {string} val
  * @returns {string}
  */
-export function abbreviateValue(val) {
-  /** @type {Record<string, string>} */
-  const map = {
+export function abbreviateValue(val: string) {
+  const map: Record<string, string> = {
     inline: "inl",
     "inline-block": "i-blk",
     "inline-flex": "i-flx",
@@ -109,7 +118,7 @@ export function abbreviateValue(val) {
  * @param {Record<string, unknown>} entry
  * @returns {string}
  */
-export function inferInputType(entry) {
+export function inferInputType(entry: Record<string, unknown>) {
   if (entry.$shorthand === true) return "shorthand";
   if (entry.$input === "button-group") return "button-group";
   if (entry.$input === "media") return "media";
@@ -130,10 +139,13 @@ export function inferInputType(entry) {
  * @param {ProjectConfig | null | undefined} projectConfig — parsed project.json
  * @returns {{ name: string; schema: ContentTypeSchema } | null}
  */
-export function findContentTypeSchema(documentPath, projectConfig) {
+export function findContentTypeSchema(
+  documentPath: string | null,
+  projectConfig: ProjectConfig | null | undefined,
+) {
   if (!documentPath || !projectConfig?.contentTypes) return null;
   for (const [name, def] of Object.entries(
-    /** @type {Record<string, ContentTypeDef>} */ (projectConfig.contentTypes),
+    projectConfig.contentTypes as Record<string, ContentTypeDef>,
   )) {
     if (!def.source || !def.schema) continue;
     const src = def.source.replace(/^\.\//, "").replace(/\/$/, "");
@@ -160,7 +172,7 @@ export function findContentTypeSchema(documentPath, projectConfig) {
  * @param {string} prefix - E.g. "--font-"
  * @returns {string}
  */
-export function friendlyNameToVar(name, prefix) {
+export function friendlyNameToVar(name: string, prefix: string) {
   const slug = name
     .trim()
     .toLowerCase()
@@ -180,13 +192,13 @@ export function friendlyNameToVar(name, prefix) {
  * @param {string} prefix
  * @returns {string}
  */
-export function varDisplayName(varName, prefix) {
+export function varDisplayName(varName: string, prefix: string) {
   return (
     varName
       .replace(new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`), "")
       .replace(/^--/, "")
       .replace(/-/g, " ")
-      .replace(/\b\w/g, (/** @type {string} */ c) => c.toUpperCase()) || varName
+      .replace(/\b\w/g, (c: string) => c.toUpperCase()) || varName
   );
 }
 
@@ -199,7 +211,7 @@ export function varDisplayName(varName, prefix) {
  *   | { kind: "number" }
  *   | { kind: "text" }}
  */
-export function parseCemType(typeText) {
+export function parseCemType(typeText: string | undefined | null) {
   if (!typeText) return { kind: "text" };
   const t = typeText
     .trim()