@jxsuite/studio 0.33.0 → 0.34.0

package/src/canvas/iframe-interaction.ts

@@ -0,0 +1,176 @@
+/// <reference lib="dom" />
+/**
+ * In-iframe interaction — listens for pointer events inside the canvas iframe, resolves the target
+ * to its nearest `data-jx-path` node, and reports hit (click) / hover (move) to the parent with the
+ * node's iframe-space rect. The parent owns selection + overlay rendering (cross-origin bridge);
+ * the iframe only reports what was pointed at.
+ */
+
+import { parseJxPath, serializeJxPath } from "./path-mapping";
+import { rectOf } from "../utils/geometry";
+import { computeInsertZones, insertZonesKey } from "./iframe-insert";
+import { getActiveElement, isEditing } from "../editor/inline-edit";
+import type { IframeChannel } from "./iframe-channel";
+import type { IframeToParent, NodeHit, ParentToIframe } from "./iframe-protocol";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+
+/** Walk up from an element to the nearest ancestor carrying a `data-jx-path`; null if none. */
+function nearestPathEl(start: Element | null): HTMLElement | null {
+  let el = start instanceof Element ? (start as HTMLElement) : null;
+  while (el) {
+    if (el.dataset?.jxPath) {
+      return el;
+    }
+    el = el.parentElement;
+  }
+  return null;
+}
+
+/** Walk up from an event target to the nearest element carrying a `data-jx-path`; null if none. */
+export function nearestHit(target: EventTarget | null): NodeHit | null {
+  const el = nearestPathEl(target instanceof Element ? target : null);
+  if (!el) {
+    return null;
+  }
+  const r = rectOf(el);
+  return {
+    path: parseJxPath(el.dataset.jxPath as string),
+    rect: { height: r.height, width: r.width, x: r.x, y: r.y },
+  };
+}
+
+/**
+ * Measure the current rect of each requested document path by locating its `data-jx-path` element.
+ * Paths with no matching node are omitted. The serialized path is the same string the renderer
+ * stamps, so a stored selection path round-trips back to its element.
+ */
+export function measureHits(paths: (string | number)[][], doc: Document = document): NodeHit[] {
+  const out: NodeHit[] = [];
+  for (const path of paths) {
+    const serialized = serializeJxPath(path);
+    // Wrap in single quotes (the serialized JSON only ever uses double quotes) and escape the few
+    // Characters that could still break out of an attribute-value selector.
+    const esc = serialized.replaceAll("\\", String.raw`\\`).replaceAll("'", String.raw`\'`);
+    const el = doc.querySelector(`[data-jx-path='${esc}']`);
+    if (el) {
+      const r = rectOf(el);
+      out.push({ path, rect: { height: r.height, width: r.width, x: r.x, y: r.y } });
+    }
+  }
+  return out;
+}
+
+/**
+ * The iframe-side capabilities the interaction wiring needs beyond raw pointer events. Injected
+ * from {@link file://./iframe-entry.ts} (the entry owns the shadow doc), mirroring how
+ * {@link file://./iframe-drop.ts}'s `startGrabDetector` receives its deps rather than reaching for
+ * module state.
+ */
+export interface InteractionDeps {
+  /**
+   * The iframe's current non-reactive shadow doc (path coordinate space), or null before the first
+   * render. Threaded so the insertion-zone computation reads the SAME doc the patch/drag paths
+   * use.
+   */
+  getShadowDoc: () => JxMutableNode | null;
+  /**
+   * The live render's canvas mode. Insertion "+" zones are a document-editing affordance —
+   * suppressed for stylebook renders (specimens aren't insert targets). Absent = permissive.
+   */
+  getMode?: () => string;
+}
+
+/**
+ * Wire pointer listeners on the iframe document and report hit/hover (and, when `deps` is given,
+ * the insertion "+" zones) to the parent. Hover/zones are only reported when they change, to keep
+ * the channel quiet. Returns a teardown function.
+ *
+ * The insertion-zone hook hangs off the SAME pointermove as hover (the cross-origin cousin of the
+ * legacy in-realm insertion-helper mousemove): it resolves the hovered `[data-jx-path]` element and
+ * posts `insertZones` only when the zone set's key changes; `null` is posted on pointerleave and
+ * whenever the cursor sits mid-element (no near-edge zone), so the parent clears any stale "+".
+ */
+export function startInteraction(
+  channel: IframeChannel<IframeToParent, ParentToIframe>,
+  doc: Document = document,
+  deps?: InteractionDeps,
+): () => void {
+  let lastHoverKey: string | null = null;
+  let lastZonesKey: string | null = null;
+
+  const onClick = (e: Event) => {
+    const hit = nearestHit(e.target);
+    if (hit) {
+      channel.post({ hit, kind: "hit" });
+    }
+  };
+
+  const reportHover = (hit: NodeHit | null) => {
+    const key = hit ? JSON.stringify(hit.path) : null;
+    if (key === lastHoverKey) {
+      return;
+    }
+    lastHoverKey = key;
+    channel.post({ hit, kind: "hover" });
+  };
+
+  /** Resolve + post the insertion "+" zones for an iframe-viewport cursor, deduped by key. */
+  const reportInsertZones = (target: EventTarget | null, cursor: { x: number; y: number }) => {
+    if (!deps || deps.getMode?.() === "stylebook") {
+      return;
+    }
+    const shadowDoc = deps.getShadowDoc();
+    const el = nearestPathEl(target instanceof Element ? target : null);
+    const zones = el && shadowDoc ? computeInsertZones(el, cursor, shadowDoc) : null;
+    const key = insertZonesKey(zones);
+    if (key === lastZonesKey) {
+      return;
+    }
+    lastZonesKey = key;
+    channel.post({ kind: "insertZones", zones });
+  };
+
+  const onMove = (e: Event) => {
+    reportHover(nearestHit(e.target));
+    const pe = e as PointerEvent;
+    reportInsertZones(e.target, { x: pe.clientX, y: pe.clientY });
+  };
+  const onLeave = () => {
+    reportHover(null);
+    if (deps && lastZonesKey !== "none") {
+      lastZonesKey = "none";
+      channel.post({ kind: "insertZones", zones: null });
+    }
+  };
+
+  const onContextMenu = (e: Event) => {
+    const me = e as MouseEvent;
+    // Inside the ACTIVE editable keep the NATIVE menu (spellcheck / paste) — the session owns it.
+    const active = isEditing() ? getActiveElement() : null;
+    if (active && e.target instanceof Node && active.contains(e.target)) {
+      return;
+    }
+    // Suppress the browser menu everywhere else (legacy parity — the deleted panel-events handler
+    // PreventDefaulted even with no element hit) and let the parent show the Jx element menu.
+    e.preventDefault();
+    const hit = nearestHit(e.target);
+    channel.post({
+      kind: "contextMenu",
+      path: hit ? hit.path : null,
+      x: me.clientX,
+      y: me.clientY,
+    });
+  };
+
+  doc.addEventListener("click", onClick, true);
+  doc.addEventListener("pointermove", onMove, true);
+  doc.addEventListener("pointerleave", onLeave, true);
+  doc.addEventListener("contextmenu", onContextMenu, true);
+
+  return () => {
+    doc.removeEventListener("click", onClick, true);
+    doc.removeEventListener("pointermove", onMove, true);
+    doc.removeEventListener("pointerleave", onLeave, true);
+    doc.removeEventListener("contextmenu", onContextMenu, true);
+  };
+}

