@jxsuite/studio 0.23.1 → 0.24.0

package/src/editor/{inline-format.js → inline-format.ts}

@@ -1,3 +1,4 @@
+/// <reference lib="dom" />
 /**
  * Inline-format.js — Inline formatting engine for contenteditable editing
  *
@@ -30,7 +31,7 @@ const FORMAT_TAGS = new Set([
  * @param {HTMLElement | null} editableRoot
  * @returns {boolean}
  */
-export function isTagActiveInSelection(tag, editableRoot) {
+export function isTagActiveInSelection(tag: string, editableRoot: HTMLElement | null) {
   if (!editableRoot) return false;
   if (editableRoot.contentEditable === "plaintext-only") return false;
   const sel = window.getSelection();
@@ -45,12 +46,9 @@ export function isTagActiveInSelection(tag, editableRoot) {
    * @param {Node | null} node
    * @returns {boolean}
    */
-  const hasTag = (node) => {
+  const hasTag = (node: Node | null) => {
     while (node && node !== editableRoot) {
-      if (
-        node.nodeType === Node.ELEMENT_NODE &&
-        /** @type {Element} */ (node).tagName.toLowerCase() === tag
-      )
+      if (node.nodeType === Node.ELEMENT_NODE && (node as Element).tagName.toLowerCase() === tag)
         return true;
       node = node.parentNode;
     }
@@ -67,7 +65,7 @@ export function isTagActiveInSelection(tag, editableRoot) {
  * @param {string} tag
  * @param {HTMLElement | null} editableRoot
  */
-export function toggleInlineFormat(tag, editableRoot) {
+export function toggleInlineFormat(tag: string, editableRoot: HTMLElement | null) {
   if (!editableRoot) return;
   const sel = window.getSelection();
   if (!sel || !sel.rangeCount) return;
@@ -98,26 +96,22 @@ export function toggleInlineFormat(tag, editableRoot) {
  * @param {HTMLElement} root
  * @returns {Element[]}
  */
-function findIntersectingElements(tag, range, root) {
-  /** @type {Element[]} */
-  const matches = [];
+function findIntersectingElements(tag: string, range: Range, root: HTMLElement) {
+  const matches: Element[] = [];
   const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT, {
     /**
      * @param {Node} node
      * @returns {number}
      */
-    acceptNode(node) {
-      if (
-        /** @type {Element} */ (node).tagName.toLowerCase() === tag &&
-        range.intersectsNode(node)
-      ) {
+    acceptNode(node: Node) {
+      if ((node as Element).tagName.toLowerCase() === tag && range.intersectsNode(node)) {
         return NodeFilter.FILTER_ACCEPT;
       }
       return NodeFilter.FILTER_SKIP;
     },
   });
   while (walker.nextNode()) {
-    matches.push(/** @type {Element} */ (walker.currentNode));
+    matches.push(walker.currentNode as Element);
   }
   return matches;
 }
@@ -131,7 +125,12 @@ function findIntersectingElements(tag, range, root) {
  * @param {HTMLElement} editableRoot
  * @param {Element[]} matches
  */
-function unwrapTagInRange(tag, range, editableRoot, matches) {
+function unwrapTagInRange(
+  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];
@@ -144,7 +143,7 @@ function unwrapTagInRange(tag, range, editableRoot, matches) {
  *
  * @param {Element} el
  */
-function unwrapElement(el) {
+function unwrapElement(el: Element) {
   const parent = el.parentNode;
   if (!parent) return;
   const frag = document.createDocumentFragment();
@@ -162,7 +161,7 @@ function unwrapElement(el) {
  * @param {Range} range
  * @param {HTMLElement} _editableRoot
  */
-function wrapRangeInTag(tag, range, _editableRoot) {
+function wrapRangeInTag(tag: string, range: Range, _editableRoot: HTMLElement) {
   const contents = range.extractContents();
 
   // Trim leading whitespace from the fragment
@@ -209,7 +208,7 @@ function wrapRangeInTag(tag, range, _editableRoot) {
  * @param {DocumentFragment} frag
  * @returns {string | null}
  */
-function trimLeadingWhitespace(frag) {
+function trimLeadingWhitespace(frag: DocumentFragment) {
   const first = frag.firstChild;
   if (!first || first.nodeType !== Node.TEXT_NODE) return null;
   const text = first.textContent ?? "";
@@ -232,7 +231,7 @@ function trimLeadingWhitespace(frag) {
  * @param {DocumentFragment} frag
  * @returns {string | null}
  */
-function trimTrailingWhitespace(frag) {
+function trimTrailingWhitespace(frag: DocumentFragment) {
   const last = frag.lastChild;
   if (!last || last.nodeType !== Node.TEXT_NODE) return null;
   const text = last.textContent ?? "";
@@ -256,7 +255,7 @@ function trimTrailingWhitespace(frag) {
  *
  * @param {HTMLElement | null} root
  */
-export function normalizeInlineContent(root) {
+export function normalizeInlineContent(root: HTMLElement | null) {
   if (!root) return;
   let changed = true;
   let iterations = 0;
@@ -291,24 +290,23 @@ export function normalizeInlineContent(root) {
  * @param {HTMLElement} root
  * @returns {boolean}
  */
-function mergeAdjacentSiblings(root) {
+function mergeAdjacentSiblings(root: HTMLElement) {
   let changed = false;
   const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
-  /** @type {[Element, Element][]} */
-  const toMerge = [];
+  const toMerge: [Element, Element][] = [];
 
   // Collect pairs first to avoid mutation during walk
   while (walker.nextNode()) {
-    const el = /** @type {Element} */ (walker.currentNode);
+    const el = walker.currentNode as Element;
     const next = el.nextSibling;
     if (
       next &&
       next.nodeType === Node.ELEMENT_NODE &&
-      /** @type {Element} */ (next).tagName === el.tagName &&
+      (next as Element).tagName === el.tagName &&
       FORMAT_TAGS.has(el.tagName.toLowerCase()) &&
-      attributesMatch(el, /** @type {Element} */ (next))
+      attributesMatch(el, next as Element)
     ) {
-      toMerge.push([el, /** @type {Element} */ (next)]);
+      toMerge.push([el, next as Element]);
     }
   }
 
@@ -332,28 +330,27 @@ function mergeAdjacentSiblings(root) {
  * @param {HTMLElement} root
  * @returns {boolean}
  */
-function collapseRedundantNesting(root) {
+function collapseRedundantNesting(root: HTMLElement) {
   let changed = false;
   const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
-  /** @type {Element[]} */
-  const toCollapse = [];
+  const toCollapse: Element[] = [];
 
   while (walker.nextNode()) {
-    const el = /** @type {Element} */ (walker.currentNode);
+    const el = walker.currentNode as Element;
     if (!FORMAT_TAGS.has(el.tagName.toLowerCase())) continue;
     // Check if only child is an element with the same tag
     if (
       el.childNodes.length === 1 &&
       el.firstChild !== null &&
       el.firstChild.nodeType === Node.ELEMENT_NODE &&
-      /** @type {Element} */ (el.firstChild).tagName === el.tagName
+      (el.firstChild as Element).tagName === el.tagName
     ) {
       toCollapse.push(el);
     }
   }
 
   for (const el of toCollapse) {
-    const inner = /** @type {Element} */ (el.firstChild);
+    const inner = el.firstChild as Element;
     // Replace outer with inner's children
     while (inner.firstChild) {
       el.insertBefore(inner.firstChild, inner);
@@ -370,14 +367,13 @@ function collapseRedundantNesting(root) {
  * @param {HTMLElement} root
  * @returns {boolean}
  */
-function removeEmptyInlines(root) {
+function removeEmptyInlines(root: HTMLElement) {
   let changed = false;
   const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
-  /** @type {Element[]} */
-  const toRemove = [];
+  const toRemove: Element[] = [];
 
   while (walker.nextNode()) {
-    const el = /** @type {Element} */ (walker.currentNode);
+    const el = walker.currentNode as Element;
     if (!FORMAT_TAGS.has(el.tagName.toLowerCase())) continue;
     if (el.childNodes.length === 0 && !el.textContent) {
       toRemove.push(el);
@@ -398,14 +394,14 @@ function removeEmptyInlines(root) {
  * @param {HTMLElement} root
  * @returns {boolean}
  */
-function liftEdgeWhitespace(root) {
+function liftEdgeWhitespace(root: HTMLElement) {
   let changed = false;
   const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
   /** @type {{ type: string; el: Element; ws: string }[]} */
   const ops = [];
 
   while (walker.nextNode()) {
-    const el = /** @type {Element} */ (walker.currentNode);
+    const el = walker.currentNode as Element;
     if (!FORMAT_TAGS.has(el.tagName.toLowerCase())) continue;
     if (el === root) continue;
 
@@ -430,12 +426,12 @@ function liftEdgeWhitespace(root) {
 
   for (const op of ops) {
     if (op.type === "lift-leading") {
-      const firstChild = /** @type {Text} */ (op.el.firstChild);
+      const firstChild = op.el.firstChild as Text;
       firstChild.textContent = (firstChild.textContent ?? "").slice(op.ws.length);
       op.el.parentNode?.insertBefore(document.createTextNode(op.ws), op.el);
       changed = true;
     } else if (op.type === "lift-trailing") {
-      const lastChild = /** @type {Text} */ (op.el.lastChild);
+      const lastChild = op.el.lastChild as Text;
       lastChild.textContent = (lastChild.textContent ?? "").slice(0, -op.ws.length);
       op.el.parentNode?.insertBefore(document.createTextNode(op.ws), op.el.nextSibling);
       changed = true;
@@ -451,14 +447,13 @@ function liftEdgeWhitespace(root) {
  * @param {HTMLElement} root
  * @returns {boolean}
  */
-function unwrapBareSpans(root) {
+function unwrapBareSpans(root: HTMLElement) {
   let changed = false;
   const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
-  /** @type {Element[]} */
-  const toUnwrap = [];
+  const toUnwrap: Element[] = [];
 
   while (walker.nextNode()) {
-    const el = /** @type {Element} */ (walker.currentNode);
+    const el = walker.currentNode as Element;
     if (el.tagName.toLowerCase() !== "span") continue;
     if (el === root) continue;
     // Keep spans with class, style, or any attributes
@@ -481,7 +476,7 @@ function unwrapBareSpans(root) {
  * @param {Element} b
  * @returns {boolean}
  */
-function attributesMatch(a, b) {
+function attributesMatch(a: Element, b: Element) {
   const tag = a.tagName.toLowerCase();
   if (tag === "a") {
     return a.getAttribute("href") === b.getAttribute("href");
@@ -502,7 +497,7 @@ function attributesMatch(a, b) {
  *
  * @param {Range} range
  */
-export function expandRangeToTemplateExpressions(range) {
+export function expandRangeToTemplateExpressions(range: Range) {
   expandBoundary(range, true); // start
   expandBoundary(range, false); // end
 }
@@ -514,7 +509,7 @@ export function expandRangeToTemplateExpressions(range) {
  * @param {Range} range
  * @param {boolean} isStart
  */
-function expandBoundary(range, isStart) {
+function expandBoundary(range: Range, isStart: boolean) {
   const node = isStart ? range.startContainer : range.endContainer;
   const offset = isStart ? range.startOffset : range.endOffset;
   if (node.nodeType !== Node.TEXT_NODE) return;
@@ -546,7 +541,7 @@ function expandBoundary(range, isStart) {
  * @param {string} text
  * @returns {{ start: number; end: number }[]}
  */
-export function findTemplateExpressions(text) {
+export function findTemplateExpressions(text: string) {
   /** @type {{ start: number; end: number }[]} */
   const results = [];
   let i = 0;

package/src/editor/{insertion-helper.js → insertion-helper.ts}

@@ -1,3 +1,4 @@
+/// <reference lib="dom" />
 /**
  * Insertion-helper.js — Single floating "+" button for element insertion on the canvas.
  *
@@ -5,69 +6,49 @@
  * Observables (Chrome 135+) for declarative event handling.
  */
 
-import { showSlashMenu } from "./slash-menu.js";
-import { activeTab } from "../workspace/workspace.js";
-import { transactDoc, mutateInsertNode } from "../tabs/transact.js";
+import { showSlashMenu } from "./slash-menu";
+import { activeTab } from "../workspace/workspace";
+import { transactDoc, mutateInsertNode } from "../tabs/transact";
+import type { CanvasPanel } from "../types";
+import type { JxPath } from "../state";
+import type { JxMutableNode } from "@jxsuite/schema/types";
 
-// ─── Types ────────────────────────────────────────────────────────────────────
-
-/**
- * @typedef {Object} ObservableSubscription
- * @property {(obj: { next: Function }) => void} subscribe - Subscribes to the observable stream.
- */
+interface ObservableSubscription {
+  subscribe(observer: { next: (e: Event) => void }): void;
+  subscribe(observer: { next: (e: MouseEvent) => void }): void;
+}
 
-/**
- * @typedef {Object} ObservableElement
- * @property {(event: string, options?: Object) => ObservableSubscription} on - Creates an
- *   observable for the given event.
- */
+interface ObservableElement {
+  on: (event: string, options?: Record<string, unknown>) => ObservableSubscription;
+}
 
-/**
- * @typedef {Object} CanvasPanel
- * @property {HTMLElement} canvas - The canvas content element.
- * @property {HTMLElement & ObservableElement} overlayClk - The overlay click-capture layer.
- * @property {HTMLElement} overlay - The overlay rendering layer.
- * @property {HTMLElement} viewport - The viewport container (containing block for anchor
- *   positioning).
- */
+interface InsertionHelperContext {
+  getCanvasMode: () => string; // Returns the active canvas mode.
+  withPanelPointerEvents: (fn: () => unknown) => unknown; // Executes fn with pointer-events
+  effectiveZoom: () => number; // Returns the current zoom scale factor.
+  defaultDef: (tag: string) => object; // Creates a default element definition for a tag.
+  parentElementPath: (path: JxPath) => JxPath | null; // Returns the parent element path,
+  childIndex: (path: JxPath) => string | number; // Returns the child index within the
+  getNodeAtPath: (doc: JxMutableNode, path: JxPath) => JxMutableNode | null; // Retrieves
+  elToPath: WeakMap<Element, JxPath>; // Maps rendered DOM elements to their document
+  panel: CanvasPanel; // The active canvas panel.
+}
 
-/**
- * @typedef {Object} InsertionHelperContext
- * @property {() => string} getCanvasMode - Returns the active canvas mode.
- * @property {(fn: Function) => unknown} withPanelPointerEvents - Executes fn with pointer-events
- *   temporarily enabled on the canvas.
- * @property {() => number} effectiveZoom - Returns the current zoom scale factor.
- * @property {(tag: string) => Object} defaultDef - Creates a default element definition for a tag.
- * @property {(path: JxPath) => JxPath | null} parentElementPath - Returns the parent element path,
- *   or null for root.
- * @property {(path: JxPath) => string | number} childIndex - Returns the child index within the
- *   parent.
- * @property {(doc: JxMutableNode, path: JxPath) => JxMutableNode | null} getNodeAtPath - Retrieves
- *   the node at a document path.
- * @property {WeakMap<Element, JxPath>} elToPath - Maps rendered DOM elements to their document
- *   paths.
- * @property {CanvasPanel} panel - The active canvas panel.
- */
+// ─── Types ────────────────────────────────────────────────────────────────────
 
 // ─── State ───────────────────────────────────────────────────────────────────
 
-/** @type {InsertionHelperContext | null} */
-let _ctx = null;
+let _ctx: InsertionHelperContext | null = null;
 
-/** @type {HTMLElement | null} */
-let _helper = null;
+let _helper: HTMLElement | null = null;
 
-/** @type {HTMLElement | null} */
-let _currentAnchor = null;
+let _currentAnchor: HTMLElement | null = null;
 
-/** @type {{ edge: string; path: JxPath; parentPath: JxPath; idx: number } | null} */
-let _insertionPoint = null;
+let _insertionPoint: { edge: string; path: JxPath; parentPath: JxPath; idx: number } | null = null;
 
-/** @type {AbortController | null} */
-let _abort = null;
+let _abort: AbortController | null = null;
 
-/** @type {ReturnType<typeof setTimeout> | null} */
-let _hideTimer = null;
+let _hideTimer: ReturnType<typeof setTimeout> | null = null;
 
 // Edge detection threshold in pixels
 const EDGE_THRESHOLD = 14;
@@ -82,7 +63,7 @@ const HIDE_DELAY = 300;
  *
  * @param {InsertionHelperContext} ctx
  */
-export function mount(ctx) {
+export function mount(ctx: InsertionHelperContext) {
   _ctx = ctx;
   const { panel } = ctx;
 
@@ -101,7 +82,7 @@ export function mount(ctx) {
   _abort = new AbortController();
 
   // Listen on viewport — overlayClk gets pointer-events:none during editing/selection
-  const viewport = /** @type {HTMLElement & ObservableElement} */ (panel.viewport);
+  const viewport = panel.viewport as HTMLElement & ObservableElement;
   if (typeof viewport.on === "function") {
     viewport.on("mousemove", { signal: _abort.signal }).subscribe({ next: onMouseMove });
     viewport.on("mouseleave", { signal: _abort.signal }).subscribe({ next: hide });
@@ -125,7 +106,7 @@ export function unmount() {
 // ─── Detection ───────────────────────────────────────────────────────────────
 
 /** @param {MouseEvent} e */
-function onMouseMove(e) {
+function onMouseMove(e: MouseEvent) {
   if (!_ctx || !_helper) return;
 
   const { getCanvasMode } = _ctx;
@@ -136,9 +117,9 @@ function onMouseMove(e) {
   }
 
   const { panel, withPanelPointerEvents, elToPath } = _ctx;
-  const el = /** @type {HTMLElement | null} */ (
-    withPanelPointerEvents(() => document.elementFromPoint(e.clientX, e.clientY))
-  );
+  const el = withPanelPointerEvents(() =>
+    document.elementFromPoint(e.clientX, e.clientY),
+  ) as HTMLElement | null;
 
   if (!el || !panel.canvas.contains(el)) {
     hide();
@@ -185,7 +166,7 @@ function onMouseMove(e) {
     hide();
     return;
   }
-  const childIdx = /** @type {number} */ (_ctx.childIndex(path));
+  const childIdx = _ctx.childIndex(path) as number;
 
   if (isRow) {
     const relX = e.clientX - rect.left;
@@ -217,13 +198,13 @@ function onMouseMove(e) {
  * @param {JxPath} parentPath
  * @param {number} idx
  */
-function showAt(el, edge, path, parentPath, idx) {
+function showAt(el: HTMLElement, edge: string, path: JxPath, parentPath: JxPath, idx: number) {
   if (!_helper) return;
 
   // Set CSS anchor on target element
   if (_currentAnchor !== el) {
     clearAnchor();
-    /** @type {any} */ (el.style).anchorName = "--jx-insert";
+    (el.style as CSSStyleDeclaration & Record<string, string>).anchorName = "--jx-insert";
     _currentAnchor = el;
   }
 
@@ -259,14 +240,14 @@ function hideNow() {
 
 function clearAnchor() {
   if (_currentAnchor) {
-    /** @type {any} */ (_currentAnchor.style).anchorName = "";
+    (_currentAnchor.style as CSSStyleDeclaration & Record<string, string>).anchorName = "";
     _currentAnchor = null;
   }
 }
 
 // ─── Insertion ───────────────────────────────────────────────────────────────
 
-function onHelperClick(/** @type {MouseEvent} */ e) {
+function onHelperClick(e: MouseEvent) {
   e.stopPropagation();
   e.preventDefault();
 
@@ -283,7 +264,10 @@ function onHelperClick(/** @type {MouseEvent} */ e) {
  * @param {{ label: string; tag: string; description?: string }} cmd
  * @param {{ edge: string; path: JxPath; parentPath: JxPath; idx: number }} point
  */
-function onSlashSelect(cmd, point) {
+function onSlashSelect(
+  cmd: { label: string; tag: string; description?: string },
+  point: { edge: string; path: JxPath; parentPath: JxPath; idx: number },
+) {
   if (!_ctx) return;
 
   const { defaultDef } = _ctx;