@jxsuite/studio 6.1.1 → 8.0.0

package/src/editor/inline-edit-apply.ts

@@ -7,7 +7,9 @@
  * boundary.
  */
 
-import { childIndex, getNodeAtPath, parentElementPath } from "../store";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
+import { isNonNullObject, isNumber, isString } from "@jxsuite/schema/guards";
+import { childIndex, parentElementPath } from "../store";
 import { isAncestor } from "../state";
 import { isTabActive } from "../workspace/workspace";
 import {
@@ -18,12 +20,14 @@ import {
   transactDoc,
 } from "../tabs/transact";
 import { defaultDef } from "../panels/shared";
+import { componentInstance, mutateImportComponent } from "./insert-component";
 
 import { contentLength, contentOf, spliceAcross, toStored } from "./content-slice";
 import type { JxContentResult, SlashCommand } from "./inline-edit";
 import type { JxPath } from "../state";
 import type { Tab } from "../tabs/tab";
 import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { SpliceCoordinate } from "../tabs/selection";
 
 /**
  * Whether a committed inline-edit result is effectively empty (blank text / lone whitespace /
@@ -43,10 +47,21 @@ export function isEmptyContent(commitData?: JxContentResult): boolean {
   if (kids.length === 0) {
     return true;
   }
-  if (kids.length === 1 && typeof kids[0] === "string" && kids[0].trim() === "") {
+  const [only] = kids;
+  if (kids.length === 1 && isString(only) && only.trim() === "") {
     return true;
   }
-  return kids.length === 1 && typeof kids[0] === "object" && kids[0]?.tagName === "br";
+  // The result crossed the frame boundary as JSON, so a `null` child is excluded here explicitly.
+  return kids.length === 1 && isNonNullObject(only) && only.tagName === "br";
+}
+
+/** The slot of the block at `path`. */
+function blockSlot(path: JxPath): SpliceCoordinate {
+  /* SAFETY: a block with a sibling position has an element path ending in `"children", <index>`, so
+     it has a parent element path and its last segment is the numeric child index. A repeater's
+     template root (`…, "map"`) is editable too; callers do not exclude that case yet, so it reaches
+     here with a string segment exactly as before this cast. */
+  return { index: childIndex(path) as number, parentPath: parentElementPath(path) as JxPath };
 }
 
 /**
@@ -126,7 +141,7 @@ export function applyInlinePropCommit(
   if (!node) {
     return false;
   }
-  const current = (node.$props as Record<string, unknown> | undefined)?.[prop];
+  const current = node.$props?.[prop];
   if (`${current ?? ""}` === value) {
     return false;
   }
@@ -155,8 +170,8 @@ export function applyBlockMerge(
   if (!tab) {
     return null;
   }
-  const from = getNodeAtPath(tab.doc.document, fromPath) as JxMutableNode | undefined;
-  const into = getNodeAtPath(tab.doc.document, intoPath) as JxMutableNode | undefined;
+  const from = getNodeAtPath(tab.doc.document, fromPath);
+  const into = getNodeAtPath(tab.doc.document, intoPath);
   if (!from || !into) {
     return null;
   }
@@ -184,8 +199,11 @@ export function applyBlockMerge(
       mutateUpdateProperty(t, intoPath, "textContent", merged.textContent ?? "");
     }
     mutateRemoveNode(t, fromPath);
-    // A container emptied by the removal (the `<ul>` behind a list's last item) would otherwise
-    // Linger as invisible structure that still occupies layout and shows up in the layers panel.
+    /* A container emptied by the removal (the `<ul>` behind a list's last item) would otherwise
+       linger as invisible structure that still occupies layout and shows up in the layers panel.
+       SAFETY: `fromPath` is not the root (the ancestor check above refuses `[]`), and any node below
+       the root is addressed by at least two segments (`"children", <index>`, `"cases", <name>`, or
+       `"map"` under its repeater), so parentElementPath returns a path. */
     pruneEmptyAncestors(t, parentElementPath(fromPath) as JxPath);
     if (isTabActive(tab)) {
       t.session.selection = [intoPath];
@@ -202,12 +220,12 @@ export function applyBlockMerge(
 function pruneEmptyAncestors(tab: Tab, path: JxPath): void {
   let cur = path;
   while (cur.length > 0) {
-    const node = getNodeAtPath(tab.doc.document, cur) as JxMutableNode | undefined;
+    const node = getNodeAtPath(tab.doc.document, cur);
     const kids = node?.children;
     if (!node || !Array.isArray(kids) || kids.length > 0) {
       return;
     }
-    const parent = parentElementPath(cur) as JxPath | null;
+    const parent = parentElementPath(cur);
     mutateRemoveNode(tab, cur);
     if (!parent) {
       return;
@@ -227,8 +245,7 @@ export function applyInlineSplit(
   before: JxContentResult,
   after: JxContentResult,
 ): JxPath {
-  const parentPath = parentElementPath(path) as JxPath;
-  const idx = childIndex(path) as number;
+  const { parentPath, index: idx } = blockSlot(path);
   const newPath = [...parentPath, "children", idx + 1];
   if (!tab) {
     return newPath;
@@ -260,6 +277,45 @@ export function applyInlineSplit(
   return newPath;
 }
 
+/**
+ * A slash pick from the Components group (§5.7): the empty block the "/" was typed in is REPLACED
+ * by an instance of the component, and a block with content keeps it and gets the instance after
+ * it. Either way the component is imported, as a drop of the same component would import it. An
+ * instance is a whole element with its own `$props` and slot content, so swapping a tag in place —
+ * what an HTML pick does — would leave a paragraph's leftovers inside a component.
+ */
+function insertComponentBlock(
+  tab: Tab | null,
+  path: JxPath,
+  instance: JxMutableNode,
+  commitData: JxContentResult | undefined,
+): JxPath {
+  const { parentPath, index: idx } = blockSlot(path);
+  const replace = isEmptyContent(commitData);
+  const at = replace ? idx : idx + 1;
+  const newPath = [...parentPath, "children", at];
+  if (!tab) {
+    return newPath;
+  }
+  transactDoc(tab, (t) => {
+    if (replace) {
+      mutateRemoveNode(t, path);
+    } else if (commitData?.children) {
+      mutateUpdateProperty(t, path, "textContent");
+      mutateUpdateProperty(t, path, "children", commitData.children);
+    } else if (commitData?.textContent != null) {
+      mutateUpdateProperty(t, path, "children");
+      mutateUpdateProperty(t, path, "textContent", commitData.textContent);
+    }
+    mutateInsertNode(t, parentPath, at, instance);
+    mutateImportComponent(t, instance.tagName);
+    if (isTabActive(tab)) {
+      t.session.selection = [newPath];
+    }
+  });
+  return newPath;
+}
+
 /**
  * Apply a slash-insert at `path` of `tab`'s document: swap the (empty) node's tag in place, or
  * commit pending content and insert a new element after it. Returns the path to edit next (the
@@ -271,6 +327,10 @@ export function applyInlineInsert(
   cmd: SlashCommand,
   commitData: JxContentResult | undefined,
 ): JxPath {
+  const instance = cmd.component === true ? componentInstance(cmd.tag) : null;
+  if (instance) {
+    return insertComponentBlock(tab, path, instance, commitData);
+  }
   if (isEmptyContent(commitData)) {
     if (!tab) {
       return path;
@@ -291,8 +351,7 @@ export function applyInlineInsert(
     return path;
   }
 
-  const parentPath = parentElementPath(path) as JxPath;
-  const idx = childIndex(path) as number;
+  const { parentPath, index: idx } = blockSlot(path);
   const newPath = [...parentPath, "children", idx + 1];
   if (!tab) {
     return newPath;
@@ -336,8 +395,8 @@ export function applyRangeReplace(
   if (!tab) {
     return null;
   }
-  const head = getNodeAtPath(tab.doc.document, from.path) as JxMutableNode | undefined;
-  const tail = getNodeAtPath(tab.doc.document, to.path) as JxMutableNode | undefined;
+  const head = getNodeAtPath(tab.doc.document, from.path);
+  const tail = getNodeAtPath(tab.doc.document, to.path);
   if (!head || !tail) {
     return null;
   }
@@ -366,6 +425,9 @@ export function applyRangeReplace(
     for (const path of removals) {
       if (getNodeAtPath(t.doc.document, path)) {
         mutateRemoveNode(t, path);
+        /* SAFETY: every removal is the range's tail or a rendered block the iframe named between its
+           ends; none is the root, which contains both ends, and any node below the root is
+           addressed by at least two segments, so parentElementPath returns a path. */
         pruneEmptyAncestors(t, parentElementPath(path) as JxPath);
       }
     }
@@ -389,7 +451,7 @@ function comparePathsDescending(a: JxPath, b: JxPath): number {
     if (av === bv) {
       continue;
     }
-    if (typeof av === "number" && typeof bv === "number") {
+    if (isNumber(av) && isNumber(bv)) {
       return bv - av;
     }
     return String(bv).localeCompare(String(av));

package/src/editor/inline-edit.ts

@@ -7,13 +7,13 @@
  * text formatting, Enter for new paragraphs, and slash commands for inserting elements.
  */
 
-import elementsMeta from "../../data/elements-meta.json";
-import { displayTagName } from "@jxsuite/schema/guards";
+import { displayTagName, isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { normalizeInlineContent } from "./inline-format";
-import { isEditableTag } from "./editable-tags";
+import { execEditingCommand } from "./inline-link";
+import { ELEMENT_DEFS, isEditableTag } from "./editable-tags";
 import type { EditableVerdicts } from "./editable-tags";
 import type { JxPath } from "../state";
-import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { JsonPrimitive, JxMutableNode } from "@jxsuite/schema/types";
 
 /**
  * The slash-menu surface inline editing drives. Injected (rather than imported) so this module
@@ -21,12 +21,15 @@ import type { JxMutableNode } from "@jxsuite/schema/types";
  * real menu, the canvas iframe supplies its own (or a no-op) without bloating the slim iframe
  * bundle.
  */
+/** What a slash menu is opened with: the pick handler, and how the list is filtered and sourced. */
+export interface SlashMenuOptions {
+  onSelect: (cmd: SlashCommand) => void;
+  showFilter?: boolean;
+  commands?: SlashCommand[];
+}
+
 export interface SlashController {
-  show: (
-    anchorEl: HTMLElement,
-    filter: string,
-    cbs: { onSelect: (cmd: SlashCommand) => void; showFilter?: boolean; commands?: SlashCommand[] },
-  ) => void;
+  show: (anchorEl: HTMLElement, filter: string, cbs: SlashMenuOptions) => void;
   dismiss: () => void;
   isOpen: () => boolean;
 }
@@ -74,15 +77,20 @@ export interface InlineAction {
   shortcut?: string;
 }
 
-interface ElementDef {
-  $inlineChildren?: string[];
-  $inlineActions?: InlineAction[] | string;
-}
-
 export interface SlashCommand {
   label: string;
   tag: string;
   description: string;
+  /**
+   * The heading the offer is listed under. Absent for the HTML elements, which are the menu's
+   * first, unheaded group; `"Components"` for the project's components (§5.7).
+   */
+  group?: string;
+  /**
+   * Whether `tag` names a project component: the pick inserts `buildComponentInstance` and imports
+   * the component (`editor/insert-component.ts`) rather than an element's default definition.
+   */
+  component?: boolean;
 }
 
 export interface JxContentResult {
@@ -124,7 +132,7 @@ export function isInlineInContext(childTag: string, parentTag: string) {
   if (!parentTag) {
     return INLINE_TAGS.has(childTag);
   }
-  const parentDef = (elementsMeta.$defs as Record<string, ElementDef>)[parentTag];
+  const parentDef = ELEMENT_DEFS[parentTag];
   if (!parentDef || !parentDef.$inlineChildren) {
     return false;
   }
@@ -139,13 +147,13 @@ export function isInlineInContext(childTag: string, parentTag: string) {
  * @returns {InlineAction[] | null}
  */
 export function getInlineActions(tag: string) {
-  const def = (elementsMeta.$defs as Record<string, ElementDef>)[tag];
+  const def = ELEMENT_DEFS[tag];
   if (!def) {
     return null;
   }
   let actions = def.$inlineActions;
-  if (typeof actions === "string") {
-    const refDef = (elementsMeta.$defs as Record<string, ElementDef>)[actions];
+  if (isString(actions)) {
+    const refDef = ELEMENT_DEFS[actions];
     actions = refDef?.$inlineActions ?? undefined;
   }
   if (!Array.isArray(actions)) {
@@ -233,12 +241,13 @@ export function isEditableBlock(el: HTMLElement) {
  * Check if a node is an inline child. When parentNode is provided, uses context-aware scoping from
  * metadata. Without parent, uses the fallback INLINE_TAGS set.
  *
- * @param {JxMutableNode} node
+ * @param {JxMutableNode | JsonPrimitive} node A document child entry; a text or other scalar child
+ *   is never an inline element.
  * @param {JxMutableNode} [parentNode]
  * @returns {boolean}
  */
-export function isInlineElement(node: JxMutableNode, parentNode?: JxMutableNode) {
-  if (!node || typeof node !== "object") {
+export function isInlineElement(node: JxMutableNode | JsonPrimitive, parentNode?: JxMutableNode) {
+  if (!isNonNullObject(node)) {
     return false;
   }
   const childTag = (displayTagName(node.tagName) || "div").toLowerCase();
@@ -304,7 +313,7 @@ export function startEditing(
   insertFn = callbacks.onInsert;
   endFn = callbacks.onEnd;
   _plainMode = opts?.plainText === true;
-  _plainOriginal = _plainMode ? (el.textContent ?? "") : "";
+  _plainOriginal = _plainMode ? el.textContent : "";
   _plainPosted = false;
 
   // Mark the caret's block so the empty-block slash hint can target it. The editing host itself is
@@ -495,7 +504,7 @@ function handlePaste(e: ClipboardEvent) {
   e.preventDefault();
   // Paste as plain text to avoid foreign HTML
   const text = e.clipboardData?.getData("text/plain") ?? "";
-  document.execCommand("insertText", false, text);
+  execEditingCommand("insertText", text);
 }
 
 // ─── Enter: split the active block ─────────────────────────────────────────
@@ -594,7 +603,7 @@ function commitChanges(inPlace: boolean) {
   if (_plainMode) {
     // A prop value is a plain single-line string (a directive attribute) — flatten any newline
     // That survived plaintext editing and skip the rich DOM→Jx serialization entirely.
-    const text = (activeEl.textContent ?? "").replaceAll("\n", " ");
+    const text = activeEl.textContent.replaceAll("\n", " ");
     /*
      * A SESSION THAT CHANGED NOTHING MUST WRITE NOTHING.
      *
@@ -635,17 +644,18 @@ export function normalizeChildren(node: { children?: (JxMutableNode | string)[]
   }
 
   // Step 1: Merge adjacent text nodes
-  const merged = [];
+  const merged: (JxMutableNode | string)[] = [];
   for (const child of node.children) {
-    if (typeof child === "string" && merged.length > 0 && typeof merged.at(-1) === "string") {
-      merged[merged.length - 1] += child;
+    const last = merged.at(-1);
+    if (isString(child) && isString(last)) {
+      merged[merged.length - 1] = last + child;
     } else {
       merged.push(child);
     }
   }
 
   // Step 2: If all children are text, fold into textContent
-  if (merged.every((c: JxMutableNode | string) => typeof c === "string")) {
+  if (merged.every((c) => isString(c))) {
     return { textContent: merged.join("") };
   }
 
@@ -674,7 +684,7 @@ function elementToJx(el: HTMLElement): JxContentResult {
   const children: (JxMutableNode | string)[] = [];
   for (const child of nodes) {
     const jsx = domNodeToJx(child);
-    if (jsx !== null && jsx !== undefined) {
+    if (jsx !== null) {
       children.push(jsx);
     }
   }
@@ -683,6 +693,23 @@ function elementToJx(el: HTMLElement): JxContentResult {
   return normalizeChildren({ children });
 }
 
+/**
+ * Whether `node` is an element carrying `dataset` — an HTML, SVG or MathML element, which is every
+ * element an HTML editing host can hold. Decided by node type and feature, not `instanceof`, so it
+ * holds for a node of any realm.
+ */
+function isDatasetElementNode(node: Node): node is Element & HTMLOrSVGElement {
+  return node.nodeType === Node.ELEMENT_NODE && "dataset" in node;
+}
+
+/** Browser execCommand output tags, mapped to the tags Jx documents use for the same formatting. */
+const BROWSER_TAG_CONVENTIONS = new Map([
+  ["b", "strong"],
+  ["i", "em"],
+  ["s", "del"],
+  ["strike", "del"],
+]);
+
 /**
  * Convert a DOM node to a Jx element definition.
  *
@@ -698,23 +725,17 @@ function domNodeToJx(node: Node) {
     return text; // Bare string — text node child
   }
 
-  if (node.nodeType !== Node.ELEMENT_NODE) {
+  if (!isDatasetElementNode(node)) {
     return null;
   }
 
-  const el = node as HTMLElement;
+  const el = node;
   const tag = el.tagName.toLowerCase();
   const result: JxMutableNode = { tagName: tag };
 
-  // Map browser execCommand output to our tag conventions
-  const tagMap: Record<string, string> = {
-    b: "strong",
-    i: "em",
-    s: "del",
-    strike: "del",
-  };
-  if (tagMap[tag]) {
-    result.tagName = tagMap[tag];
+  const conventional = BROWSER_TAG_CONVENTIONS.get(tag);
+  if (conventional) {
+    result.tagName = conventional;
   }
 
   // Attributes
@@ -725,8 +746,9 @@ function domNodeToJx(node: Node) {
   const href = el.dataset.jxHref ?? el.getAttribute("href");
   if (tag === "a" && href != null) {
     result.attributes = { href };
-    if ((el as HTMLAnchorElement).title) {
-      result.attributes.title = (el as HTMLAnchorElement).title;
+    // `title` is an HTMLElement property: an HTML `<a>` reflects the attribute, an SVG `<a>` has none.
+    if ("title" in el && isString(el.title) && el.title) {
+      result.attributes.title = el.title;
     }
   }
   if (tag === "code") {
@@ -776,13 +798,15 @@ function fragmentToJx(frag: DocumentFragment) {
     }
   }
 
+  const [only] = children;
   if (
     children.length === 1 &&
-    typeof children[0] !== "string" &&
-    children[0]!.tagName === "span" &&
-    typeof children[0]!.textContent === "string"
+    only !== undefined &&
+    !isString(only) &&
+    only.tagName === "span" &&
+    isString(only.textContent)
   ) {
-    return { textContent: children[0]!.textContent };
+    return { textContent: only.textContent };
   }
 
   return children.length > 0 ? { children } : { textContent: "" };
@@ -855,10 +879,11 @@ export function openSlashMenu(opts?: { anchored?: boolean }): void {
 
   // An unanchored menu carries its own filter field: there is no "/…" run in the document for the
   // Author to type into, so without one the list could only ever be filtered by scrolling it.
-  slash.show(activeEl, "", {
-    onSelect: handleSlashSelect,
-    ...(_slashAnchored ? {} : { showFilter: true }),
-  });
+  const menu: SlashMenuOptions = { onSelect: handleSlashSelect };
+  if (!_slashAnchored) {
+    menu.showFilter = true;
+  }
+  slash.show(activeEl, "", menu);
 }
 
 /**
@@ -935,6 +960,7 @@ function handleSlashSelect(cmd: SlashCommand) {
       let slashNode: Text | null = null;
       let slashOffset = 0;
       while (walker.nextNode()) {
+        // SAFETY: the walker shows only text nodes (SHOW_TEXT), and nextNode() just landed on one.
         const node = walker.currentNode as Text;
         if (charCount + node.length > slashIdx) {
           slashNode = node;