package/src/canvas/iframe-keys.ts

@@ -0,0 +1,85 @@
+/// <reference lib="dom" />
+/**
+ * In-iframe keyboard forwarding. Studio's shortcuts are bound to the EDITOR document, so once focus
+ * moves into the canvas iframe (a click selects a node there) undo/redo/save/delete/duplicate/arrow
+ * navigation stop firing. This captures the global-shortcut subset inside the iframe, prevents the
+ * browser default, and posts a flattened event the parent re-dispatches to its shortcut handler.
+ *
+ * The subset mirrors `editor/shortcuts.ts`: any Ctrl/Cmd combo, plus the bare editing/navigation
+ * keys. Keystrokes while an editable element (input / contenteditable — e.g. a future inline edit)
+ * is focused inside the iframe are left alone so typing still works.
+ */
+
+import { cancelIframeDrag, isDragActive } from "./iframe-drop";
+import type { IframeChannel } from "./iframe-channel";
+import type { IframeToParent, ParentToIframe, SerializedKey } from "./iframe-protocol";
+
+/** Bare (non-modifier) keys the editor's shortcut handler acts on. */
+const BARE_FORWARD_KEYS: ReadonlySet<string> = new Set([
+  "Delete",
+  "Backspace",
+  "Escape",
+  "Enter",
+  "ArrowUp",
+  "ArrowDown",
+  "ArrowLeft",
+  "ArrowRight",
+]);
+
+/** Whether `el` is a text-entry target whose own keystrokes must not be hijacked. */
+function isEditableTarget(el: EventTarget | null): boolean {
+  if (!(el instanceof HTMLElement)) {
+    return false;
+  }
+  if (el.isContentEditable) {
+    return true;
+  }
+  return el.tagName === "INPUT" || el.tagName === "TEXTAREA" || el.tagName === "SELECT";
+}
+
+/** Whether this keydown belongs to the global-shortcut subset the parent handles. */
+export function shouldForwardKey(e: KeyboardEvent): boolean {
+  if (isEditableTarget(e.target)) {
+    return false;
+  }
+  return e.ctrlKey || e.metaKey || BARE_FORWARD_KEYS.has(e.key);
+}
+
+/** Flatten a KeyboardEvent to the structured-cloneable subset the bridge carries. */
+export function serializeKey(e: KeyboardEvent): SerializedKey {
+  return {
+    altKey: e.altKey,
+    code: e.code,
+    ctrlKey: e.ctrlKey,
+    key: e.key,
+    metaKey: e.metaKey,
+    shiftKey: e.shiftKey,
+  };
+}
+
+/**
+ * Listen for global-shortcut keystrokes on the iframe document, prevent their default, and forward
+ * them to the parent. Returns a teardown function.
+ */
+export function startKeyForwarding(
+  channel: IframeChannel<IframeToParent, ParentToIframe>,
+  doc: Document = document,
+): () => void {
+  const onKey = (e: KeyboardEvent) => {
+    // Escape during a flow-3 (iframe-originated) drag cancels locally — the iframe owns cancel for
+    // That case (single-sourced through iframe-drop), so it must NOT also forward Escape to the
+    // Parent (which would tear down via a second path and double-fire).
+    if (e.key === "Escape" && isDragActive()) {
+      e.preventDefault();
+      cancelIframeDrag();
+      return;
+    }
+    if (!shouldForwardKey(e)) {
+      return;
+    }
+    e.preventDefault();
+    channel.post({ event: serializeKey(e), kind: "forwardKey" });
+  };
+  doc.addEventListener("keydown", onKey, true);
+  return () => doc.removeEventListener("keydown", onKey, true);
+}

