@jxsuite/studio 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/studio",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Jx Studio — visual builder for Jx documents",
   "license": "MIT",
   "repository": {
@@ -30,7 +30,7 @@
   "dependencies": {
     "@atlaskit/pragmatic-drag-and-drop": "^1.8.1",
     "@atlaskit/pragmatic-drag-and-drop-hitbox": "^1.1.0",
-    "@jxsuite/runtime": "^0.6.2",
+    "@jxsuite/runtime": "^0.7.0",
     "@spectrum-web-components/accordion": "^1.12.0",
     "@spectrum-web-components/action-bar": "1.12.0",
     "@spectrum-web-components/action-button": "^1.12.0",

package/src/editor/insertion-helper.js

@@ -0,0 +1,301 @@
+/**
+ * Insertion-helper.js — Single floating "+" button for element insertion on the canvas.
+ *
+ * Uses CSS Anchor Positioning to attach to sibling boundaries and empty containers. Uses Native
+ * Observables (Chrome 135+) for declarative event handling.
+ */
+
+import { showSlashMenu } from "./slash-menu.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} ObservableSubscription
+ * @property {(obj: { next: Function }) => void} subscribe - Subscribes to the observable stream.
+ */
+
+/**
+ * @typedef {Object} ObservableElement
+ * @property {(event: string, options?: Object) => ObservableSubscription} on - Creates an
+ *   observable for the given event.
+ */
+
+/**
+ * @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).
+ */
+
+/**
+ * @typedef {Object} InsertionHelperContext
+ * @property {() => any} getState - Returns the current editor state.
+ * @property {(state: any) => void} update - Commits a new state.
+ * @property {() => string} getCanvasMode - Returns the active canvas mode.
+ * @property {(fn: Function) => any} 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 {(s: any, path: any[], idx: number, def: Object) => any} insertNode - Inserts a node
+ *   into the document tree.
+ * @property {(s: any, path: any[]) => any} selectNode - Sets the selection to the given path.
+ * @property {(path: any[]) => any[] | null} parentElementPath - Returns the parent element path, or
+ *   null for root.
+ * @property {(path: any[]) => string | number} childIndex - Returns the child index within the
+ *   parent.
+ * @property {(doc: any, path: any[]) => any} getNodeAtPath - Retrieves the node at a document path.
+ * @property {WeakMap<any, any[]>} elToPath - Maps rendered DOM elements to their document paths.
+ * @property {CanvasPanel} panel - The active canvas panel.
+ */
+
+// ─── State ───────────────────────────────────────────────────────────────────
+
+/** @type {InsertionHelperContext | null} */
+let _ctx = null;
+
+/** @type {HTMLElement | null} */
+let _helper = null;
+
+/** @type {HTMLElement | null} */
+let _currentAnchor = null;
+
+/** @type {{ edge: string; path: any[]; parentPath: any[]; idx: number } | null} */
+let _insertionPoint = null;
+
+/** @type {AbortController | null} */
+let _abort = null;
+
+/** @type {ReturnType<typeof setTimeout> | null} */
+let _hideTimer = null;
+
+// Edge detection threshold in pixels
+const EDGE_THRESHOLD = 14;
+
+// Delay before hiding to allow cursor to reach the button
+const HIDE_DELAY = 300;
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Mount the insertion helper system.
+ *
+ * @param {InsertionHelperContext} ctx
+ */
+export function mount(ctx) {
+  _ctx = ctx;
+  const { panel } = ctx;
+
+  _helper = document.createElement("button");
+  _helper.className = "insertion-helper";
+  _helper.textContent = "+";
+  _helper.addEventListener("click", onHelperClick);
+  _helper.addEventListener("mouseenter", () => {
+    cancelHide();
+  });
+  _helper.addEventListener("mouseleave", () => {
+    scheduleHide();
+  });
+  panel.viewport.appendChild(_helper);
+
+  _abort = new AbortController();
+
+  // Listen on viewport — overlayClk gets pointer-events:none during editing/selection
+  const viewport = /** @type {HTMLElement & ObservableElement} */ (panel.viewport);
+  if (typeof viewport.on === "function") {
+    viewport.on("mousemove", { signal: _abort.signal }).subscribe({ next: onMouseMove });
+    viewport.on("mouseleave", { signal: _abort.signal }).subscribe({ next: hide });
+  } else {
+    panel.viewport.addEventListener("mousemove", onMouseMove, { signal: _abort.signal });
+    panel.viewport.addEventListener("mouseleave", hide, { signal: _abort.signal });
+  }
+}
+
+export function unmount() {
+  _abort?.abort();
+  _abort = null;
+  cancelHide();
+  if (_helper?.parentElement) _helper.remove();
+  clearAnchor();
+  _helper = null;
+  _ctx = null;
+  _insertionPoint = null;
+}
+
+// ─── Detection ───────────────────────────────────────────────────────────────
+
+/** @param {MouseEvent} e */
+function onMouseMove(e) {
+  if (!_ctx || !_helper) return;
+
+  const { getCanvasMode } = _ctx;
+  if (getCanvasMode() !== "design") {
+    hide();
+    return;
+  }
+
+  const { panel, withPanelPointerEvents, elToPath } = _ctx;
+  const el = withPanelPointerEvents(() => document.elementFromPoint(e.clientX, e.clientY));
+
+  if (!el || !panel.canvas.contains(el)) {
+    hide();
+    return;
+  }
+
+  const path = elToPath.get(el);
+  if (!path) {
+    hide();
+    return;
+  }
+
+  // Empty container: show centered "+"
+  if (el.classList.contains("empty-container-placeholder")) {
+    showAt(el, "center", path, path, 0);
+    return;
+  }
+
+  // Root element — can't insert siblings above/below root
+  if (path.length === 0) {
+    hide();
+    return;
+  }
+
+  // Determine layout direction of parent container
+  const parent = el.parentElement;
+  if (!parent) {
+    hide();
+    return;
+  }
+
+  const parentStyle = getComputedStyle(parent);
+  const display = parentStyle.display;
+  const isFlex = display === "flex" || display === "inline-flex";
+  const isGrid = display === "grid" || display === "inline-grid";
+  const isRow =
+    (isFlex && parentStyle.flexDirection.startsWith("row")) ||
+    (isGrid && parentStyle.gridAutoFlow?.startsWith("column"));
+
+  // Calculate relative position within element
+  const rect = el.getBoundingClientRect();
+  const parentPath = _ctx.parentElementPath(path);
+  if (!parentPath) {
+    hide();
+    return;
+  }
+  const childIdx = /** @type {number} */ (_ctx.childIndex(path));
+
+  if (isRow) {
+    const relX = e.clientX - rect.left;
+    if (relX < EDGE_THRESHOLD) {
+      showAt(el, "left", path, parentPath, childIdx);
+    } else if (rect.width - relX < EDGE_THRESHOLD) {
+      showAt(el, "right", path, parentPath, childIdx + 1);
+    } else {
+      hide();
+    }
+  } else {
+    const relY = e.clientY - rect.top;
+    if (relY < EDGE_THRESHOLD) {
+      showAt(el, "top", path, parentPath, childIdx);
+    } else if (rect.height - relY < EDGE_THRESHOLD) {
+      showAt(el, "bottom", path, parentPath, childIdx + 1);
+    } else {
+      hide();
+    }
+  }
+}
+
+// ─── Show / Hide ─────────────────────────────────────────────────────────────
+
+/**
+ * @param {HTMLElement} el
+ * @param {string} edge
+ * @param {any[]} path
+ * @param {any[]} parentPath
+ * @param {number} idx
+ */
+function showAt(el, edge, path, parentPath, idx) {
+  if (!_helper) return;
+
+  // Set CSS anchor on target element
+  if (_currentAnchor !== el) {
+    clearAnchor();
+    el.style.anchorName = "--jx-insert";
+    _currentAnchor = el;
+  }
+
+  _helper.dataset.edge = edge;
+  _helper.classList.add("visible");
+  _insertionPoint = { edge, path, parentPath, idx };
+  cancelHide();
+}
+
+function scheduleHide() {
+  cancelHide();
+  _hideTimer = setTimeout(hideNow, HIDE_DELAY);
+}
+
+function cancelHide() {
+  if (_hideTimer !== null) {
+    clearTimeout(_hideTimer);
+    _hideTimer = null;
+  }
+}
+
+function hide() {
+  scheduleHide();
+}
+
+function hideNow() {
+  _hideTimer = null;
+  if (!_helper) return;
+  _helper.classList.remove("visible");
+  clearAnchor();
+  _insertionPoint = null;
+}
+
+function clearAnchor() {
+  if (_currentAnchor) {
+    _currentAnchor.style.anchorName = "";
+    _currentAnchor = null;
+  }
+}
+
+// ─── Insertion ───────────────────────────────────────────────────────────────
+
+function onHelperClick(/** @type {MouseEvent} */ e) {
+  e.stopPropagation();
+  e.preventDefault();
+
+  if (!_ctx || !_helper || !_insertionPoint) return;
+
+  const captured = _insertionPoint;
+  showSlashMenu(_helper, "", {
+    showFilter: true,
+    onSelect: (cmd) => onSlashSelect(cmd, captured),
+  });
+}
+
+/**
+ * @param {any} cmd
+ * @param {{ edge: string; path: any[]; parentPath: any[]; idx: number }} point
+ */
+function onSlashSelect(cmd, point) {
+  if (!_ctx) return;
+
+  const { getState, update, defaultDef, insertNode, selectNode } = _ctx;
+  const S = getState();
+  const { parentPath, idx, edge } = point;
+
+  const newDef = defaultDef(cmd.tag);
+  const insertPath = edge === "center" ? point.path : parentPath;
+  const insertIdx = edge === "center" ? 0 : idx;
+
+  let s = insertNode(S, insertPath, insertIdx, newDef);
+  const newPath = [...insertPath, "children", insertIdx];
+  s = selectNode(s, newPath);
+  update(s);
+
+  hide();
+}

package/src/editor/slash-menu.js

@@ -34,12 +34,16 @@ const SLASH_COMMANDS = [
 const host = document.createElement("div");
 host.style.display = "contents";
 
-/** @type {{ onSelect: (cmd: any) => void } | null} */
+/** @type {{ onSelect: (cmd: any) => void; showFilter?: boolean } | null} */
 let callbacks = null;
 let activeIdx = 0;
 /** @type {any[]} */
 let filteredItems = [];
 let open = false;
+/** @type {HTMLElement | null} */
+let _anchorEl = null;
+/** @type {DOMRect | null} */
+let _anchorRect = null;
 
 // ─── Public API ───────────────────────────────────────────────────────────────
 
@@ -53,7 +57,7 @@ export function isSlashMenuOpen() {
  *
  * @param {HTMLElement} anchorEl — the element being edited (for positioning)
  * @param {string} filter — current typed filter text (after the "/")
- * @param {{ onSelect: (cmd: any) => void }} cbs
+ * @param {{ onSelect: (cmd: any) => void; showFilter?: boolean }} cbs
  */
 export function showSlashMenu(anchorEl, filter, cbs) {
   // Lazily attach host to sp-theme
@@ -62,6 +66,8 @@ export function showSlashMenu(anchorEl, filter, cbs) {
   }
 
   callbacks = cbs;
+  _anchorEl = anchorEl;
+  _anchorRect = anchorEl.getBoundingClientRect();
 
   filteredItems = filter
     ? SLASH_COMMANDS.filter(
@@ -69,49 +75,28 @@ export function showSlashMenu(anchorEl, filter, cbs) {
       )
     : SLASH_COMMANDS;
 
-  if (!filteredItems.length) {
+  if (!filteredItems.length && !cbs.showFilter) {
     dismissSlashMenu();
     return;
   }
 
   activeIdx = 0;
 
-  const rect = anchorEl.getBoundingClientRect();
-
-  litRender(
-    html`
-      <sp-popover
-        open
-        style="position:fixed;left:${rect.left}px;top:${rect.bottom +
-        4}px;z-index:9999;max-height:280px;overflow-y:auto"
-      >
-        <sp-menu style="min-width:220px">
-          ${filteredItems.map(
-            (cmd, i) => html`
-              <sp-menu-item
-                ?focused=${i === 0}
-                @click=${(/** @type {Event} */ e) => {
-                  e.preventDefault();
-                  e.stopPropagation();
-                  select(cmd);
-                }}
-              >
-                ${cmd.label}
-                ${cmd.description
-                  ? html`<span slot="description">${cmd.description}</span>`
-                  : nothing}
-              </sp-menu-item>
-            `,
-          )}
-        </sp-menu>
-      </sp-popover>
-    `,
-    host,
-  );
+  render(anchorEl, cbs.showFilter || false);
 
   if (!open) {
     open = true;
     document.addEventListener("keydown", onKeydown, true); // capture phase
+    requestAnimationFrame(() => {
+      document.addEventListener("mousedown", onOutsideClick, true);
+    });
+  }
+
+  if (cbs.showFilter) {
+    requestAnimationFrame(() => {
+      const input = /** @type {HTMLInputElement | null} */ (host.querySelector(".slash-filter"));
+      if (input) input.focus();
+    });
   }
 }
 
@@ -119,13 +104,75 @@ export function dismissSlashMenu() {
   if (!open) return;
   open = false;
   callbacks = null;
+  _anchorEl = null;
+  _anchorRect = null;
   filteredItems = [];
   document.removeEventListener("keydown", onKeydown, true);
+  document.removeEventListener("mousedown", onOutsideClick, true);
   litRender(nothing, host);
 }
 
 // ─── Internal ─────────────────────────────────────────────────────────────────
 
+/**
+ * @param {HTMLElement} anchorEl
+ * @param {boolean} showFilter
+ */
+function render(anchorEl, showFilter) {
+  const rect = _anchorRect || anchorEl.getBoundingClientRect();
+
+  litRender(
+    html`
+      <sp-popover
+        open
+        style="position:fixed;left:${rect.left}px;top:${rect.bottom +
+        4}px;z-index:9999;max-height:320px;overflow-y:auto"
+      >
+        ${showFilter
+          ? html`<input
+              class="slash-filter"
+              type="text"
+              placeholder="Filter…"
+              autocomplete="off"
+              style="display:block;width:100%;box-sizing:border-box;padding:6px 10px;border:none;border-bottom:1px solid var(--border, #444);outline:none;font-size:13px;background:transparent;color:inherit"
+              @input=${onFilterInput}
+            />`
+          : nothing}
+        <sp-menu style="min-width:220px">
+          ${filteredItems.length
+            ? filteredItems.map(
+                (cmd, i) => html`
+                  <sp-menu-item
+                    ?focused=${i === 0}
+                    @click=${(/** @type {Event} */ e) => {
+                      e.preventDefault();
+                      e.stopPropagation();
+                      select(cmd);
+                    }}
+                  >
+                    ${cmd.label}
+                    ${cmd.description
+                      ? html`<span slot="description">${cmd.description}</span>`
+                      : nothing}
+                  </sp-menu-item>
+                `,
+              )
+            : html`<sp-menu-item disabled>No matches</sp-menu-item>`}
+        </sp-menu>
+      </sp-popover>
+    `,
+    host,
+  );
+}
+
+/** @param {MouseEvent} e */
+function onOutsideClick(e) {
+  const popover = host.querySelector("sp-popover");
+  if (popover && !popover.contains(/** @type {Node} */ (e.target))) {
+    dismissSlashMenu();
+  }
+}
+
 /** @param {any} cmd */
 function select(cmd) {
   const cbs = callbacks;
@@ -133,16 +180,42 @@ function select(cmd) {
   cbs?.onSelect(cmd);
 }
 
+/** @param {Event} e */
+function onFilterInput(e) {
+  const input = /** @type {HTMLInputElement} */ (e.target);
+  const filter = input.value.toLowerCase();
+
+  filteredItems = filter
+    ? SLASH_COMMANDS.filter(
+        (c) => c.label.toLowerCase().includes(filter) || c.tag.toLowerCase().includes(filter),
+      )
+    : SLASH_COMMANDS;
+
+  activeIdx = 0;
+  if (_anchorEl) render(_anchorEl, true);
+
+  // Re-focus input after re-render
+  requestAnimationFrame(() => {
+    const el = /** @type {HTMLInputElement | null} */ (host.querySelector(".slash-filter"));
+    if (el && el !== document.activeElement) {
+      el.focus();
+      el.selectionStart = el.selectionEnd = el.value.length;
+    }
+  });
+}
+
 /** @param {KeyboardEvent} e */
 function onKeydown(e) {
   if (!open) return;
 
-  const items = /** @type {NodeListOf<Element>} */ (host.querySelectorAll("sp-menu-item"));
-  if (!items.length) return;
+  const items = /** @type {NodeListOf<Element>} */ (
+    host.querySelectorAll("sp-menu-item:not([disabled])")
+  );
 
   if (e.key === "ArrowDown") {
     e.preventDefault();
     e.stopPropagation();
+    if (!items.length) return;
     items[activeIdx]?.removeAttribute("focused");
     activeIdx = (activeIdx + 1) % items.length;
     items[activeIdx]?.setAttribute("focused", "");
@@ -150,6 +223,7 @@ function onKeydown(e) {
   } else if (e.key === "ArrowUp") {
     e.preventDefault();
     e.stopPropagation();
+    if (!items.length) return;
     items[activeIdx]?.removeAttribute("focused");
     activeIdx = (activeIdx - 1 + items.length) % items.length;
     items[activeIdx]?.setAttribute("focused", "");