@jxsuite/studio 0.28.5 → 0.29.0

package/src/editor/context-menu.ts

@@ -97,7 +97,7 @@ async function readFromClipboard() {
     for (const item of items) {
       if (item.types.includes(JX_MIME)) {
         const blob = await item.getType(JX_MIME);
-        const json = JSON.parse(await blob.text());
+        const json = JSON.parse(await blob.text()) as JxNode;
         return [json];
       }
       if (item.types.includes("text/html")) {
@@ -116,7 +116,7 @@ async function readFromClipboard() {
         const text = await blob.text();
         // Try parsing as Jx JSON
         try {
-          const parsed = JSON.parse(text);
+          const parsed = JSON.parse(text) as JxNode;
           if (parsed && parsed.tagName) {
             return [parsed];
           }
@@ -191,14 +191,14 @@ export async function pasteNode() {
     const idx = childIndex(tab.session.selection) as number;
     transactDoc(tab, (t) => {
       for (let i = 0; i < nodes.length; i++) {
-        mutateInsertNode(t, pp, idx + 1 + i, nodes[i]);
+        mutateInsertNode(t, pp, idx + 1 + i, nodes[i]!);
       }
     });
   } else {
     const idx = Array.isArray(parent.children) ? parent.children.length : 0;
     transactDoc(tab, (t) => {
       for (let i = 0; i < nodes.length; i++) {
-        mutateInsertNode(t, pPath, idx + i, nodes[i]);
+        mutateInsertNode(t, pPath, idx + i, nodes[i]!);
       }
     });
   }
@@ -272,16 +272,23 @@ export function showContextMenu(
   // Select the node
   tab.session.selection = path;
 
+  // Index-based structural actions (cut/duplicate/insert/wrap/delete) require a numeric child
+  // Index. Repeater templates (path tail "map") and the document root don't have one — they get
+  // Copy only — so we never splice with a non-numeric index.
+  const idxIsNumber = typeof childIndex(path) === "number";
+
   const items: { label: string; action?: () => void | Promise<void>; danger?: boolean }[] = [
     { action: () => copyNode(), label: "Copy" },
   ];
 
-  if (path.length >= 2) {
-    items.push({ action: () => cutNode(), label: "Cut" });
-    items.push({
-      action: () => transactDoc(activeTab.value, (t) => mutateDuplicateNode(t, path)),
-      label: "Duplicate",
-    });
+  if (path.length >= 2 && idxIsNumber) {
+    items.push(
+      { action: () => cutNode(), label: "Cut" },
+      {
+        action: () => transactDoc(activeTab.value, (t) => mutateDuplicateNode(t, path)),
+        label: "Duplicate",
+      },
+    );
     if (node.style) {
       const nodeStyle = node.style;
       items.push({
@@ -305,33 +312,36 @@ export function showContextMenu(
         label: "Paste styles",
       });
     }
-    items.push({ label: "—" }); // Separator
-    items.push({
-      action: () => {
-        const pp = parentElementPath(path) as JxPath;
-        const idx = childIndex(path) as number;
-        transactDoc(activeTab.value, (t) =>
-          mutateInsertNode(t, pp, idx, { children: [], tagName: "p" }),
-        );
+    // Separator
+    items.push(
+      { label: "—" },
+      {
+        action: () => {
+          const pp = parentElementPath(path) as JxPath;
+          const idx = childIndex(path) as number;
+          transactDoc(activeTab.value, (t) =>
+            mutateInsertNode(t, pp, idx, { children: [], tagName: "p" }),
+          );
+        },
+        label: "Insert before",
       },
-      label: "Insert before",
-    });
-    items.push({
-      action: () => {
-        const pp = parentElementPath(path) as JxPath;
-        const idx = childIndex(path) as number;
-        transactDoc(activeTab.value, (t) =>
-          mutateInsertNode(t, pp, idx + 1, { children: [], tagName: "p" }),
-        );
+      {
+        action: () => {
+          const pp = parentElementPath(path) as JxPath;
+          const idx = childIndex(path) as number;
+          transactDoc(activeTab.value, (t) =>
+            mutateInsertNode(t, pp, idx + 1, { children: [], tagName: "p" }),
+          );
+        },
+        label: "Insert after",
       },
-      label: "Insert after",
-    });
-    items.push({
-      action: () => transactDoc(activeTab.value, (t) => mutateWrapNode(t, path)),
-      label: "Wrap in Div",
-    });
-    // Don't show Repeat if already inside a repeater (path ends with "children", "map")
-    if (!(path.length >= 2 && path.at(-2) === "children" && path.at(-1) === "map")) {
+      {
+        action: () => transactDoc(activeTab.value, (t) => mutateWrapNode(t, path)),
+        label: "Wrap in Div",
+      },
+    );
+    // Don't offer Repeat on a repeater template (path tail "map") or on an array node itself.
+    if (path.at(-1) !== "map" && (node as JxMutableNode).$prototype !== "Array") {
       items.push({
         action: () => convertToRepeater(),
         label: "Repeat...",
@@ -368,48 +378,56 @@ export function showContextMenu(
         });
       }
     }
-    items.push({ label: "—" }); // Separator
-    items.push({
-      action: () => transactDoc(activeTab.value, (t) => mutateRemoveNode(t, path)),
-      danger: true,
-      label: "Delete",
-    });
+    // Separator
+    items.push(
+      { label: "—" },
+      {
+        action: () => transactDoc(activeTab.value, (t) => mutateRemoveNode(t, path)),
+        danger: true,
+        label: "Delete",
+      },
+    );
   }
-  if (path.length >= 2) {
-    items.push({ label: "—" });
-    items.push({
-      action: async () => {
-        const nodes = await readFromClipboard();
-        if (!nodes || nodes.length === 0) {
-          return;
-        }
-        const idx = Array.isArray(node.children) ? node.children.length : 0;
-        transactDoc(activeTab.value, (t) => {
-          for (let i = 0; i < nodes.length; i++) {
-            mutateInsertNode(t, path, idx + i, nodes[i]);
+  // Paste targets — never into/after an array node (its content is the single map template).
+  if (path.length >= 2 && (node as JxMutableNode).$prototype !== "Array") {
+    items.push(
+      { label: "—" },
+      {
+        action: async () => {
+          const nodes = await readFromClipboard();
+          if (!nodes || nodes.length === 0) {
+            return;
           }
-        });
-        statusMessage("Pasted");
+          const idx = Array.isArray(node.children) ? node.children.length : 0;
+          transactDoc(activeTab.value, (t) => {
+            for (let i = 0; i < nodes.length; i++) {
+              mutateInsertNode(t, path, idx + i, nodes[i]!);
+            }
+          });
+          statusMessage("Pasted");
+        },
+        label: "Paste inside",
       },
-      label: "Paste inside",
-    });
-    items.push({
-      action: async () => {
-        const nodes = await readFromClipboard();
-        if (!nodes || nodes.length === 0) {
-          return;
-        }
-        const pp = parentElementPath(path) as JxPath;
-        const idx = childIndex(path) as number;
-        transactDoc(activeTab.value, (t) => {
-          for (let i = 0; i < nodes.length; i++) {
-            mutateInsertNode(t, pp, idx + 1 + i, nodes[i]);
+    );
+    if (idxIsNumber) {
+      items.push({
+        action: async () => {
+          const nodes = await readFromClipboard();
+          if (!nodes || nodes.length === 0) {
+            return;
           }
-        });
-        statusMessage("Pasted");
-      },
-      label: "Paste after",
-    });
+          const pp = parentElementPath(path) as JxPath;
+          const idx = childIndex(path) as number;
+          transactDoc(activeTab.value, (t) => {
+            for (let i = 0; i < nodes.length; i++) {
+              mutateInsertNode(t, pp, idx + 1 + i, nodes[i]!);
+            }
+          });
+          statusMessage("Pasted");
+        },
+        label: "Paste after",
+      });
+    }
   }
 
   let x = e.clientX,
@@ -445,7 +463,7 @@ export function showContextMenu(
                 style=${item.danger ? "color: var(--danger)" : ""}
                 @click=${() => {
                   dismissContextMenu();
-                  item.action?.();
+                  void item.action?.();
                 }}
                 >${item.label}</sp-menu-item
               >`,

package/src/editor/convert-to-component.ts

@@ -8,8 +8,10 @@ import { activeTab } from "../workspace/workspace";
 import { transact } from "../tabs/transact";
 import { componentRegistry, computeRelativePath, loadComponentRegistry } from "../files/components";
 import { getPlatform } from "../platform";
+import { jsonClone } from "../utils/studio-utils";
 import { statusMessage } from "../panels/statusbar";
 import { showDialog } from "../ui/layers";
+import { validateComponentSlots } from "../services/cem-export";
 
 import type { JxMutableNode } from "@jxsuite/schema/types";
 
@@ -75,7 +77,12 @@ export async function convertToComponent() {
     const platform = getPlatform();
     await platform.writeFile(componentFile, JSON.stringify(componentDef, null, 2));
     await loadComponentRegistry();
-    statusMessage(`Converted to <${name}>`);
+    const warning = validateComponentSlots(componentDef);
+    if (warning) {
+      statusMessage(`Converted to <${name}> — Warning: ${warning}`, 6000);
+    } else {
+      statusMessage(`Converted to <${name}>`);
+    }
   } catch (error) {
     statusMessage(`Error saving component: ${errorMessage(error)}`);
   }
@@ -102,7 +109,9 @@ function deriveDefaultName(node: JxMutableNode) {
  * @returns {JxMutableNode}
  */
 function extractComponentDef(node: JxMutableNode) {
-  const clone = structuredClone(node);
+  // JsonClone, not structuredClone: the selected node is a @vue/reactivity proxy,
+  // Which structuredClone rejects with DataCloneError.
+  const clone = jsonClone(node);
   delete clone.$id;
   delete clone.$layout;
   delete clone.$paths;

package/src/editor/convert-to-repeater.ts

@@ -68,10 +68,9 @@ export async function convertToRepeater() {
       repeater.sort = config.sort;
     }
 
-    (parent.children as (string | JxMutableNode)[])[idx] = {
-      children: repeater as unknown as (string | JxMutableNode)[],
-      tagName: "div",
-    };
+    // Replace the selected element in place with the array pseudo-element — no wrapper div. The
+    // Repeated items render directly among the original parent's children.
+    (parent.children as (string | JxMutableNode)[])[idx] = repeater as unknown as JxMutableNode;
   });
 }
 
@@ -111,7 +110,7 @@ async function promptRepeaterConfig(defs: Record<string, unknown>) {
 
   const fnDefs = Object.entries(defs).filter(([, d]) => defCategory(d) === "function");
 
-  let source = arrayDefs.length > 0 ? arrayDefs[0][0] : "__new__";
+  let source = arrayDefs.length > 0 ? arrayDefs[0]![0] : "__new__";
   let newDefName = "";
   let filterDef = "";
   let sortDef = "";

package/src/editor/inline-edit.ts

@@ -522,8 +522,8 @@ function elementToJx(el: HTMLElement): JxContentResult {
   if (nodes.length === 0) {
     return { textContent: "" };
   }
-  if (nodes.length === 1 && nodes[0].nodeType === Node.TEXT_NODE) {
-    return { textContent: nodes[0].textContent };
+  if (nodes.length === 1 && nodes[0]!.nodeType === Node.TEXT_NODE) {
+    return { textContent: nodes[0]!.textContent };
   }
 
   // Mixed content → children array
@@ -589,8 +589,8 @@ function domNodeToJx(node: Node) {
   const { childNodes } = el;
   if (childNodes.length === 0) {
     result.textContent = "";
-  } else if (childNodes.length === 1 && childNodes[0].nodeType === Node.TEXT_NODE) {
-    result.textContent = childNodes[0].textContent;
+  } else if (childNodes.length === 1 && childNodes[0]!.nodeType === Node.TEXT_NODE) {
+    result.textContent = childNodes[0]!.textContent;
   } else {
     result.children = [];
     for (const child of childNodes) {
@@ -615,8 +615,8 @@ function fragmentToJx(frag: DocumentFragment) {
   if (nodes.length === 0) {
     return { textContent: "" };
   }
-  if (nodes.length === 1 && nodes[0].nodeType === Node.TEXT_NODE) {
-    return { textContent: nodes[0].textContent };
+  if (nodes.length === 1 && nodes[0]!.nodeType === Node.TEXT_NODE) {
+    return { textContent: nodes[0]!.textContent };
   }
 
   const children: (JxMutableNode | string)[] = [];
@@ -630,10 +630,10 @@ function fragmentToJx(frag: DocumentFragment) {
   if (
     children.length === 1 &&
     typeof children[0] !== "string" &&
-    children[0].tagName === "span" &&
-    typeof children[0].textContent === "string"
+    children[0]!.tagName === "span" &&
+    typeof children[0]!.textContent === "string"
   ) {
-    return { textContent: children[0].textContent };
+    return { textContent: children[0]!.textContent };
   }
 
   return children.length > 0 ? { children } : { textContent: "" };

package/src/editor/inline-format.ts

@@ -149,14 +149,14 @@ function findIntersectingElements(tag: string, range: Range, root: HTMLElement)
  * @param {Element[]} matches
  */
 function unwrapTagInRange(
-  tag: string,
-  range: Range,
-  editableRoot: HTMLElement,
+  _tag: string,
+  _range: Range,
+  _editableRoot: HTMLElement,
   matches: Element[],
 ) {
   // Process in reverse so DOM mutations don't shift later nodes
   for (let i = matches.length - 1; i >= 0; i--) {
-    const el = matches[i];
+    const el = matches[i]!;
     unwrapElement(el);
   }
 }
@@ -249,7 +249,7 @@ function trimLeadingWhitespace(frag: DocumentFragment) {
   if (!match) {
     return null;
   }
-  const [, ws] = match;
+  const ws = match[1]!;
   if (text.length === ws.length) {
     // Entire node is whitespace — remove it
     first.remove();
@@ -276,7 +276,7 @@ function trimTrailingWhitespace(frag: DocumentFragment) {
   if (!match) {
     return null;
   }
-  const [, ws] = match;
+  const ws = match[1]!;
   if (text.length === ws.length) {
     last.remove();
   } else {
@@ -363,7 +363,7 @@ function mergeAdjacentSiblings(root: HTMLElement) {
 
   // Process in reverse to preserve earlier offsets
   for (let i = toMerge.length - 1; i >= 0; i--) {
-    const [el, next] = toMerge[i];
+    const [el, next] = toMerge[i]!;
     // Move all children from next into el
     while (next.firstChild) {
       el.append(next.firstChild);
@@ -468,8 +468,8 @@ function liftEdgeWhitespace(root: HTMLElement) {
     if (first && first.nodeType === Node.TEXT_NODE) {
       const text = first.textContent ?? "";
       const m = text.match(/^(\s+)/);
-      if (m && text.length > m[1].length) {
-        ops.push({ el, type: "lift-leading", ws: m[1] });
+      if (m && text.length > m[1]!.length) {
+        ops.push({ el, type: "lift-leading", ws: m[1]! });
       }
     }
 
@@ -477,8 +477,8 @@ function liftEdgeWhitespace(root: HTMLElement) {
     if (last && last.nodeType === Node.TEXT_NODE && last !== first) {
       const text = last.textContent ?? "";
       const m = text.match(/(\s+)$/);
-      if (m && text.length > m[1].length) {
-        ops.push({ el, type: "lift-trailing", ws: m[1] });
+      if (m && text.length > m[1]!.length) {
+        ops.push({ el, type: "lift-trailing", ws: m[1]! });
       }
     }
   }

package/src/editor/merge-tags.ts

@@ -0,0 +1,120 @@
+/**
+ * Merge tags — enumerate insertable `${…}` template tokens from the document's state.
+ *
+ * Powers the inline-edit "Insert data" menu (Mailchimp-style merge tags). Given the document's
+ * state definitions plus the live resolved scope, produces a flat list of accessor paths the author
+ * can drop into editable text: top-level `state.*` names, nested object paths, array `.length`, and
+ * — when editing inside a repeater — `item`, `item.*`, and `index`.
+ *
+ * Pure and DOM-free: callers pass the data in, this returns plain descriptors.
+ */
+
+import { defCategory } from "../panels/signals-panel";
+import { dataTypeLabel, unwrapSignal } from "../panels/data-explorer";
+
+export interface MergeTag {
+  /** Insertion token placed between `${` and `}`, e.g. `state.user.name`, `item.title`, `index`. */
+  token: string;
+  /** Display path shown in the menu (currently identical to `token`). */
+  label: string;
+  /** Type + short value preview, e.g. `string · "Alice"`, `Array(4)`, `{3}`. */
+  hint: string;
+  /** Source category — `defCategory` of the root def, or `"repeater"` for item/index entries. */
+  category: string;
+}
+
+/** Levels of nesting walked beneath each root name. */
+const DEPTH_CAP = 3;
+/** Maximum object keys enumerated per level (mirrors the data-explorer tree cap). */
+const BREADTH_CAP = 30;
+
+/** Type label plus a short value preview for primitives. */
+function previewHint(value: unknown): string {
+  const v = unwrapSignal(value);
+  const typeLabel = dataTypeLabel(v);
+  if (v === null || v === undefined || typeof v === "object") {
+    return typeLabel; // Null / pending / Array(n) / {n}
+  }
+  const text =
+    typeof v === "string" ? (v.length > 24 ? `"${v.slice(0, 24)}…"` : `"${v}"`) : String(v);
+  return `${typeLabel} · ${text}`;
+}
+
+/**
+ * Walk a resolved value, appending nested-path tags to `out`. Arrays contribute a `.length` tag and
+ * stop (index access is context-dependent); plain objects recurse up to the depth/breadth caps.
+ */
+function walk(value: unknown, prefix: string, category: string, depth: number, out: MergeTag[]) {
+  if (depth >= DEPTH_CAP) {
+    return;
+  }
+  const v = unwrapSignal(value);
+  if (v === null || v === undefined || typeof v !== "object") {
+    return;
+  }
+  if (Array.isArray(v)) {
+    const token = `${prefix}.length`;
+    out.push({ category, hint: `number · ${v.length}`, label: token, token });
+    return;
+  }
+  const keys = Object.keys(v).slice(0, BREADTH_CAP);
+  for (const key of keys) {
+    if (key.startsWith("$")) {
+      continue; // Internal keys ($children, $ref, reactive plumbing) are not author-facing
+    }
+    const childVal = (v as Record<string, unknown>)[key];
+    const childPrefix = `${prefix}.${key}`;
+    out.push({ category, hint: previewHint(childVal), label: childPrefix, token: childPrefix });
+    walk(childVal, childPrefix, category, depth + 1, out);
+  }
+}
+
+/**
+ * Build the list of insertable merge tags for the current editing context.
+ *
+ * @param state - The document's `state` definitions (`tab.doc.document.state`), used for names and
+ *   classification (functions are skipped — they are not text-insertable values).
+ * @param scope - The live resolved scope (`panel.liveCtx.scope`) for type/preview hints and the
+ *   nested-property walk. May be null before the canvas has rendered.
+ * @param localScope - The editing element's recorded render scope (`elToScope.get(el)`). When it
+ *   carries a `$map` (repeater) context, `item` / `item.*` / `index` tags are appended.
+ */
+export function buildMergeTags(
+  state: Record<string, unknown> | null | undefined,
+  scope: Record<string, unknown> | null | undefined,
+  localScope: Record<string, unknown> | null = null,
+): MergeTag[] {
+  const out: MergeTag[] = [];
+  const defs = state ?? {};
+  const scp = scope ?? {};
+
+  for (const [name, def] of Object.entries(defs)) {
+    if (name.startsWith("$")) {
+      continue;
+    }
+    const category = defCategory(def);
+    if (category === "function") {
+      continue; // Handlers/functions aren't insertable as text values
+    }
+    const value = scp[name];
+    const token = `state.${name}`;
+    out.push({ category, hint: previewHint(value), label: token, token });
+    walk(value, token, category, 0, out);
+  }
+
+  if (localScope) {
+    const map = unwrapSignal(localScope.$map) as { item?: unknown; index?: unknown } | undefined;
+    if (map && typeof map === "object") {
+      out.push({ category: "repeater", hint: previewHint(map.item), label: "item", token: "item" });
+      walk(map.item, "item", "repeater", 0, out);
+      out.push({
+        category: "repeater",
+        hint: previewHint(map.index),
+        label: "index",
+        token: "index",
+      });
+    }
+  }
+
+  return out;
+}

package/src/editor/shortcuts.ts

@@ -183,7 +183,7 @@ export function initShortcuts(
             const tabToClose = workspace.tabs.get(workspace.activeTabId);
             if (tabToClose?.doc.dirty) {
               const name = tabToClose.documentPath?.split("/").pop() || "Untitled";
-              showConfirmDialog(
+              void showConfirmDialog(
                 "Unsaved Changes",
                 `"${name}" has unsaved changes. Close without saving?`,
                 { confirmLabel: "Close", destructive: true },
@@ -232,17 +232,17 @@ export function initShortcuts(
         }
         case "c": {
           e.preventDefault();
-          copyNode();
+          void copyNode();
           break;
         }
         case "x": {
           e.preventDefault();
-          cutNode();
+          void cutNode();
           break;
         }
         case "v": {
           e.preventDefault();
-          pasteNode();
+          void pasteNode();
           break;
         }
         case "0": {

package/src/files/components.ts

@@ -3,6 +3,7 @@
 import { getPlatform } from "../platform";
 import { projectState } from "../store";
 import type { ComponentMeta } from "../types";
+import type { JxMutableNode } from "@jxsuite/schema/types";
 
 /** A discovered component: project components carry a file path; package components may not. */
 export interface ComponentEntry extends Omit<ComponentMeta, "path"> {
@@ -25,6 +26,42 @@ export async function loadComponentRegistry() {
   }
 }
 
+/**
+ * Build a fresh instance definition for a component: $props from prop defaults, plus the
+ * component's slot fallback children cloned in as starting content so editors can edit from the
+ * defaults. Children destined for a named slot carry a `slot` attribute (required for runtime
+ * distribution); fallback for the default slot is inserted as-is. When the component has no slot
+ * fallback, no `children` key is emitted so slotless instances stay atomic in the layers tree.
+ *
+ * @param {ComponentEntry} comp
+ * @returns {JxMutableNode}
+ */
+export function buildComponentInstance(comp: ComponentEntry): JxMutableNode {
+  const $props = Object.fromEntries(
+    (comp.props ?? []).map((p) => [p.name, p.default !== undefined ? p.default : ""]),
+  );
+  const children: (JxMutableNode | string)[] = [];
+  for (const slot of comp.slots ?? []) {
+    for (const child of structuredClone(slot.fallback ?? [])) {
+      if (!slot.name) {
+        children.push(child);
+      } else if (typeof child === "object" && child !== null && typeof child.tagName === "string") {
+        // Preserve an author-set slot attribute (slot forwarding inside fallback).
+        child.attributes = { slot: slot.name, ...child.attributes };
+        children.push(child);
+      } else {
+        // Text and non-element nodes can't carry a slot attribute — wrap them.
+        children.push({ attributes: { slot: slot.name }, children: [child], tagName: "span" });
+      }
+    }
+  }
+  return {
+    $props,
+    tagName: comp.tagName,
+    ...(children.length > 0 ? { children } : {}),
+  };
+}
+
 /**
  * @param {string | null} fromDocPath
  * @param {string} toCompPath