package/src/canvas/iframe-overlay.ts

@@ -0,0 +1,218 @@
+/// <reference lib="dom" />
+/**
+ * Parent-side canvas overlay layer for the iframe host. Because the cross-origin bridge forbids the
+ * parent from reading the iframe's DOM, selection/hover boxes are drawn from rects the iframe posts
+ * back (see {@link measureHits}/`hover`). This module owns the pure rect→overlay math ({@link
+ * canvasRectToParent}) and a small DOM layer that floats above the iframe, reusing the same
+ * `overlay-box`/`overlay-selection`/`overlay-hover` classes as the legacy canvas for visual
+ * parity.
+ */
+
+import type { SerializableRect } from "./iframe-protocol";
+
+/** An overlay box position in the parent overlay layer's local coordinates. */
+export interface OverlayPlacement {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Map a rect measured in the iframe's own viewport to the parent overlay layer's coordinates. The
+ * overlay layer is positioned exactly over the iframe (same top-left), so the only transform is the
+ * zoom `scale` (applied as a CSS `transform: scale()` on the iframe element, hence a plain multiply
+ * here). Kept pure so the zoom math is unit-tested independently of the DOM.
+ */
+export function canvasRectToParent(rect: SerializableRect, scale = 1): OverlayPlacement {
+  return {
+    height: rect.height * scale,
+    left: rect.x * scale,
+    top: rect.y * scale,
+    width: rect.width * scale,
+  };
+}
+
+/**
+ * Map a parent-viewport cursor (e.g. a pragmatic `location.current.input`, in true post-transform
+ * parent px) into the iframe's own viewport coordinates. The iframe + overlay are descendants of
+ * the scaled `panzoom-wrap`, so the cursor must be DIVIDED by the zoom `scale` (the inverse of the
+ * CSS `transform: scale()` the browser already applied). `iframeRect` is `rectOf(iframe)` (its GBCR
+ * bakes in pan + scale, so subtracting its `left`/`top` cancels the pan offset). Pure, so the
+ * sign/order of the transform is unit-tested independently of the DOM. Empirical `scale` is derived
+ * by the caller as `rectOf(iframe).width / iframe.clientWidth` (NOT `effectiveZoom()` — a separate
+ * path that can desync).
+ */
+export function parentCursorToIframe(
+  cursor: { x: number; y: number },
+  iframeRect: { left: number; top: number },
+  scale = 1,
+): { x: number; y: number } {
+  return {
+    x: (cursor.x - iframeRect.left) / scale,
+    y: (cursor.y - iframeRect.top) / scale,
+  };
+}
+
+/** The geometric side a drop indicator draws on (mirrors {@link DropPreview}'s `edge`). */
+export type DropEdge = "top" | "bottom" | "inside";
+
+/** A floating overlay layer over the iframe that draws a selection box and a hover box. */
+export interface OverlayLayer {
+  /**
+   * Position the selection box (or hide it when `placement` is null). `label` shows a small badge
+   * on the box (stylebook draws the selected tag, e.g. "<p>", via the legacy `.overlay-label` CSS);
+   * omitted/null hides it.
+   */
+  setSelection: (placement: OverlayPlacement | null, label?: string | null) => void;
+  /** Position the hover box (or hide it when `placement` is null). */
+  setHover: (placement: OverlayPlacement | null) => void;
+  /**
+   * Draw the drop indicator for a drag-over (Phase 4c). `placement` is the reference node's rect in
+   * overlay-local coords (the caller maps the iframe-space `referenceRect` via
+   * {@link canvasRectToParent} at scale=1 — the overlay is INSIDE the scaled panzoom-wrap, so the
+   * browser already scales it; multiplying by zoom would double-scale, D-2). `edge` "inside" → a
+   * dashed box over the reference; "top"/"bottom" → a thin line at the reference's top/bottom edge.
+   * Pass null to hide.
+   */
+  setDropIndicator: (placement: OverlayPlacement | null, edge?: DropEdge) => void;
+  /**
+   * Position the clickable insertion "+" at `placement` (overlay-local coords, mapped via
+   * {@link canvasRectToParent} at scale=1 like the drop indicator, D-2), centered on the anchor box
+   * and tagged with `edge` (for the `[data-edge]` styling). Pass null to hide it. This is the ONE
+   * element on the otherwise `pointer-events:none` overlay that captures pointer events, so the
+   * author can actually click it; the caller wires its click/mouseenter/mouseleave via
+   * {@link insertButton}.
+   */
+  setInsertZone: (placement: OverlayPlacement | null, edge?: InsertButtonEdge) => void;
+  /** The clickable "+" button, so the caller can attach click + hover (grace-timer) listeners. */
+  readonly insertButton: HTMLButtonElement;
+  /** The layer root element (caller appends it over the iframe). */
+  readonly root: HTMLElement;
+  /** Remove the layer from the DOM. */
+  dispose: () => void;
+}
+
+/** The geometric side the insertion "+" anchors to (mirrors {@link InsertZone}'s `edge`). */
+export type InsertButtonEdge = "top" | "bottom" | "left" | "right" | "center";
+
+function place(box: HTMLElement, placement: OverlayPlacement | null): void {
+  if (!placement) {
+    box.style.display = "none";
+    return;
+  }
+  box.style.display = "block";
+  box.style.left = `${placement.left}px`;
+  box.style.top = `${placement.top}px`;
+  box.style.width = `${placement.width}px`;
+  box.style.height = `${placement.height}px`;
+}
+
+/** Build (but do not mount) an overlay layer with hidden selection + hover boxes. */
+export function createOverlayLayer(doc: Document = document): OverlayLayer {
+  const root = doc.createElement("div");
+  root.className = "jx-canvas-iframe-overlay";
+  // Float over the iframe without intercepting pointer events (the iframe handles its own hit-test).
+  root.style.cssText = "position:absolute;inset:0;pointer-events:none;overflow:hidden;z-index:2";
+
+  const selectionBox = doc.createElement("div");
+  selectionBox.className = "overlay-box overlay-selection";
+  selectionBox.style.display = "none";
+
+  const selectionLabel = doc.createElement("div");
+  selectionLabel.className = "overlay-label";
+  selectionLabel.style.display = "none";
+  selectionBox.append(selectionLabel);
+
+  const hoverBox = doc.createElement("div");
+  hoverBox.className = "overlay-box overlay-hover";
+  hoverBox.style.display = "none";
+
+  // Reuses the legacy `.canvas-drop-indicator` CSS (`.line` = thin bar, `.inside` = dashed box).
+  const dropBox = doc.createElement("div");
+  dropBox.className = "canvas-drop-indicator";
+  dropBox.style.display = "none";
+
+  // The clickable insertion "+" — reuses the legacy `.insertion-helper` circle styling. It is the
+  // ONE element on the `pointer-events:none` overlay that re-enables pointer events, so the author
+  // Can click it (the legacy CSS-anchor positioning rules are inert here — no `position-anchor` is
+  // Set — so it is positioned explicitly via left/top by placeInsertButton).
+  const insertButton = doc.createElement("button");
+  insertButton.className = "insertion-helper";
+  insertButton.textContent = "+";
+  insertButton.style.pointerEvents = "auto";
+  insertButton.style.display = "none";
+
+  root.append(hoverBox, selectionBox, dropBox, insertButton);
+
+  return {
+    dispose: () => root.remove(),
+    insertButton,
+    root,
+    setDropIndicator: (placement, edge = "inside") => placeDropIndicator(dropBox, placement, edge),
+    setHover: (placement) => place(hoverBox, placement),
+    setInsertZone: (placement, edge = "center") => placeInsertButton(insertButton, placement, edge),
+    setSelection: (placement, label = null) => {
+      place(selectionBox, placement);
+      if (placement && label) {
+        selectionLabel.textContent = label;
+        selectionLabel.style.display = "block";
+      } else {
+        selectionLabel.style.display = "none";
+      }
+    },
+  };
+}
+
+/**
+ * Position the insertion "+" centered on the anchor `placement` (a zero-thickness edge box from the
+ * iframe), or hide it when null. Sets `data-edge` for the `[data-edge]` styling and toggles the
+ * `visible` class the legacy CSS uses (display + opacity). Explicit left/top centering replaces the
+ * legacy CSS-anchor positioning, which can't reach across the iframe boundary.
+ */
+function placeInsertButton(
+  btn: HTMLButtonElement,
+  placement: OverlayPlacement | null,
+  edge: InsertButtonEdge,
+): void {
+  if (!placement) {
+    btn.style.display = "none";
+    btn.classList.remove("visible");
+    return;
+  }
+  btn.dataset.edge = edge;
+  btn.classList.add("visible");
+  // Center the 20×20 circle on the anchor box's midpoint (the edge for a zero-thickness box).
+  btn.style.display = "grid";
+  btn.style.left = `${placement.left + placement.width / 2}px`;
+  btn.style.top = `${placement.top + placement.height / 2}px`;
+  btn.style.translate = "-50% -50%";
+}
+
+/**
+ * Position the drop indicator box. `inside` → a dashed box over the reference rect; `top`/`bottom`
+ * → a thin horizontal line at the reference's top/bottom (full reference width, zero-height bar).
+ * The placement is already in overlay-local coords at scale=1 (D-2).
+ */
+function placeDropIndicator(
+  box: HTMLElement,
+  placement: OverlayPlacement | null,
+  edge: DropEdge,
+): void {
+  if (!placement) {
+    box.style.display = "none";
+    return;
+  }
+  box.style.display = "block";
+  box.style.left = `${placement.left}px`;
+  box.style.width = `${placement.width}px`;
+  if (edge === "inside") {
+    box.className = "canvas-drop-indicator inside";
+    box.style.top = `${placement.top}px`;
+    box.style.height = `${placement.height}px`;
+    return;
+  }
+  box.className = "canvas-drop-indicator line";
+  box.style.height = "";
+  box.style.top = `${edge === "top" ? placement.top : placement.top + placement.height}px`;
+}